Install the ACL Controller

• Your application tasks must include certain tags to be compatible with the ACL controller. Refer to the Task Tags section of the installation page.
• You should be familiar with configuring Consul’s secure features, including how to create ACL tokens and policies. Refer to the for an introduction and the ACL system documentation for more information.
• If you are using Consul with multiple ECS clusters, each cluster requires its own instance of the ACL controller.

Before deploying the ACL controller for the first time, you must from Consul in AWS Secrets Manager.

You must create a task definition to deploy the ACL controller in your ECS cluster. The ACL controller must run in the same ECS cluster that hosts your service mesh application tasks.

The following example shows how the task definition should be configured for the ACL controller.

{
  "family": "my-consul-acl-controller",
  "networkMode": "awsvpc",
  "containerDefinitions": [
    {
      "name": "acl-controller",
      "image": "public.ecr.aws/hashicorp/consul-ecs:<CONSUL_ECS_VERSION>",
      "essential": true,
      "command": ["acl-controller", "-iam-role-path", "/consul-ecs/"],
      "secrets": [
        {
          "name": "CONSUL_HTTP_TOKEN",
          "valueFrom": "arn:aws:secretsmanager:us-west-2:000000000000:secret:my-consul-bootstrap-token"
        },
          "name": "CONSUL_CACERT_PEM",
          "valueFrom": "arn:aws:secretsmanager:us-west-2:000000000000:secret:my-consul-ca-cert"
        }
      ],
      "environment": [
        {
          "name": "CONSUL_HTTP_ADDR",
          "value": "<Consul server HTTP API address>"
        }
      ]
    }
  ]
}

You must include the following top-level fields.

The following CLI options are available in the command field of the container definition.

The following describes the entries to include in the secrets list.

Once the task definition is created, define an ECS service in order to start an ACL controller task.

The following example contains the recommended settings for the ACL controller. Refer to the ECS service documentation to complete the remaining details for your use case.

{
   "cluster": "<Your ECS cluster ARN>"
   "desiredCount": 1,
   "launchType": "FARGATE",
   "serviceName": "my-acl-controller",
   "taskDefinition": "<task definition ARN>",
   ...
}

The following example shows the policy needed for the ECS task role for the ACL controller. This grants the ACL controller permission to list tasks, describe tasks, and read and update secrets.

{
  "Version": "2012-10-17",
  "Statement": [
      "Effect": "Allow",
      "Action": [
        "ecs:ListTasks",
        "ecs:DescribeTasks"
      ],
      "Resource": ["*"]
    }
  ]
}

The following are the required permissions.

Execution Role Policy

The following IAM policy document allows ECS to retrieve secrets needed to start the ACL controller task from AWS Secrets Manager, including the ACL bootstrap token.

The following example shows the policy needed for the execution role.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "secretsmanager:GetSecretValue"
      ],
      "Resource": [
        "arn:aws:secretsmanager:us-west-2:000000000000:secret:my-consul-bootstrap-token",
        "arn:aws:secretsmanager:us-west-2:000000000000:secret:my-consul-ca-cert"
      ]
    }
  ]
}