How to Install and Use Gremlin on CentOS 7¶
This tutorial walks through how to install Gremlin on CentOS 7 and run a CPU attack.
Before you begin, you’ll need:
- A CentOS 7 server
- A Gremlin account
Step 1 - Installing the Gremlin Daemon and CLI¶
First, ssh into your server and add the Gremlin RPM repository:
$ sudo curl https://rpm.gremlin.com/gremlin.repo -o /etc/yum.repos.d/gremlin.repo
Then install the Gremlin daemon and CLI:
sudo yum install -y gremlind gremlin
Step 2 - Validating the Install¶
Run the following command to confirm
gremlin has everything it needs to function:
Note: DO NOT run this command on production hosts
$ gremlin syscheck
The CLI will walk through its library of attack types and run some mock attacks:
Checking resource gremlins ... Checking CPU gremlin ... Attack on cpu_1 completed successfully CPU gremlin OK ...
The full syscheck may take a few minutes, so please be patient!
Step 3 - Configuring the Gremlin Daemon¶
The Gremlin daemon (
gremlind) connects to the Gremlin backend and waits for attack orders from you. When it receives attack orders, it uses the CLI (
gremlin) to run the attack.
gremlind to the Gremlin backend, you need your client credentials. (This is NOT the same as the email/password credentials you use to access the Gremlin Web App.) Read the Client Auth docs to see how to find your client credentials in the Web App.
With the credentials in hand, it’s time to configure the daemon. As with most daemons, you can configure
gremlind either by configuration file or environment variables. Let’s use the configuration file.
Add these configuration options to the daemon’s configuration file:
$ echo 'GREMLIN_TEAM_ID="<INSERT_YOUR_TEAM_ID>"' >> /etc/default/gremlind $ echo 'GREMLIN_TEAM_CERTIFICATE_OR_FILE="file:///var/lib/gremlin/gremlin.cert"' >> /etc/default/gremlind $ echo 'GREMLIN_TEAM_PRIVATE_KEY_OR_FILE="file:///var/lib/gremlin/gremlin.key"' >> /etc/default/gremlind
Then add your PEM-encoded certificate and key to two new filesâ€”
/var/lib/gremlin/gremlin.key, respectivelyâ€”and set the ownership and permissions on the files so that only
gremlind can access them:
$ sudo chown gremlin:gremlin /var/lib/gremlin/gremlin.* $ sudo chmod 600 /var/lib/gremlin/gremlin.*
Optionally, give the Gremlin daemon a custom ID so it’s easy to find in the Web App later:
$ echo 'GREMLIN_IDENTIFIER="my-first-gremlin-host"' >> /etc/default/gremlind
That’s enough configuration for this tutorial, but feel free to read about other configuration options in the Gremlin Docs.
Restart the daemon to apply the configuration changes:
$ sudo systemctl restart gremlind
Now you’re ready to run attacks using the Gremlin Web App.
Step 4 - Creating attacks using the Gremlin Control Panel¶
Login to the Gremlin Control Panel using your Company name and sign-on credentials. These details were emailed to you when you created your Gremlin account.
Example: The Hello World of Chaos Engineering (a CPU attack)¶
The Hello World of Chaos Engineering is the CPU Resource Attack. To create a CPU Resource Attack select Resource and then CPU in the dropdown menu.
The CPU Resource Attack will consume CPU resources based on the settings you select. The most popular default settings for a CPU Resource Attack are pre-selected, a default attack will utilize 1 core for 60 seconds. Before you can run the Gremlin attack you will need to click either Exact hosts to run the attack on or click the Random attack option.
Click Exact and select a Gremlin Client in the list.
On your server, run top to check the impact of the Gremlin Attack:
$ top top - 06:26:47 up 7 days, 7:00, 1 user, load average: 0.28, 0.07, 0.02 Tasks: 105 total, 1 running, 104 sleeping, 0 stopped, 0 zombie %Cpu(s): 79.7 us, 20.3 sy, 0.0 ni, 0.0 id, 0.0 wa, 0.0 hi, 0.0 si, 0.0 st KiB Mem : 1016120 total, 127140 free, 93956 used, 795024 buff/cache KiB Swap: 0 total, 0 free, 0 used. 712192 avail Mem PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND 23768 gremlin 20 0 13268 11136 3576 S 99.3 1.1 0:14.05 gremlin 23766 root 20 0 40388 3600 3072 R 0.3 0.4 0:00.03 top 1 root 20 0 37760 5760 3940 S 0.0 0.6 0:13.74 systemd 2 root 20 0 0 0 0 S 0.0 0.0 0:00.00 kthreadd 3 root 20 0 0 0 0 S 0.0 0.0 0:01.28 ksoftirqd/0 5 root 0 -20 0 0 0 S 0.0 0.0 0:00.00 kworker/0:0H 7 root 20 0 0 0 0 S 0.0 0.0 0:06.14 rcu_sched 8 root 20 0 0 0 0 S 0.0 0.0 0:00.00 rcu_bh 9 root rt 0 0 0 0 S 0.0 0.0 0:00.00 migration/0 10 root rt 0 0 0 0 S 0.0 0.0 0:04.09 watchdog/0
When your attack is complete it will move to Completed Attacks.
Step 5 - Halting a CPU resource attack using the Gremlin Control Panel¶
You’ve installed Gremlin on a server running CentOS 7 and validated that Gremlin works by running the Hello World of Chaos Engineering, the CPU Resource attack. You now possess tools that make it possible for you to explore additional Gremlin Attacks including attacks that impact State and Network.
Gremlin’s Developer Guide is a great resource and reference for using Gremlin to do Chaos Engineering. You can also explore the Gremlin Blog for more information on how to use Chaos Engineering with your application infrastructure.