Getting Started

Installing Gremlin on Kubernetes with Helm

The Gremlin Helm Chart is the recommended way to install the Gremlin Agent on Kubernetes. If you want to install Gremlin using just <span class="code-class-custom">kubectl</span> and pure YAML, see Install Gremlin on Kubernetes manually.

These instructions are for Helm v3 and later. Helm v2 is no longer supported.

The steps for deploying to Kubernetes with Helm are:

  1. Gather your credentials
  2. Deploy the Helm chart
  3. Additional configuration
  4. Verify your installation

Gather your credentials

All Gremlin integration installations require you to use one of Gremlin's authentication methods. With Helm, you can use either signature (i.e. certificate)-based authentication or secret authentication. Secret-based authentication is easier to implement, but we recommend using certificate-based authentication. We'll show both methods in this guide.

First, retrieve your Team ID from your team settings page. Next, if you're using secret-based authentication, create a new secret, copy the secret to a text file (or keep the pop-up open), then continue to the next step.

If you're using certificate-based authentication, generate a new certificate pair, or download an existing certificate pair if one exists. Unzip the folder containing your certificates, then continue to the next step.

Deploy the Helm chart

Now that we have our credentials, let's add the Gremlin Helm repo and create a new namespace for our deployment:


helm repo add gremlin https://helm.gremlin.com/
kubectl create namespace gremlin

Now we'll deploy the Chart. With this command, your team ID and secrets/certificates are passed directly to the Helm Chart. If you'd prefer to manage these secrets outside of Helm, see our Helm Chart documentation.

Make sure to set the values of gremlin.secret.teamID, gremlin.secret.clusterID, gremlin.secret.certificate, and gremlin.secret.key to your actual Gremlin team ID, cluster ID, path to the certificate file, and path to the key file respectively.

For secret-based authentication:


helm install gremlin gremlin/gremlin \
    --namespace gremlin \
    --set      gremlin.secret.type=secret \
    --set      gremlin.secret.managed=true \
    --set      gremlin.hostPID=true \
    --set      gremlin.secret.teamID=YourGremlinTeamID \
    --set      gremlin.secret.clusterID=YourGremlinClusterID \
    --set      gremlin.secret.teamSecret=YourGremlinTeamSecret

For certificate-based authentication:


helm install gremlin gremlin/gremlin \
    --namespace gremlin \
    --set      gremlin.secret.type=certificate \
    --set      gremlin.secret.managed=true \
    --set      gremlin.hostPID=true \
    --set      gremlin.secret.teamID=YourGremlinTeamID \
    --set      gremlin.secret.clusterID=YourGremlinClusterID \
    --set-file gremlin.secret.certificate=/path/to/gremlin.cert \
    --set-file gremlin.secret.key=/path/to/gremlin.key

Additional configuration

The Helm Chart includes several additional options for customizing to your environment. These options include:

  • Specifying a container driver (Gremlin will try to auto-detect the current driver, but you can also tell Gremlin to use a specific driver).
  • Enabling Gremlin on the Kubernetes Master so you can run tests on the Kubernetes Control Plane.
  • Enabling AppArmor support for clusters that use AppArmor.
  • Installing Gremlin's custom PodSecurityPolicy or seccomp policy for restrictive clusters.
  • Configuring Gremlin to use a proxy.
  • Allowing multiple Gremlin teams to target specific namespaces.
  • Allow adding arbitrary environment variables.
  • Allow adding arbitrary annotations to Kubernetes service account.

These are optional and are only necessary if Gremlin doesn't run using the default options. To learn more, see the Additional Configuration for Helm docs.

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-custom">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 with Helm

To uninstall Gremlin via Helm, run the following commands:


helm uninstall gremlin -n gremlin
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
User Management
Health Checks
Command Line Interface
Updating Gremlin
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
Role Based Access Control
Running Failure Flags experiments
Scheduling Scenarios
Shared Scenarios
Shutdown Experiment
Time Travel Experiment
Troubleshooting Gremlin on OpenShift
User Authentication via SAML and Okta
Integration Agent for Linux
Test Suites
Restricting Testing Times
Process Exhaustion Experiment
Enabling DNS collection