Infrastructure Layer

Installation

Gremlin must be installed on each host you wish to attack. In order for your hosts (and containers within the hosts) to be targetable, the installed gremlin must be registered with the Gremlin Control Plane.

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.

General steps deploying to Virtual Machine:

Get credentials - Team ID with secret or certificates
Install Gremlin packages: gremlin and gremlind
Register to the Control Plane

General steps deploying to Kubernetes:

Get Credentials - Team ID with secret or certificates
Create Kubernetes secret
Deploy Helm Chart

Virtual Machine

Before installing look at our caveats page to see if there are additional steps needed for your distribution during installation.

Ubuntu, Debian, etc.

For DEB-based Linux distributions (DEB packages)

bash

1# Add packages needed to install and verify gremlin (already on many systems)
2sudo apt update && sudo apt install -y apt-transport-https dirmngr
3
4# Add the Gremlin repo
5echo "deb https://deb.gremlin.com/ release non-free" | sudo tee /etc/apt/sources.list.d/gremlin.list
6
7# Import the GPG key
8sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 9CDB294B29A5B1E2E00C24C022E8EF3461A50EF6
9
10# Install Gremlin client and daemon
11sudo apt update && sudo apt install -y gremlin gremlind

List older versions of gremlin via: apt list -a gremlin and install them via apt install gremlin=x.x.x-x

Amazon Linux, RHEL, CentOS, etc.

For RPM-based Linux distributions (RPM packages)

bash

1# Install dependencies
2sudo yum install -y iproute-tc
3
4# Add the Gremlin repo
5sudo curl https://rpm.gremlin.com/gremlin.repo -o /etc/yum.repos.d/gremlin.repo
6
7# Install Gremlin client and daemon
8sudo yum install -y gremlin gremlind

List older versions of gremlin via: yum list available gremlin --showduplicates and install them via yum install gremlin-x.x.x-x

Docker Image

Alternatively, instead of installing Gremlin directly on the host operating system, you can deploy Gremlin from the Docker image on DockerHub.

For gremlind to attack Docker containers, you need to add the gremlin user to the docker group after installing Gremlin and Docker.

bash

1sudo adduser gremlin docker

Kubernetes

Gremlin allows targeting objects within your Kubernetes clusters. After selecting a cluster, you can filter the visible set of objects by selecting a namespace. Select any of your Deployments, ReplicaSets, StatefulSets, DaemonSets, or Pods. When one object is selected, all child objects will also be targeted. For example, when selecting a DaemonSet, all of the pods within will be selected.

Only parent Kubernetes objects are available to target. Pods will be listed only if they don't belong to a Set or Deployment.

Installation

In addition to the Gremlin client that is installed on the host, or node, of a Kubernetes cluster, you must also install the Gremlin Kubernetes client to the cluster. The Kubernetes client can be installed either using kubectl or helm. Both methods are outlined here.

Create a Kubernetes secret from Gremlin certificates

A Kubernetes secret is different from the secret used for secret-based Gremlin authentication. If you are using secret-based authentication, you can skip this step.

Download the Gremlin certificates (you need at least team manager access)
Unzip certificates.zip
Rename the files in the certificates folder. Team Name.pub_cert.pem becomes gremlin.cert. Team Name.priv_key.pem becomes gremlin.key.
Create a gremlin namespace: kubectl create namespace gremlin
Create a kubernetes secret by running the following:
kubectl -n gremlin create secret generic gremlin-team-cert --from-file=/path/to/gremlin.cert --from-file=/path/to/gremlin.key

kubectl

Download and apply the Gremlin configuration manifest

Download the Gremlin configuration manifest by running the following:
wget https://k8s.gremlin.com/resources/gremlin-conf.yaml
Open the file and update the following:
- Replace the following line with your team ID: "YOUR TEAM ID GOES HERE"
- Replace the following line with your team secret: "YOUR TEAM SECRET GOES HERE" (If you are using certificate-based authentication, remove this line.)
- Replace the following line with a string that you will use to identify your cluster: "YOUR UNIQUE CLUSTER NAME GOES HERE"
Apply the manifest with this command: kubectl apply -f /path/to/gremlin-conf.yaml

Download and apply the Gremlin client manifest

If you are using certificate-based authentication:

Download and apply the gremlin client manifest for your kubernetes cluster by running the following:
kubectl apply -f https://k8s.gremlin.com/resources/gremlin-client.yaml

If you are using secret-based authentication:

Download and apply the gremlin client manifest for your kubernetes cluster by running the following:
kubectl apply -f https://k8s.gremlin.com/resources/gremlin-client-secret.yaml

Download and apply the K8s client manifest

If you are using certificate-based authentication:

Download and apply the k8s client manifest by running:
kubectl apply -f https://k8s.gremlin.com/resources/gremlin-chao.yaml

If you are using secret-based authentication:

Download and apply the k8s client manifest by running:
kubectl apply -f https://k8s.gremlin.com/resources/gremlin-chao-secret.yaml

Helm

Let Gremlin know your Gremlin team ID and your Kubernetes cluster name

bash

1GREMLIN_TEAM_ID="changeit"
2GREMLIN_CLUSTER_ID="changeit"

Add the Gremlin helm chart

bash

1helm repo remove gremlin
2helm repo add gremlin https://helm.gremlin.com

Create a namespace for the Gremlin Kubernetes client

bash

1kubectl create namespace gremlin

Install the Gremlin Kubernetes client

shell

1helm install gremlin/gremlin \
2    --name gremlin \
3    --namespace gremlin \
4    --set gremlin.secret.managed=true \
5    --set gremlin.secret.type=secret \
6    --set gremlin.secret.teamID=$GREMLIN_TEAM_ID \
7    --set gremlin.secret.clusterID=$GREMLIN_CLUSTER_ID \
8    --set gremlin.secret.teamSecret=$GREMLIN_TEAM_SECRET

The Gremlin helm chart also supports certificate-based authentication, and manually managed Kubernetes secrets, as well as several other configuration options. For the most complete, up-to-date instructions for installing from the Gremlin helm chart, see the README.

Running an attack

Once you select the Kubernetes objects to be targeted, select and configure your desired Gremlin attack. When the attack is run, the underlying containers within the objects selected will be impacted.

Containers share resources with their hosts. Running resource attacks on Kubernetes objects will impact the hosts where the targeted containers are running, including the host's full set of containers.

ECS, Swarm, Mesos

Additional installation tutorials are available in our community site.

Windows

For Microsoft Windows run the following from an elevated command prompt.

PowerShell

1msiexec /quiet /package https://windows.gremlin.com/installer/latest/gremlin_installer.msi

After installation, you need to authenticate the agent.

After Installation

After installation, the next step is to authenticate the agent with the Gremlin Control Plane. See Authentication for more information.

For additional configuration options, such as using the Gremlin configuration file and environment variables, see Advanced Configuration.

Previous Next