Install the ACL Controller

This topic describes how to manually deploy the ACL controller, which will automatically configure the AWS IAM Auth Method. 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 Learn Guides about Consul Security 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.

Set Up Secrets

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

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 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>"
        }
      ]
    }
  ]
}

{
  "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.

In the containerDefinitions list, include one container with the following 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.

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

{
   "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": ["*"]
    }
  ]
}

{
  "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"
      ]
    }
  ]
}

{
  "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"
      ]
    }
  ]
}

The following are the required permissions.