Deploy Consul to ECS manually

The following instructions describe how to use the consul-ecs Docker image to manually create the ECS task definition without Terraform. If you intend to peer the service mesh to multiple Consul datacenters or partitions, you must use the Consul ECS Terraform module to install your service mesh on ECS. There is no manual process for deploying a mesh gateway to an ECS cluster.

Requirements

You should have some familiarity with AWS ECS. Refer to What is Amazon Elastic Container Service for details.

Secure configuration requirements

You must meet the following requirements and prerequisites to enable security features in Consul service mesh:

• Enable TLS encryption on your Consul servers so that they can communicate security with Consul dataplane containers over gRPC.
• Enable access control lists (ACLs) on your Consul servers. ACLs provide authentication and authorization for access to Consul servers on the mesh.
• You should be familiar with specifying sensitive data on ECS. Refer to Passing sensitive data to a container in the AWS documentation for additional information.

You should be familiar with configuring Consul's secure features, including how to create ACL tokens and policies. Refer to the following resources:

• Create a service token
• Day 1: Security tutorial for additional information.

Consul requires a unique IAM role for each ECS task family. Task IAM roles cannot be shared by different task families because the task family is unique to each Consul service.

Configure ECS task definition file

Create a JSON file for the task definition. The task definition is the ECS blueprint for your software services on AWS. Refer to the ECS task definitions in the AWS documentation for additional information.

In addition to your application container, add configurations to your task definition that creates the following Consul containers:

• Dataplane container
• Control-plane container
• ECS controller container

Top-level fields

The following table describes the top-level fields you must include in the task definition:

The following example shows the top-level fields:

{
  "family": "my-example-client-app",
  "networkMode": "awsvpc",
  "volumes": [
    {
      "name": "consul_data"
    },
    {
      "name": "consul_binary"
    }
  ],
  "containerDefinitions": [...],
  "tags": [
    {
      "key": "consul.hashicorp.com/mesh",
      "value": "true"
    },
    {
      "key": "consul.hashicorp.com/service-name",
      "value":  "example-client-app"
    }
  ]
}

Configure task tags

The tags list must include the following tags if you are using the ECS controller in a secure configuration. Without these tags, the ACL controller is unable to provision a service token for the task.

Define your application container

Specify your application container configurations in the containerDefinitions field. The following table describes all containerDefinitions fields:

Refer to the ECS Task Definition documentation for a complete reference.

Application container dependency configuration

The control-plane and the dataplane containers are dependencies that enforce a specific startup order. The settings ensure that your application container starts after the control-plane container finishes setting up the task and after the dataplane is ready to proxy traffic between this task and the service mesh.

The dependsOn list must include the following maps:

{
  {
    "containerName": "consul-ecs-control-plane",
    "condition": "SUCCESS"
  },
  {
    "containerName": "consul-dataplane",
    "condition": "HEALTHY"
  }
}

Configure the dataplane container

The dataplane container runs Envoy proxy for Consul service mesh. Specify the fields described in the following table to declare a dataplane container:

Dataplane container dependency configuration

The dependsOn configuration ensures that the dataplane container starts after the control-plane container successfully writes the Envoy bootstrap configuration file to the shared volume. The dependsOn list must include the following map:

[
  {
    "containerName": "consul-ecs-control-plane",
    "condition": "SUCCESS"
  }
]

Dataplane container volume mount configuration

The mountPoints configuration defines a volume and path where dataplane container can consume the Envoy bootstrap configuration file generated by the control-plane container. You must specify the following keys and values:

{
  "mountPoints": [
    {
      "readOnly": true,
      "containerPath": "/consul",
      "sourceVolume": "consul_data"
    }
  ],
}

Configure the control-plane container

The control-plane container is the first Consul container to start and set up the instance for Consul service mesh. It registers the service and proxy for this task with Consul and writes the Envoy bootstrap configuration to a shared volume.

Specify the fields described in the following table to declare the control-plane container:

Control-plane shared volume configuration

The mountPoints configuration defines a volume and path where the control-plane container stores the Envoy bootstrap configuration file required to start Envoy. You must specify the following keys and values:

"mountPoints": [
  {
    "readOnly": false,
    "containerPath": "/consul",
    "sourceVolume": "consul_data"
  },
  {
    "readOnly": true,
    "containerPath": "/bin/consul-inject",
    "sourceVolume": "consul_binary"
  }
],

Control-plane to Consul servers configuration

Provide Consul server connection settings to the mesh task module so that the module can configure the control-plane and ECS controller containers to connect to the servers.

1. In your variables.tf file, define variables for the host URL and TLS settings for gRPC and HTTP traffic. Refer to the mesh task module reference for information about the variables you can define. In the following example, the Consul server address is defined in the consul_server_hosts variable:

   variable "consul_server_hosts" {
     description = "Address of Consul servers."
     type        = string
   }
   
   

   Copy

2. Add an environment block to the control-plane and ECS controller containers definition.

3. Set the environment.name field to the CONSUL_ECS_CONFIG_JSON environment variable and the value to local.encoded_config.

   environment = [
     {
       name  = "CONSUL_ECS_CONFIG_JSON",
       value = local.encoded_config
     }
   ]
   

   Copy

   When you apply the configuration, the mesh task module interpolates the server configuration variables, builds a config.tf file, and injects the settings into the appropriate containers.

For additional information about the config.tf file, refer to the JSON schema reference documentation.

Register the task definition configuration

Register the task definition with your ECS cluster using the AWS Console, AWS CLI, or another method supported by AWS. You must also create an ECS Service to start tasks using the task definition. Refer to the following ECS documentation for information on how to register the task definition:

• Creating a task definition using the classic console
• Register task definition CLI

Deploy the controller container

The controller container runs in a separate ECS task and is responsible for Consul security features. The controller uses the AWS IAM auth method to enable ECS tasks to automatically obtain Consul ACL tokens when the task starts up. Refer to Consul security components for additional information.

Verify that you have completed the prerequisites described in Secure configuration requirements and configure the following components to enable Consul security features.

• ACL policy
• ECS task role
• Auth method for service tokens

Create an ACL policy

On the Consul server, create a policy that grants the following access for the controller:

• acl:write
• operator:write
• node:write
• service:write

The policy allows Consul to generate a token linked to the policy. Refer to Create a service token for instructions.

ECS task role

1. Create an ECS task role and configure an iam:GetRole permission so that it can fetch itself. Refer to IAM Policies for instructions.
2. Add an consul.hashicorp.com.service-name tag to the task role that contains the Consul service name for the application in the task.
3. When using Consul Enterprise, you must also include the consul.hashicorp.com.namespace tag to specify the namespace to register the service in.

Configure the auth method for service tokens

Run the consul acl auth-method create command on a Consul server to create an instance of the auth method for service tokens.

The following example command configures the auth method to associate a service identity to each token created during login to this auth method instance.

$ consul acl auth-method create \
    -type aws-iam \
    -name iam-ecs-service-token \
    -description="AWS IAM auth method for ECS service tokens" \
    -config '{
  "BoundIAMPrincipalArns": ["arn:aws:iam::<ACCOUNT>:role/consul-ecs/*"],
  "EnableIAMEntityDetails": true,
  "IAMEntityTags": [
    "consul.hashicorp.com.service-name"
  ]
}'

If you want to create these resources in a particular partition, include the -partition <partition-name> option when creating Consul ACL roles, policies, auth methods, and binding rules with the Consul CLI.

You must specify the following flags in the command:

Auth method -config parameter

You must specify the following configuration in the -config flag:

Refer to the auth method configuration parameters documentation for additional information.

Create the binding rule

Run the consul acl binding-rule create command on a Consul server to create a binding rule. The rule associates a service identity with each token created on successful login to this instance of the auth method.

In the following example, Consul takes the service identity name from the consul.hashicorp.com.service-name tag specified for authenticating IAM role identity.

$ consul acl binding-rule create \
   -method iam-ecs-service-token \
   -description 'Bind a service identity from IAM role tags for ECS service tokens' \
   -bind-type service \
   -bind-name '${entity_tags.consul.hashicorp.com.service-name}'

Note that you must include the -partition <partition-name> option to the Consul CLI when creating Consul ACL roles, policies, auth methods, and binding rules, in order to create these resources in a particular partition.

Configure storage for secrets

Secure and store Consul Server CA certificates so that they are available to ECS tasks. You may require more than one certificate for different Consul protocols. Refer to the following documentation for instructions on how to store and pass secrets to ECS tasks:

• AWS Systems Manager Parameter Store
• AWS Secrets Manager

You can reference stored secrets using their ARN. The examples show ARNs for secrets stored in AWS Secrets Manager:

• Consul Server CA Cert for RPC: arn:aws:secretsmanager:us-west-2:000000000000:secret:my-consul-ca-cert
• Consul Server CA Cert for HTTPS: arn:aws:secretsmanager:us-west-2:000000000000:secret:my-consul-https-ca-cert

Configure audit logging EnterpriseEnterprise

You can configure Consul servers connected to your ECS workloads to capture a log of authenticated events. Refer to Audit Logging for details.

Next steps

After deploying the Consul service mesh infrastructure, you must still define routes between service instances as well as configure the bind address for your applications so that they only receive traffic through the mesh. Refer to the following topics:

• Configure routes between ECS tasks
• Configure the ECS task bind address