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.

SecretSample Secret NameDescription
Consul server CA certmy-consul-ca-certThe Consul server CA Cert for the HTTPS interface. This is required if the Consul server uses a self-signed or internal CA. It is not required for Consul servers in HCP.
Bootstrap ACL Tokenmy-consul-bootstrap-tokenA Consul ACL token with acl:write and operator:write permissions.

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.

  1. {
  2. "family": "my-consul-acl-controller",
  3. "networkMode": "awsvpc",
  4. "containerDefinitions": [
  5. {
  6. "name": "acl-controller",
  7. "image": "public.ecr.aws/hashicorp/consul-ecs:<CONSUL_ECS_VERSION>",
  8. "essential": true,
  9. "command": ["acl-controller", "-iam-role-path", "/consul-ecs/"],
  10. "secrets": [
  11. {
  12. "name": "CONSUL_HTTP_TOKEN",
  13. "valueFrom": "arn:aws:secretsmanager:us-west-2:000000000000:secret:my-consul-bootstrap-token"
  14. },
  15. {
  16. "name": "CONSUL_CACERT_PEM",
  17. "valueFrom": "arn:aws:secretsmanager:us-west-2:000000000000:secret:my-consul-ca-cert"
  18. }
  19. ],
  20. "environment": [
  21. {
  22. "name": "CONSUL_HTTP_ADDR",
  23. "value": "<Consul server HTTP API address>"
  24. }
  25. ]
  26. }
  27. ]
  28. }
  1. {
  2. "family": "my-consul-acl-controller",
  3. "networkMode": "awsvpc",
  4. "containerDefinitions": [
  5. {
  6. "name": "acl-controller",
  7. "image": "public.ecr.aws/hashicorp/consul-ecs:<CONSUL_ECS_VERSION>",
  8. "essential": true,
  9. "command": ["acl-controller", "-iam-role-path", "/consul-ecs/"],
  10. "secrets": [
  11. {
  12. "name": "CONSUL_HTTP_TOKEN",
  13. "valueFrom": "arn:aws:secretsmanager:us-west-2:000000000000:secret:my-consul-bootstrap-token"
  14. },
  15. {
  16. "name": "CONSUL_CACERT_PEM",
  17. "valueFrom": "arn:aws:secretsmanager:us-west-2:000000000000:secret:my-consul-ca-cert"
  18. }
  19. ],
  20. "environment": [
  21. {
  22. "name": "CONSUL_HTTP_ADDR",
  23. "value": "<Consul server HTTP API address>"
  24. }
  25. ]
  26. }
  27. ]
  28. }

You must include the following top-level fields.

Field nameTypeDescription
familystringThe task family name of your choice.
networkModestringMust be awsvpc, which is the only network mode supported by Consul on ECS.

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

Field nameTypeDescription
namestringThe container name, which should be acl-controller
imagestringThe consul-ecs image. Use our public AWS registry, public.ecr.aws/hashicorp/consul-ecs, to avoid rate limits.
commandlistShould be set as shown. The startup command for the ACL controller.
essentialbooleanMust be true to ensure the health of your application container affects the health status of the task.
secretslistShould be set as shown. Configures the secrets the ECS service will retrieve and set as environment variables in the acl-controller container.
environmentstringMust be set as shown. Configures environment variables that the ECS service will set in the acl-controller container. Must set the CONSUL_HTTP_ADDR environment variable to the HTTP(S) address of the Consul servers.

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

FlagTypeDescription
-iam-role-pathstringSpecifies the path to IAM roles trusted by the AWS IAM auth method created by the controller.
-log-levelstringThe log level for the ACL controller. Can be set to DEBUG for additional detail.

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

NameDescription
CONSUL_HTTP_TOKENMust be set to the secret containing the bootstrap ACL token.
CONSUL_CACERT_PEMIf applicable, should be set to the secret containing the Consul server CA certificate. This must not be set when using Consul servers in HCP.

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.

  1. {
  2. "cluster": "<Your ECS cluster ARN>"
  3. "desiredCount": 1,
  4. "launchType": "FARGATE",
  5. "serviceName": "my-acl-controller",
  6. "taskDefinition": "<task definition ARN>",
  7. ...
  8. }
  1. {
  2. "cluster": "<Your ECS cluster ARN>"
  3. "desiredCount": 1,
  4. "launchType": "FARGATE",
  5. "serviceName": "my-acl-controller",
  6. "taskDefinition": "<task definition ARN>",
  7. ...
  8. }
Field nameTypeDescription
clusterstringSet to your ECS cluster name or ARN. This must be the same ECS cluster where your service mesh applications run.
desiredCountintegerMust be 1. Only one instance of the ACL controller should run per ECS cluster.
launchTypestringConsul on ECS supports both the FARGATE and EC2 launch types.
serviceNamestringThe service name of your choice.
taskDefinitionstringMust be set to the ACL controller task definition.

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.

  1. {
  2. "Version": "2012-10-17",
  3. "Statement": [
  4. {
  5. "Effect": "Allow",
  6. "Action": [
  7. "ecs:ListTasks",
  8. "ecs:DescribeTasks"
  9. ],
  10. "Resource": ["*"]
  11. }
  12. ]
  13. }
  1. {
  2. "Version": "2012-10-17",
  3. "Statement": [
  4. {
  5. "Effect": "Allow",
  6. "Action": [
  7. "ecs:ListTasks",
  8. "ecs:DescribeTasks"
  9. ],
  10. "Resource": ["*"]
  11. }
  12. ]
  13. }

The following are the required permissions.

ActionResourceDescription
ecs:ListTasksAllow the ACL controller to watch for new tasks.
ecs:DescribeTasksAllow the ACL controller to retrieve details for new tasks.

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.

  1. {
  2. "Version": "2012-10-17",
  3. "Statement": [
  4. {
  5. "Effect": "Allow",
  6. "Action": [
  7. "secretsmanager:GetSecretValue"
  8. ],
  9. "Resource": [
  10. "arn:aws:secretsmanager:us-west-2:000000000000:secret:my-consul-bootstrap-token",
  11. "arn:aws:secretsmanager:us-west-2:000000000000:secret:my-consul-ca-cert"
  12. ]
  13. }
  14. ]
  15. }
  1. {
  2. "Version": "2012-10-17",
  3. "Statement": [
  4. {
  5. "Effect": "Allow",
  6. "Action": [
  7. "secretsmanager:GetSecretValue"
  8. ],
  9. "Resource": [
  10. "arn:aws:secretsmanager:us-west-2:000000000000:secret:my-consul-bootstrap-token",
  11. "arn:aws:secretsmanager:us-west-2:000000000000:secret:my-consul-ca-cert"
  12. ]
  13. }
  14. ]
  15. }

The following are the required permissions.

ActionResourceDescription
secretsmanager:GetSecretValuearn:aws:secretsmanager:us-west-2:000000000000:secret:<NAME>Allow ECS to retrieve this secret and inject the secret into the task.