How to Install and Use Gremlin Locally with Docker For Mac

How to Install and Use Gremlin Locally with Docker For Mac

This installation guide will walk you through running Gremlin locally using Docker for Mac. You will also run a shutdown attack against an Nginx container.

Prerequisites

Step 1.0 - Install Docker For Mac

First you will need to install Docker For Mac if you do not yet have it on your local computer, follow the instructions provided by Docker.

Step 2.0 - Installing Gremlin

After you have created your Gremlin account (sign up here) you will need to find your Gremlin Daemon credentials. Login to the Gremlin App using your Company name and sign-on credentials. These were emailed to you when you signed up to start using Gremlin.

Navigate to Team Settings and click on your Team.

Store your Gremlin client credentials as environment variables, for example:

1export GREMLIN_TEAM_ID=3f242793-018a-5ad5-9211-fb958f8dc084
1export GREMLIN_TEAM_SECRET=eac3a31b-4a6f-6778-1bdb813a6fdc

Next run the Gremlin Daemon in a Container.

Use docker run to pull the official Gremlin Docker image and run the Gremlin daemon:

bash
1docker run -d --net=host \
2 --cap-add=NET_ADMIN --cap-add=SYS_BOOT --cap-add=SYS_TIME \
3 --cap-add=KILL \
4 -v $PWD/var/lib/gremlin:/var/lib/gremlin \
5 -v $PWD/var/log/gremlin:/var/log/gremlin \
6 -v /var/run/docker.sock:/var/run/docker.sock \
7 -e GREMLIN_TEAM_ID="$GREMLIN_TEAM_ID" \
8 -e GREMLIN_TEAM_SECRET="$GREMLIN_TEAM_SECRET" \
9 -e GREMLIN_BYPASS_USERNS_REMAP="$GREMLIN_BYPASS_USERNS_REMAP" \
10 gremlin/gremlin daemon

Use docker ps to see all running Docker containers:

bash
1sudo docker ps
1CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
2b281e749ac33 gremlin/gremlin "/entrypoint.sh daem…" 5 seconds ago Up 4 seconds relaxed_heisenberg

Step 3.0 - Create an NGINX container to attack

First we will create a directory for the html page we will serve using nginx:

bash
1mkdir -p ~/docker-nginx/html
2cd ~/docker-nginx/html

Create a simple HTML page:

bash
1vim index.html

Paste in this content:

1<html>
2 <head>
3 <title>Docker nginx tutorial</title>
4 <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/css/bootstrap.min.css" integrity="sha384-Gn5384xqQ1aoWXA+058RXPxPg6fy4IWvTNh0E263XmFcJlSAwiGgFAW/dAiS6JXm" crossorigin="anonymous">
5 </head>
6 <body>
7 <div class="container">
8 <h1>Hello it is your container speaking</h1>
9 <p>This nginx page was created by your Docker container.</p>
10 <p>Now it's time to create a Gremlin attack.</p>
11 </div>
12 </body>
13</html>

Create a container using the nginx Docker image:

bash
1sudo docker run -l service=nginx --name docker-nginx -p 80:80 -d -v ~/docker-nginx/html:/usr/share/nginx/html nginx

Make sure the docker-nginx container is running:

bash
1sudo docker ps
1CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
27167cacb2536 gremlin/gremlin "/entrypoint.sh daem…" 40 seconds ago Up 39 seconds practical_benz
3fb58b77e5ef8 nginx "nginx -g 'daemon of…" 10 minutes ago Up 10 minutes 0.0.0.0:80->80/tcp docker-nginx

Step 4.0 - Run A Gremlin Shutdown Attack

Now use the Gremlin CLI (gremlin) to run a Shutdown attack from within a Gremlin container:

bash
1sudo docker run -i --cap-add=NET_ADMIN -e GREMLIN_TEAM_ID="${GREMLIN_TEAM_ID}" -e GREMLIN_TEAM_CERTIFICATE_OR_FILE="${GREMLIN_TEAM_CERTIFICATE_OR_FILE}" -e GREMLIN_TEAM_PRIVATE_KEY_OR_FILE="${GREMLIN_TEAM_PRIVATE_KEY_OR_FILE}" -v /var/run/docker.sock:/var/run/docker.sock gremlin/gremlin attack-container docker-nginx shutdown

This attack will shutdown your Nginx container.

Conclusion

You now have Gremlin up and running locally, and you have validated its functionality against a running Nginx container.

Feel free to expand this to other container environments and have fun running Chaos Experiments!

Related

Avoid downtime. Use Gremlin to turn failure into resilience.

Gremlin empowers you to proactively root out failure before it causes downtime. See how you can harness chaos to build resilient systems by requesting a demo of Gremlin.

Get started
  • TechCrunch
  • Forbes
  • Business Insider
  • VentureBeat


© 2020 Gremlin Inc. San Jose, CA 95113