Dashboard
Getting Started

Compatibility

The following matrices show the operability of Gremlin on various platforms. Following the compatibility matrices is a list of caveats for installing Gremlin on specific operating systems. At times Gremlin cannot be installed directly on an operating system due to mitigating factors such as dependency issues. In these instances, the matrix shows whether another means of deployment is available and has been tested, such as Docker. Note that you should always apply the latest software updates before installing Gremlin.

Linux

You can install Gremlin directly on these Linux distributions.

Distro Version CPU Disk IO Memory Process
Killer
Shut
down
Time
Travel
Black
hole
DNS Latency Packet
Loss
Ubuntu 14.04+ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️
Debian 7+ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️
Red Hat 6.7+ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️
CENTOS 6.9+ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️
Fedora 27+ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️
SUSE 12+ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️
AWS AL1/2 ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️

Containers and orchestration platforms

Gremlin natively supports Kubernetes, OpenShift, Docker, and many standard container runtimes.

Distro Version CPU Disk IO Memory Process
Killer
Shut
down
Time
Travel
Black
hole
DNS Latency Packet
Loss
Docker 17.12.1-ce ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️
Cri-O 1.17.1 ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️
Containerd 1.2.13 ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️
Fedora Atomic ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️
Alpine 3.7 ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️
Photon 1+ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️
CoreOS 1649.0.0+ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️
FreeBSD 10.4+ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️
Kubernetes
(K8s)
1.6+ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️
Flatcar 2605.12.0+ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️
OpenShift 4+ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️

Windows

Gremlin supports the following versions of Microsoft Windows:

Windows Version CPU Disk IO Memory Process
Killer
Shut
down
Time
Travel
Black
hole
DNS Latency Packet
Loss
Server 2008 R2 and later ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️
Windows 7 and later ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️

Cloud platforms

Gremlin is designed to work on any cloud platform that provides Linux or Windows-based hosts. Gremlin has been tested on these platforms:

Platform CPU Disk IO Memory Process
Killer
Shut
down
Time
Travel
Black
hole
DNS Latency Packet
Loss
GCP ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️
AWS ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️
Azure ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️

Caveats

Some platforms have limitations or require additional configuration. These caveats are listed below.

Ubuntu

The dependency apt-transport-https must be installed:

BASH

sudo apt install apt-transport-https

Debian

The following dependencies must be installed:

  • apt-transport-https
  • dirmngr (Debian 9)
BASH

sudo apt install apt-transport-https dirmngr

SUSE

The dependency libcap-progs must be installed:

BASH

sudo zypper install libcap-progs

Amazon Linux 2

The dependency iproute-tc must be installed:

BASH

sudo yum install iproute-tc

RHEL 8

The dependency kernel-modules-extra must be installed:

BASH

sudo dnf install kernel-modules-extra

Fedora Atomic

Latency and Packet Loss experiments do not succeed due to an unavailable dependency:

  • Tc Error: RTNETLINK answers: No such file or directory

Google Container Optimized OS (COS)

When running network experiments, Gremlin recommends using the latest version of COS. Prior versions of COS did not include kernel modules necessary to apply network impacts. For GKE users, the following minimum versions are recommended:

  • 1.15.9-gke.17+
  • 1.16.6-gke.5+

Windows

Azure Windows instances may throttle disk I/O such that large disk experiments will take an excessive amount of time to complete.

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 Agent, 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

Installing Gremlin

Once you've verified compatability, continue to Installing Gremlin to start the installation process.

No items found.
Next
Previous
This is some text inside of a div block.
Compatibility
Installing the Gremlin Agent
Authenticating the Gremlin Agent
Configuring the Gremlin Agent
Managing the Gremlin Agent
Integrations
Health Checks
Notifications
Command Line Interface
Updating Gremlin
Reliability Management (RM) Quick Start Guide
Services and Dependencies
Detected Risks
Reliability Tests
Reliability Score
Targets
Experiments
Scenarios
GameDays
Overview
Deploying Failure Flags on AWS Lambda
Deploying Failure Flags on AWS ECS
Deploying Failure Flags on Kubernetes
Classes, methods, & attributes
API Keys
Examples
Container security
General
Linux
Windows
Chao
Helm
Glossary
Additional Configuration for Helm
Amazon CloudWatch Health Check
AppDynamics Health Check
Blackhole Experiment
CPU Experiment
Certificate Expiry
Custom Health Check
Custom Load Generator
DNS Experiment
Datadog Health Check
Disk Experiment
Dynatrace Health Check
Grafana Cloud Health Check
Grafana Cloud K6
IO Experiment
Install Gremlin on Kubernetes manually
Install Gremlin on OpenShift 4
Installing Gremlin on AWS - Configuring your VPC
Installing Gremlin on Kubernetes with Helm
Installing Gremlin on Windows
Installing Gremlin on a virtual machine
Installing the Failure Flags SDK
Jira
Latency Experiment
Memory Experiment
Network Tags
New Relic Health Check
Overview
Overview
Overview
Overview
Overview
Packet Loss Attack
PagerDuty Health Check
Preview: Gremlin in Kubernetes Restricted Networks
Private Network Integration Agent
Process Collection
Process Killer Experiment
Prometheus Health Check
Configuring Role Based Access Control (RBAC)
Running Failure Flags experiments
Scheduling Scenarios
Shared Scenarios
Shutdown Experiment
Slack
Time Travel Experiment
Troubleshooting Gremlin on OpenShift
User Authentication via SAML and Okta
Managing Users and Teams
Webhooks
Integration Agent for Linux
Test Suites
Restricting Testing Times
Reports
Process Exhaustion Experiment
Enabling DNS collection
Authenticating Users with Microsoft Entra ID (Azure Active Directory) via SAML
AWS Quick Start Guide
Installing Gremlin on Amazon ECS
Experiments Revamp