Install the ACL Controller

This topic describes how to manually deploy the ACL controller to automatically provision ACL tokens for Consul on ECS. If you are using Terraform, refer to the Terraform Secure Configuration page to deploy the ACL controller.

Prerequisites

• 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 following Learn Guides for an introduction and the ACL system documentation for more information.

Set Up Secrets

The ACL controller supports managing secrets in AWS Secrets Manager.

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

The secret for the client token must be intially empty. The ACL controller creates the client token in Consul and stores the token in Secrets Manager. In the secret name, <PREFIX> should be replaced with the secret name prefix of your choice.

Secret Name Prefix

The ACL controller requires that the secrets it reads and writes are named with a unique prefix. The name prefix is used in the Task Role Policy to limit the ACL controller’s access within AWS Secrets Manager to only those secrets strictly needed by the ACL controller.

The name prefix should be unique among secrets in your AWS account. We recommend using a short (8 character) random string for the prefix.

NOTE: If you are using the ACL controller with multiple ECS clusters, each cluster requires its own instance of the ACL controller, and each instance of the ACL controller should have a unique name prefix.

Task Definition

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 hosting 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",
        "-consul-client-secret-arn", "arn:aws:secretsmanager:us-west-2:000000000000:secret:<PREFIX>-consul-client-token",
        "-secret-name-prefix", "<PREFIX>",
      ],
      "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.

In the containerDefinitions list, include one container with the following fields.

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

ECS Service

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>",
   ...
}

AWS IAM Roles

The ECS task and execution roles must be configured to allow the ACL controller access to the ECS API and Secrets Manager API.

Task Role Policy

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": ["*"]
    },
    {
      "Effect": "Allow",
      "Action": [
        "secretsmanager:GetSecretValue",
        "secretsmanager:UpdateSecret"
      ],
      "Resource": [
        "arn:aws:secretsmanager:us-west-2:000000000000:secret:<PREFIX>-*"
      ]
    }
  ]
}

The following are the required permissions. You will need to substitute <PREFIX> with your chosen name prefix.

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:<PREFIX>-consul-client-token"
      ]
    }
  ]
}