Getting Started

Install Gremlin on Kubernetes manually

This section will guide you through installing the Gremlin Agent using only YAML files. We only recommend using this method if installing via Helm is not suitable for your use case.

Gremlin provides an automatically generated YAML file with everything needed to deploy Gremlin to your cluster. Deploying Gremlin is as easy as downloading this file and applying it using kubectl.

  1. Log into your Gremlin account and navigate to the Getting Started page.
  2. Under step 1 ("Install the Gremlin agent"), look for the link to download gremlin-k8s-installation.yaml . Click on this link to download the file.
  3. Optionally, to give your cluster a unique name, open the file, navigate to the "Chao" deployment, and change the value of spec.template.spec.containers.args."cluster_id" to your preferred cluster name. Otherwise, Gremlin will use a randomly generated value for the cluster name.
  4. On your workstation, open a terminal, navigate to the folder containing the YAML file, then run the following command:

kubectl apply -f gremlin-k8s-installation.yaml

Verify your installation

On the cluster, you can run the following command to check that the Gremlin Agent was installed properly:


kubectl get pods -n gremlin

This should list one Gremlin Agent for each node in your cluster, plus one Pod named <span class="code-class-name">chao</span>. For example, this is the output for a three-node cluster:


kubectl get pods -n gremlin

NAME                    READY   STATUS    RESTARTS   AGE
chao-78bbc7cbf6-9hn7q   1/1     Running   0          5d20h
gremlin-9r4t7           1/1     Running   0          5d20h
gremlin-bwmtz           1/1     Running   1          126d
gremlin-bx6dn           1/1     Running   0          5d20h

The following example shows 2 pending pods, which means the installation is incomplete. Contact your cluster administrator to debug why Gremlin is unable to run on those nodes.


kubectl get pods -n gremlin

NAME                    READY   STATUS    RESTARTS   AGE
chao-78bbc7cbf6-9hn7q   1/1     Running   0          5d20h
gremlin-c25ld           0/1     Pending   0          112d
gremlin-n5gt7           0/1     Pending   0          112d
gremlin-zn4kq           1/1     Running   0          126d

Gremlin can only target cluster resources on nodes that have a Gremlin Agent running on them. If you run a test that targets a resource on a node without a Gremlin Agent, the test will report an error. If Chao is not running, you won't be able to target cluster resources at all.

If you need additional troubleshooting help, see Gremlin Agent in the Gremlin Knowledge Base.

Uninstalling Gremlin from Kubernetes

To uninstall Gremlin from a Kubernetes cluster using YAML, simply delete the gremlin namespace by running the following command:


kubectl delete namespace gremlin
No items found.
This is some text inside of a div block.
Installing the Gremlin Agent
Authenticating the Gremlin Agent
Configuring the Gremlin Agent
Managing the Gremlin Agent
Health Checks
Command Line Interface
Updating Gremlin
Reliability Management (RM) Quick Start Guide
Services and Dependencies
Detected Risks
Reliability Tests
Reliability Score
Deploying Failure Flags on AWS Lambda
Deploying Failure Flags on AWS ECS
Deploying Failure Flags on Kubernetes
Classes, methods, & attributes
API Keys
Container security
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
Latency Experiment
Memory Experiment
Network Tags
New Relic Health Check
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
Time Travel Experiment
Troubleshooting Gremlin on OpenShift
User Authentication via SAML and Okta
Managing Users and Teams
Integration Agent for Linux
Test Suites
Restricting Testing Times
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