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:
- Gather your credentials
- Create a Kubernetes secret from your Gremlin certificates
- Download and apply the Gremlin configuration manifest
- 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:
1kubectl 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:
1kubectl -n gremlin create secret generic gremlin-team-cert \2 --from-file=/path/to/gremlin.cert \3 --from-file=/path/to/gremlin.key
Download and apply the Gremlin configuration manifest
Next, we'll deploy the Gremlin configuration manifest.
Download the Gremlin configuration manifest by running the following:
bash1wget https://k8s.gremlin.com/resources/gremlin-conf.yamlOpen the file and update the following:
- Replace the following line with your team ID: "YOUR TEAM ID GOES HERE"
- 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.
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.
Apply the manifest by running the following command:
bash1kubectl 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:
1kubectl apply -f https://k8s.gremlin.com/resources/gremlin-client.yaml
If you are using secret-based authentication, run this command instead:
1kubectl 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:
1kubectl apply -f https://k8s.gremlin.com/resources/gremlin-chao.yaml
If you are using secret-based authentication, run this command instead:
1kubectl 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:
1kubectl get pods -n gremlin
This should list one Gremlin Agent for each node in your cluster, plus one Pod named chao
. For example, this is the output for a three-node cluster:
1kubectl get pods -n gremlin23NAME READY STATUS RESTARTS AGE4chao-78bbc7cbf6-9hn7q 1/1 Running 0 5d20h5gremlin-9r4t7 1/1 Running 0 5d20h6gremlin-bwmtz 1/1 Running 1 126d7gremlin-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.
1kubectl get pods -n gremlin23NAME READY STATUS RESTARTS AGE4chao-78bbc7cbf6-9hn7q 1/1 Running 0 5d20h5gremlin-c25ld 0/1 Pending 0 112d6gremlin-n5gt7 0/1 Pending 0 112d7gremlin-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, run the following command:
1kubectl delete namespace gremlin