Getting Started

Installing Gremlin on Amazon ECS

Gremlin supports Amazon Elastic Container Service (ECS) using our container agent. This document will walk you through deploying the Gremlin container to your ECS deployment.

Gremlin only works on EC2-backed ECS. For Fargate-backed ECS, please use Failure Flags.

To get the most from this installation guide, you should also be familiar with installing Gremlin as a container. You can reference Installing Gremlin in a Docker Container for help.

Step 1: Create the task definition

  1. Use this link to download the JSON task definition. In a text editor, replace my-team-id, my-team-secret, and my-aws-account with your Gremlin team ID, Gremlin secret, and AWS account ID, respectively.
  2. Review the Task Definition's limits and CPU architecture values to ensure they match your target environment.
  3. In the AWS management Console, navigate to Task Definitions and choose Create New Task Definition with JSON.
  4. Paste the contents of your task definition into the JSON field, then click Create.

Step 2: Create the daemon service definition

  1. In the AWS Management Console, navigate to Clusters in ECS.
  2. Select the cluster you want to deploy Gremlin to.
  3. On the Services tab, click Create.

On the Configure Services page, set the parameters as follows:

  1. Select the Launch Type compute option.
  2. Select the EC2 launch type.
  3. Select the Service application type.
  4. Set Task Definition → Family to “gremlin”.
  5. Set Task Definition → Revision to “latest”.
  6. Set Service Type to DAEMON.
  7. Click Create to create the service.

Verifying the installation

To verify that Gremlin is properly installed and running:

  1. In the AWS management Console, navigate to Clusters.
  2. Select the cluster you just deployed Gremlin into.
  3. On the Services tab, you should now see the Gremlin service.
  4. Verify that Desired tasks matches the number of ECS hosts in your cluster
  5. Verify that Running tasks matches the number of Desired tasks. Note that it can take several minutes for the ECS scheduler to launch Gremlin to full capacity.
  6. Once the Gremlin service is running at full capacity, navigate to https://app.gremlin.com/clients/. You can search via the tag platform=ecs to verify that the Gremlin control plane can see the freshly launched ECS daemons.
  7. Navigate to https://app.gremlin.com/attacks/new and click on the Containers tab.
  8. Verify that you are seeing the application containers and tags currently running on your ECS cluster.

Additional ECS configuration options

There are some advanced options that change how Gremlin interacts with ECS:

  • networkMode: This option determines which network space we would like to affect. For example, setting it to awsvpc means the task can only affect the awsvpc interface. Some other options are: host, bridge, or none. By default, this value is set to host. For more information, please consult the AWS guide on network mode.
  • pidMode: This parameter allows you to configure the container to share their process ID with either the host or other containers in the task. It may prove useful when performing process killer attacks to set this parameter to host. By default, this value is set to host. For more information, please consult the AWS guide on PID mode.
No items found.
This is some text inside of a div block.
Installing the Gremlin Agent
Authenticating the Gremlin Agent
Configuring the Gremlin Agent
Managing the Gremlin Agent
Health Checks
Command Line Interface
Updating Gremlin
Reliability Management (RM) Quick Start Guide
Services and Dependencies
Detected Risks
Reliability Tests
Reliability Score
Deploying Failure Flags on AWS Lambda
Deploying Failure Flags on AWS ECS
Deploying Failure Flags on Kubernetes
Classes, methods, & attributes
API Keys
Container security
Additional Configuration for Helm
Amazon CloudWatch Health Check
AppDynamics Health Check
Blackhole Experiment
CPU Experiment
Certificate Expiry
Custom Health Check
Custom Load Generator
DNS Experiment
Datadog Health Check
Disk Experiment
Dynatrace Health Check
Grafana Cloud Health Check
Grafana Cloud K6
IO Experiment
Install Gremlin on Kubernetes manually
Install Gremlin on OpenShift 4
Installing Gremlin on AWS - Configuring your VPC
Installing Gremlin on Kubernetes with Helm
Installing Gremlin on Windows
Installing Gremlin on a virtual machine
Installing the Failure Flags SDK
Latency Experiment
Memory Experiment
Network Tags
New Relic Health Check
Packet Loss Attack
PagerDuty Health Check
Preview: Gremlin in Kubernetes Restricted Networks
Private Network Integration Agent
Process Collection
Process Killer Experiment
Prometheus Health Check
Configuring Role Based Access Control (RBAC)
Running Failure Flags experiments
Scheduling Scenarios
Shared Scenarios
Shutdown Experiment
Time Travel Experiment
Troubleshooting Gremlin on OpenShift
User Authentication via SAML and Okta
Managing Users and Teams
Integration Agent for Linux
Test Suites
Restricting Testing Times
Process Exhaustion Experiment
Enabling DNS collection
Authenticating Users with Microsoft Entra ID (Azure Active Directory) via SAML
AWS Quick Start Guide
Installing Gremlin on Amazon ECS