Getting started with Gremlin’s API

Ana M Medina

Sr. Chaos Engineer

Last Updated: April 14, 2021

Categories: Chaos Engineering

Introduction

Gremlin is a simple, safe and secure service for running chaos experiments on a SaaS platform. It has an intuitive web-based interface that makes it easy to view your systems, design and run experiments, and see the status of ongoing experiments.

Once you’ve had experience running experiments through the web app, the next step is to automate your experiments. With the Gremlin API, you can perform actions in Gremlin through a REST-based API. This makes it easy to initiate attacks from another application (such as a CI/CD service) and automate your experiments. This tutorial will show you how to get started with the Gremlin API, including authenticating and running your first attack.

Overview

This tutorial will show you how to:

• Step 1: Retrieve the authorization token for the API
• Step 2: Run a chaos experiment using the API
• Step 3: Run a chaos experiment using the Gremlin API Examples
• Step 4: Verify the status of a chaos experiment using the API

Prerequisites

Before you begin this tutorial, you’ll need:

• A Gremlin account (request a free trial)
• A host running the Gremlin agent. You can use the Gremlin Playground to quickly create a virtual machine instance with the Gremlin agent pre-installed. For other options, see our installation documentation.

Step 1: Retrieve the authorization token for the API

Before we can use the API, we’ll need to authenticate our session by including an Authorization Header in each API call. This header includes a token that we need in order to authenticate with Gremlin. There are two ways to obtain an authorization token: either by authenticating as our Gremlin user by using our Gremlin credentials, or by creating an API key. We’ll look at both methods.

Authenticating using credentials

To log in using user credentials, we'll run the following command in a terminal. We'll replace the email, password, and companyName fields with our login email, password, and Gremlin company:

1curl -X POST --header 'Content-Type: application/x-www-form-urlencoded' \
2    --data-urlencode 'email=gremlin@gremlin.com' \
3    --data-urlencode 'password=MyPassword' \
4    --data-urlencode 'companyName=Chaos' \
5    'https://api.gremlin.com/v1/users/auth'

If you have MFA enabled, you’ll need to change the endpoint to /users/auth/mfa/auth and include the token from your password authenticator:

1curl -X POST --header 'Content-Type: application/x-www-form-urlencoded' \
2    --data-urlencode 'email=gremlin@gremlin.com' \
3    --data-urlencode 'password=MyPassword' \
4    --data-urlencode 'companyName=Chaos' \
5    --data-urlencode ‘token=000000’ \
6    'https://api.gremlin.com/v1/users/auth/mfa/auth'

This returns the following output. The header field contains the token that we’ll use. Since we belong to multiple teams, each team is included in the response. Each team uses a separate token, so we’ll need to find the right team by checking the org_name field. For example, here’s the output for the team "My Team":

1[
2  {
3    "company_id": "c96634ae-1100-5b91-9e99-1e40bb2fe656",
4    "company_is_alfi_enabled": true,
5    "expires_at": "2021-04-14T07:42:37.410Z",
6    "header": "Bearer MTZhY2RjZDEtMjIxYi01YjZjLThhN2EtYTgyOWFmN2ZjYmVhOmFuYW1tZWRpbmEyMUBnbWFpbC5jb206NTZlYzNmZTYtYjNiMC0xMWU5LWJhMzctMDI0MmQyMzAyY2Yy",
7    "identifier": "gremlin@gremlin.com",
8    "org_id": "16acdcd1-221b-5b6c-8a7a-a829af7fcbea",
9    "org_name": "My Team",
10    "renew_token": "3a354e60-56a2-4745-b54e-6056a2a74592",
11    "token": "56ec3fe6-b3b0-11e9-ba37-0242d2302cf2",
12    "tier": "Enterprise",
13    "company_name": "Chaos",
14    "last_login": "2021-04-13T19:42:37.381Z",
15    "roles": [...],
16    "privileges": [...]
17  }
18]

This gives us our new token:

Bearer MTZhY2RjZDEtMjIxYi01YjZjLThhN2EtYTgyOWFmN2ZjYmVhOmFuYW1tZWRpbmEyMUBnbWFpbC5jb206NTZlYzNmZTYtYjNiMC0xMWU5LWJhMzctMDI0MmQyMzAyY2Yy

We’ll need to format this as an HTTP Authorization header:

Authorization: Bearer MTZhY2RjZDEtMjIxYi01YjZjLThhN2EtYTgyOWFmN2ZjYmVhOmFuYW1tZWRpbmEyMUBnbWFpbC5jb206NTZlYzNmZTYtYjNiMC0xMWU5LWJhMzctMDI0MmQyMzAyY2Yy

We’ll also save the full header as an environment variable named $header for later use in this tutorial by running this command in a terminal:

1export header="Authorization: Bearer MTZhY2RjZDEtMjIxYi01YjZjLThhN2EtYTgyOWFmN2ZjYmVhOmFuYW1tZWRpbmEyMUBnbWFpbC5jb206NTZlYzNmZTYtYjNiMC0xMWU5LWJhMzctMDI0MmQyMzAyY2Yy"

Authenticating using API keys

With API keys, we can authenticate using service accounts instead of our own user account. To create an API key, we’ll open the Gremlin web app and navigate to the team settings page, then click the API Keys tab. If we have an API key that we want to reuse, we can click on the copy icon next to the key’s name in the API key list to copy the key to our clipboard:

To create a new API key, we’ll click New API Key. We’ll enter a name for the API Key and an optional description, then click Save. Now we can copy the value shown in the “API Key” field.

This gives us our new token:

f02868098b13e4f68da82b0c5e5c950ea750fce53c62d982cdab0c61099e5f98

We’ll format the full header containing the token and save it as an environment variable named $header for later use in this tutorial:

1export header="Authorization: Key f02868098b13e4f68da82b0c5e5c950ea750fce53c62d982cdab0c61099e5f98"

Step 2: Run a chaos experiment using the API

Now that we’ve authenticated, let’s run an attack. For this experiment, we’ll run a CPU attack on a random host for 120 seconds (2 minutes) utilizing 100% of all cores. In addition to the authorization header we created in step 1, we’ll also need our team ID. This is available in the Team Settings page, under the Configuration tab:

Now, we’ll run the following command in a terminal. We’ll replace your_team_id in the URL with our actual team ID.

1curl -X POST \
2    --header "Content-Type: application/json" \
3    --header "$header" \
4    --data '
5    {
6        "command": { "type": "cpu", "args": ["-c", "1", "--length", "120"] },
7        "target": { "type": "Random" }
8    }' \
9    'https://api.gremlin.com/v1/attacks/new?teamId=your_team_id'

The API will start the attack and return a unique execution ID. We can use this ID in other API requests, such as querying the status of an attack or halting an attack. Here’s an example of the response:

443bf563-21c7-11ea-b4dc-024221b6d1e6

Step 3: Run a chaos experiment using the Gremlin API Examples

Instead of creating each attack request by hand, we can also generate fully-formed API requests through the web app. This makes it easy to build a chaos experiment in the web app and simply copy the identical API calls to our REST API tool, terminal, CI/CD tool, or script. This also works for Scenarios.

As an example, we’ll recreate the same attack in the Gremlin web app. First, we’ll log into the Gremlin web app and create a new attack by clicking Attacks in the left nav bar, then click New Attack. We’ll select our host as the target, expand Choose a Gremlin, select Resource, then select CPU. We’ll change the length to 120 and set the CPU Capacity to 100.

Now, instead of clicking Unleash Gremlin, we’ll click Gremlin API Examples in the bottom right corner of the screen:

This opens the API pane, which contains a fully formatted request that we can run using curl. This also shows the endpoint URL, HTTP method, request headers, and request body. The Authorization drop-down toggles between bearer authentication and API key authentication.

This makes it easy to create readily-formatted API requests for attacks or Scenarios, and works for existing attacks as well as new attacks.

Step 4: Check the status of an experiment using the API

Once we have the execution ID, we can check the status of the attack by sending a GET request to the /attacks/execution_id endpoint. We’ll replace execution_id with the attack execution ID from step 2, and replace team_id in the URL with our actual team ID:

1curl -X GET "https://api.gremlin.com/v1/attacks/execution_id?teamId=team_id" \
2    --header "$token" \
3     -H "accept: application/json"

Here we can see the full details of the attack including the hosts it ran on (infra_target.resolvedHosts), the status (stage), and the attack configuration (attack_configuration). The attack already finished, and this is reflected in the response:

1{
2  "total_clients": 1,
3  "infra_target": {...},
4  "client_metrics_enabled_count": 1,
5  "attack_configuration": {...},
6  "target_type": "Host",
7  "version": 9,
8  "targets": ["gremlin-demo-lab-worker2"],
9  ...
10  "created_at": "2021-04-13T20:49:50.454Z",
11  "create_source": "Api",
12  "stage": "Successful",
13  "execution_stage_summary": {
14    "Successful": 1
15  },
16  "infra_command": {
17    "commandType": "CPU",
18    "commandArgs": {
19      "cores": 1,
20      "all_cores": false,
21      "length": 120,
22      "type": "cpu",
23      "percent": 100
24    }
25  },
26  "stage_lifecycle": "Complete",
27  "owning_team_id": "team_id",
28  "guid": "ca646b5d-9c99-11eb-81b5-0a4ea014d8f1",
29  "create_user": "Service account",
30  "start_time": "2021-04-13T20:49:50.444Z",
31  "end_time": "2021-04-13T20:52:11.021Z",
32  "updated_at": "2021-04-13T20:52:11.021Z",
33  "kind": "Api"
34}

Lastly, we can view this attack in the Gremlin web app by adding the execution ID to the following URL: https://app.gremlin.com/attacks/. For example, here’s our API-created attack in the web app (note that Gremlin shows the user who ran the attack as “Service account” and the type of attack as “API”):

Conclusion

Congrats! You’ve learned how to use the Gremlin API. To learn more about our API and what it’s capable of, check out our interactive API reference, or documentation. Here are some examples of how you can use our API to automate your chaos experiments and bring your Chaos Engineering practice to the next level:

• Add Chaos Engineering to your CI/CD pipeline using Jenkins
• Run chaos experiments alongside frontend tests
• Run Chaos Experiments alongside load testing with JMeter

To see how others are using the API, join the Chaos Engineering Slack community! Have fun exploring!