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)
| Metric | Agent Idle |
|---|---|
| CPU | < 0.10% |
| Resident Memory | ~17 MiB |
| Storage on disk | ~35 MiB |
Linux Host DIY
May require elevated privileges
| Metric | Source |
|---|---|
| CPU | top |
| Resident Memory | pmap <pid> |
| Storage on disk | du -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
| Metric | Agent Idle |
|---|---|
| CPU | < 0.07% |
| Resident Memory | ~752 KiB |
| Container Size | ~9 KiB |
| Image Size | ~616 MiB |
Docker DIY
May require elevated privileges
| Metric | Source |
|---|---|
| CPU | docker stats |
| Resident Memory | docker stats |
| Container Size | docker system df -v |
| Image Size | docker 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)
| Metric | Agent 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.
| Metric | Source |
|---|---|
| CPU | typeperf "\Process(gremlind)\% Processor Time" |
| Resident Memory | typeperf "\Process(gremlind)\Working Set Peak" |
| Storage on disk | dir "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:
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:
| Variable | Default | Description |
|---|---|---|
| GREMLIN_INSTALL_USER | gremlin | The Linux user to own all file installed by Gremlin. This user is created if it does not exist |
| GREMLIN_INSTALL_GROUP | gremlin | The Linux group to own all file installed by Gremlin. This group is created if it does not exist |
| GREMLIN_INSTALL_BIN_MODE | 6111 | The file mode for executable files installed by Gremlin. |