Getting Started > Installing Gremlin on Amazon ECS

Installing Gremlin on Amazon ECS

Supported platforms:

N/A

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.

Note

The agent 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

Copy the JSON task definition from the code block at the end of this step. In a text editor, replace YOUR_TEAM_ID with your Gremlin team ID, YOUR_TEAM_SECRET with your Gremlin team secret and YOUR_GREMLIN_AGENT_VERSION with the agent version you wish to use.
1. For logging, set YOUR_LOG_GROUP_NAME and YOUR_REGION to the CloudWatch log group and region you wish to use, respectively.
2. For privileges, set YOUR_TASK_EXECUTION_ROLE to the ARN of the task execution role you wish to use, and YOUR_TASK_ROLE to the ARN of the task IAM role you wish to use.
Review the Task Definition's limits and CPU architecture values to ensure they match your target environment.
In the AWS management Console, navigate to Task Definitions and choose Create New Task Definition with JSON.
Paste the contents of your task definition into the JSON field, then click Create.

YAML


{
    "compatibilities": [
        "EXTERNAL",
        "EC2",
        "MANAGED_INSTANCES"
    ],
    "containerDefinitions": [
        {
            "command": [
                "daemon"
            ],
            "cpu": 0,
            "environment": [
                {
                    "name": "GREMLIN_TEAM_SECRET",
                    "value": "$YOUR_SECRET"
                },
                {
                    "name": "GREMLIN_TEAM_ID",
                    "value": "$YOUR_TEAM_ID"
                },
                {
                    "name": "GREMLIN_CLIENT_TAGS",
                    "value": "platform=ecs"
                }
            ],
            "essential": true,
            "image": "gremlin/gremlin:$YOUR_GREMLIN_AGENT_VERSION",
            "linuxParameters": {
                "capabilities": {
                    "add": [
                        "DAC_READ_SEARCH",
                        "KILL",
                        "NET_ADMIN",
                        "NET_RAW",
                        "SYS_ADMIN",
                        "SYS_BOOT",
                        "SYS_PTRACE",
                        "SYS_RESOURCE",
                        "SYS_TIME"
                    ],
                    "drop": []
                },
                "initProcessEnabled": true
            },
            "logConfiguration": {
                "logDriver": "awslogs",
                "options": {
                    "awslogs-group": "/ecs/$YOUR_LOG_GROUP_NAME",
                    "awslogs-create-group": "true",
                    "awslogs-region": "$YOUR_REGION",
                    "awslogs-stream-prefix": "ecs"
                }
            },
            "mountPoints": [
                {
                    "containerPath": "/sys/fs/cgroup",
                    "readOnly": false,
                    "sourceVolume": "cgroup-root"
                },
                {
                    "containerPath": "/var/log/gremlin",
                    "readOnly": false,
                    "sourceVolume": "gremlin-logs"
                },
                {
                    "containerPath": "/var/lib/gremlin/executions",
                    "readOnly": false,
                    "sourceVolume": "gremlin-state"
                },
                {
                    "containerPath": "/var/run/docker.sock",
                    "readOnly": false,
                    "sourceVolume": "docker-socket"
                }
            ],
            "name": "gremlin",
            "portMappings": [],
            "systemControls": [],
            "volumesFrom": []
        }
    ],
    "cpu": "1024",
    "executionRoleArn": "$YOUR_TASK_EXECUTION_ROLE",
    "family": "gremlin",
    "memory": "1024",
    "networkMode": "host",
    "pidMode": "host",
    "placementConstraints": [],
    "requiresCompatibilities": [
        "EC2"
    ],
    "runtimePlatform": {
        "cpuArchitecture": "X86_64",
        "operatingSystemFamily": "LINUX"
    },
    "taskRoleArn": "$YOUR_TASK_ROLE",
    "volumes": [
        {
            "host": {
                "sourcePath": "/var/lib/gremlin/executions"
            },
            "name": "gremlin-state"
        },
        {
            "host": {
                "sourcePath": "/var/run/docker.sock"
            },
            "name": "docker-socket"
        },
        {
            "host": {
                "sourcePath": "/sys/fs/cgroup"
            },
            "name": "cgroup-root"
        },
        {
            "host": {
                "sourcePath": "/var/log/gremlin"
            },
            "name": "gremlin-logs"
        }
    ],
    "tags": []
}

‍

Step 2: Create the daemon service definition

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

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

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

‍

Verifying the installation

To verify that Gremlin is properly installed and running:

In the AWS management Console, navigate to Clusters.
Select the cluster you just deployed Gremlin into.
On the Services tab, you should now see the Gremlin service.
Verify that Desired tasks matches the number of ECS hosts in your cluster
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.
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.
Navigate to https://app.gremlin.com/attacks/new and click on the Containers tab.
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.

Installing the Gremlin Agent

Configuring the Gremlin Agent