Getting Started

Installing Gremlin

The Gremlin Agent interacts with your stack to test its reliability and inject failure in a thoughtful, controlled manner. It must be installed on each host you wish to test and then registered with the Gremlin Control Plane. Then you can target hosts and containers within the hosts with reliability tests and scenarios from the Gremlin web app, API, or CLI.

Gremlin can be deployed into bare-metal environments running either Linux or Windows, into container-based infrastructure environments running on Linux, and into virtual infrastructure environments.

Environment-specific instructions

For installation instructions, visit the page specific to the environment you are working with:

Advanced configuration

You can configure the Gremlin Agent with a configuration file or with environment variables. See Advanced configuration for more information.

Client overhead

The Gremlin Agent that runs on the client requires very little overhead. Here are the needs in a couple of sample use cases.

Note: For information about network bandwidth usage by the Gremlin Daemon, refer to Bandwidth usage.

Linux single-task host

The Gremlin Agent has very low performance overhead on a classic, single-task host. Our benchmarks for this type of host are based on an Amazon EC2 t2.micro:

  • vCPUs: 1 vCPUs
  • Memory: 1 GiB
  • Operating System: Ubuntu 16.04 LTS (Debian agent instructions found here)
MetricAgent Idle
CPU< 0.10%
Resident Memory~17 MiB
Storage on disk~35 MiB

Linux Host DIY

May require elevated privileges

MetricSource
CPUtop
Resident Memorypmap <pid>
Storage on diskdu -sh */* \| grep gremlin or during installation

Linux Docker host

The Gremlin Agent has very low performance overhead on a host running Docker, with exact usage depending on the number of Docker containers your machine hosts, and whether those processes are long- or short-lived. Our benchmarks for this type of host are based on an Amazon EC2 t2.micro:

  • vCPUs: 1 vCPUs
  • Memory: 1 GiB
  • Operating system: Ubuntu 16.04 LTS
  • Docker Client Version: 19.03.5-ce
  • Docker Engine Version: 19.03.5-ce
  • Number of containers: 1 container

For this type of Docker host, typical usage is

MetricAgent Idle
CPU< 0.07%
Resident Memory~752 KiB
Container Size~9 KiB
Image Size~616 MiB

Docker DIY

May require elevated privileges

MetricSource
CPUdocker stats
Resident Memorydocker stats
Container Sizedocker system df -v
Image Sizedocker system df -v

Windows single-task host

The Gremlin Agent has very low performance overhead on a classic, single-task host. Our benchmarks for this type of host are based on an Amazon EC2 t2.micro:

  • vCPUs: 1 vCPUs
  • Memory: 1 GiB
  • Operating System: Windows Server 2019 Datacenter (Windows agent instructions found here)
MetricAgent Idle
CPU< 0.10%
Resident Memory~23 MiB
Storage on disk~21 MiB

Windows host DIY

The typeperf commands in the table below output each second. The -si option can be used to average over longer time periods. For example, -si 29:00 averages over 29 minutes.

Multiple typeperf counters can be included; just seperate them with a space.

MetricSource
CPUtypeperf "\Process(gremlind)\% Processor Time"
Resident Memorytypeperf "\Process(gremlind)\Working Set Peak"
Storage on diskdir "C:\Program Files\Gremlin" /s

Other considerations

Customize Gremlin's Linux user and group

By default on Linux, Gremlin installs a gremlin Linux user and group, and sets the suid bit on /usr/bin/gremlin so that all users can run the Gremlin executable. These defaults can be overridden at installation time by supplying environment variables to the installer.

For example, to run Gremlin as root and restrict executable access to root:root, you would run:

shell
1GREMLIN_INSTALL_USER=root GREMLIN_INSTALL_GROUP=root GREMLIN_INSTALL_BIN_MODE=0770 \
2 sudo -E yum install gremlin gremlind

The full list of variables available at install time, and their defaults are as follows:

VariableDefaultDescription
GREMLIN_INSTALL_USERgremlinThe Linux user to own all file installed by Gremlin. This user is created if it does not exist
GREMLIN_INSTALL_GROUPgremlinThe Linux group to own all file installed by Gremlin. This group is created if it does not exist
GREMLIN_INSTALL_BIN_MODE6111The file mode for executable files installed by Gremlin.