Dashboard
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.

The steps for deploying to Kubernetes using pure YAML are:

  1. Gather your credentials
  2. Create a Kubernetes secret from your Gremlin certificates
  3. Download and apply the Gremlin configuration manifest
  4. Verify your installation

Gather your credentials

All Gremlin integration installations require you to use one of Gremlin's authentication methods. With Kubernetes, 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.

First, retrieve your Team ID from your team settings page. Next, 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.

Create a Kubernetes secret from your Gremlin certificates

Now that we have our credentials, let's create a Kubernetes Secret to store them securely.

First, we'll create a new namespace for our deployment:

SHELL

kubectl create namespace gremlin

Next, we'll create the secret. Replace "/path/to/gremlin.cert" and "/path/to/gremlin.key" with the actual filepath to your Gremlin certificate and key file, respectively:

SHELL

kubectl -n gremlin create secret generic gremlin-team-cert \
   --from-file=/path/to/gremlin.cert \
   --from-file=/path/to/gremlin.key

Download and apply the Gremlin configuration manifest

Next, we'll deploy the Gremlin configuration manifest.

  1. Download the Gremlin configuration manifest by running the following:
    BASH
    
    wget https://k8s.gremlin.com/resources/gremlin-conf.yaml
    
  2. Open the file and update the following:
    1. Replace the following line with your team ID: "YOUR TEAM ID GOES HERE"
    2. If you're using certificate-based authentication, remove the line starting with "GREMLIN_TEAM_SECRET". Otherwise, replace "YOUR TEAM SECRET GOES HERE" with your actual secret.
  3. Replace the following with a unique name for your cluster: "YOUR UNIQUE CLUSTER NAME GOES HERE". This name will make it easier to identify your cluster in the Gremlin web app.
  4. Apply the manifest by running the following command:
    BASH
    
    kubectl apply -f /path/to/gremlin-conf.yaml
    

Download and apply the Gremlin client manifest

Next, we'll deploy the actual Gremlin Agent. This deploys a DaemonSet that will run a single instance of the Gremlin Agent on each node in your cluster.

If you are using certificate-based authentication, run the following command:

BASH

kubectl apply -f https://k8s.gremlin.com/resources/gremlin-client.yaml

If you are using secret-based authentication, run this command instead:

BASH

kubectl apply -f https://k8s.gremlin.com/resources/gremlin-client-secret.yaml

Download and apply the K8s client (Chao) manifest

Last, we'll deploy the Chao client. This deploys a single Pod that handles communication between your Kubernetes cluster and Gremlin.

If you are using certificate-based authentication, run the following command:

BASH

kubectl apply -f https://k8s.gremlin.com/resources/gremlin-chao.yaml

If you are using secret-based authentication, run this command instead:

BASH

kubectl apply -f https://k8s.gremlin.com/resources/gremlin-chao-secret.yaml

Verify your installation

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

BASH

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:

SHELL

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.

SHELL

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

Note
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, run the following command:

BASH

kubectl delete namespace gremlin
No items found.
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
User Management
Integrations
Health Checks
Notifications
Command Line Interface
Updating Gremlin
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
Alfi
Additional Configuration for Helm
Amazon CloudWatch Health Check
AppDynamics Health Check
Application Level Fault Injection (ALFI)
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
Role Based Access Control
Running Failure Flags experiments
Scheduling Scenarios
Shared Scenarios
Shutdown Experiment
Slack
Teams
Time Travel Experiment
Troubleshooting Gremlin on OpenShift
User Authentication via SAML and Okta
Users
Webhooks
Integration Agent for Linux
Test Suites
Restricting Testing Times
Reports
Enabling DNS collection