status-im
/
consul
mirror of https://github.com/status-im/consul.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

Docs/ce 477 dataplanes on ecs (#19010) 

* updated architecture topic

* fixed type in arch diagram filenames

* fixed path to img file

* updated index page - still need to add links

* moved arch and tech specs to reference folder

* moved other ref topics to ref folder

* set up the Deploy folder and TF install topics

* merged secure conf into TF deploy instructions

* moved bind addr and route conf to their own topics

* moved arch and tech specs back to main folder

* update migrate-existing-tasks content

* merged manual deploy content; added serv conf ref

* fixed links

* added procedure for upgrading to dataplanes

* fixed linked reported by checker

* added updates to dataplanes overview page

* Apply suggestions from code review

Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>

* Apply suggestions from code review

Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>
Co-authored-by: Ganesh S <ganesh.seetharaman@hashicorp.com>

* Apply suggestions from code review

Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>
Co-authored-by: Ganesh S <ganesh.seetharaman@hashicorp.com>

* Apply suggestions from code review

Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>

* Apply suggestions from code review

Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>
Co-authored-by: Ganesh S <ganesh.seetharaman@hashicorp.com>

* Apply suggestions from code review

Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>
Co-authored-by: Ganesh S <ganesh.seetharaman@hashicorp.com>

* updated links and added redirects

* removed old architecture content

---------

Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>
Co-authored-by: Ganesh S <ganesh.seetharaman@hashicorp.com>
This commit is contained in:
trujillo-adam 2023-10-05 07:33:44 -07:00 committed by GitHub
parent af9a486fdc
commit 788c58699e
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
27 changed files with 1448 additions and 2417 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

71
website/content/docs/connect/dataplane/index.mdx
View File

@ -2,28 +2,35 @@
layout: docs
page_title: Simplified Service Mesh with Consul Dataplane
description: >-
Consul Dataplane removes the need to a run client agent for service discovery and service mesh by leveraging orchestrator functions. Learn about Consul Dataplane, how it can lower latency for Consul on Kubernetes, and how it enables Consul support for AWS Fargate and GKE Autopilot.
Consul Dataplane removes the need to run a client agent for service discovery and service mesh by leveraging orchestrator functions. Learn about Consul Dataplane, how it can lower latency for Consul on Kubernetes and AWS ECS, and how it enables Consul support for AWS Fargate and GKE Autopilot.
---
# Simplified Service Mesh with Consul Dataplane
This topic provides an overview of Consul Dataplane, a lightweight process for managing Envoy proxies introduced in Consul v1.14.0. Consul Dataplane removes the need to run client agents on every node in a cluster for service discovery and service mesh. Instead, Consul deploys sidecar proxies that provide lower latency, support additional runtimes, and integrate with cloud infrastructure providers.
This topic provides an overview of Consul Dataplane, a lightweight process for managing Envoy proxies. Consul Dataplane removes the need to run client agents on every node in a cluster for service discovery and service mesh. Instead, Consul deploys sidecar proxies that provide lower latency, support additional runtimes, and integrate with cloud infrastructure providers.
## Supported environments
- Dataplanes can connect to Consul servers v1.14.0 and newer.
- Dataplanes on Kubernetes requires Consul K8s v1.0.0 and newer.
- Dataplanes on AWS Elastic Container Services (ECS) requires Consul ECS v0.7.0 and newer.
Consul Dataplane requires servers running Consul v1.14.0+ and Consul K8s v1.0.0+.
## What is Consul Dataplane?
In standard deployments, Consul uses a control plane that contains both _server agents_ and _client agents_. Server agents maintain the service catalog and service mesh, including its security and consistency, while client agents manage communications between service instances, their sidecar proxies, and the servers. While this model is optimal for applications deployed on virtual machines or bare metal servers, orchestrators such as Kubernetes already include components called _kubelets_ that support health checking and service location functions typically provided by the client agent.
When deployed to virtual machines or bare metal environments, the Consul control plane requires _server agents_ and _client agents_. Server agents maintain the service catalog and service mesh, including its security and consistency, while client agents manage communications between service instances, their sidecar proxies, and the servers. While this model is optimal for applications deployed on virtual machines or bare metal servers, orchestrators such as Kubernetes and ECS have native components that support health checking and service location functions typically provided by the client agent.
Consul Dataplane manages Envoy proxies and leaves responsibility for other functions to the orchestrator. As a result, it removes the need to run client agents on every node. In addition, services no longer need to be reregistered to a local client agent after restarting a service instance, as a client agent’s lack of access to persistent data storage in Kubernetes deployments is no longer an issue.
Consul Dataplane manages Envoy proxies and leaves responsibility for other functions to the orchestrator. As a result, it removes the need to run client agents on every node. In addition, services no longer need to be reregistered to a local client agent after restarting a service instance, as a client agent’s lack of access to persistent data storage in container-orchestrated deployments is no longer an issue.
The following diagram shows how Consul Dataplanes facilitate service mesh in a Kubernetes-orchestrated environment.
![Diagram of Consul Dataplanes in Kubernetes deployment](/img/k8s-dataplanes-architecture.png)
### Impact on performance
The most significant differences between traditional deployments and Consul Dataplane deployments result from the removal of node-level client agents with gossip communication. They are replaced by _dataplanes_, which are the sidecars injected alongside each service instance that handle communication between Consul servers and Envoy proxies. While dataplanes use fewer resources than client agents, Consul servers need to consume additional resources in order to generate xDS resources for Envoy proxies.
Consul Dataplanes replace node-level client agents and function as sidecars attached to each service instance. Dataplanes handle communication between Consul servers and Envoy proxies, using fewer resources than client agents. Consul servers need to consume additional resources in order to generate xDS resources for Envoy proxies.
As a result, small deployments require fewer resources overall. For deployments that are especially large or expected to experience high levels of churn, consider the following impacts to your network's performance:
As a result, small deployments require fewer overall resources. For especially large deployments or deployments that expect to experience high levels of churn, consider the following impacts to your network's performance:
1. In our internal tests, which used 5000 proxies and services flapping every 2 seconds, additional CPU utilization remained under 10% on the control plane.
1. As you deploy more services, the resource usage for dataplanes grows on a linear scale.
@ -37,7 +44,7 @@ As a result, small deployments require fewer resources overall. For deployments
**Simplified set up**: Because there are no client agents to engage in gossip, you do not have to generate and distribute a gossip encryption key to agents during the initial bootstrapping process. Securing agent communication also becomes simpler, with fewer tokens to track, distribute, and rotate.
**Additional environment and runtime support**: Consul on Kubernetes versions *prior* to 1.0 (Consul 1.14) require using hostPorts and DaemonSets for client agents, which limits Consul’s ability to be deployed in environments where those features are not supported.
**Additional environment and runtime support**: Consul on Kubernetes versions _prior_ to v1.0 (Consul v1.14) require the use of hostPorts and DaemonSets for client agents, which limits Consul’s ability to be deployed in environments where those features are not supported.
As of Consul on Kubernetes version 1.0 (Consul 1.14) with the new Consul Dataplane, `hostPorts` are no longer required and Consul now supports AWS Fargate and GKE Autopilot.
**Easier upgrades**: With Consul Dataplane, updating Consul to a new version no longer requires upgrading client agents. Consul Dataplane also has better compatibility across Consul server versions, so the process to upgrade Consul servers becomes easier.
@ -49,9 +56,15 @@ To get started with Consul Dataplane, use the following reference resources:
- For `consul-dataplane` commands and usage examples, including required flags for startup, refer to the [`consul-dataplane` CLI reference](/consul/docs/connect/dataplane/consul-dataplane).
- For Helm chart information, refer to the [Helm Chart reference](/consul/docs/k8s/helm).
- For Envoy, Consul, and Consul Dataplane version compatibility, refer to the [Envoy compatibility matrix](/consul/docs/connect/proxies/envoy).
- For Consul on ECS workloads, refer to [Consul on AWS Elastic Container Service (ECS) Overview](/consul/docs/ecs).
### Installation
<Tabs>
<Tab heading="Kubernetes" group="k8s">
To install Consul Dataplane, set `VERSION` to `1.0.0` and then follow the instructions to install a specific version of Consul [with the Helm Chart](/consul/docs/k8s/installation/install#install-consul) or [with the Consul-k8s CLI](/consul/docs/k8s/installation/install-cli#install-a-previous-version).
#### Helm
@ -67,14 +80,41 @@ $ helm install consul hashicorp/consul --set global.name=consul --version ${VERS
$ export VERSION=1.0.0 && \
curl --location "https://releases.hashicorp.com/consul-k8s/${VERSION}/consul-k8s_${VERSION}_darwin_amd64.zip" --output consul-k8s-cli.zip
```
</Tab>
<Tab heading="ECS" group="ecs">
Refer to the following documentation for Consul on ECS workloads:
- [Deploy Consul with the Terraform module](/consul/docs/ecs/deploy/terraform)
- [Deploy Consul manually](/consul/ecs/install-manul)
</Tab>
</Tabs>
### Upgrading
<Tabs>
<Tab heading="Kubernetes" group="k8s">
Before you upgrade Consul to a version that uses Consul Dataplane, you must edit your Helm chart so that client agents are removed from your deployments. Refer to [upgrading to Consul Dataplane](/consul/docs/k8s/upgrade#upgrading-to-consul-dataplanes) for more information.
</Tab>
<Tab heading="ECS" group="ecs">
Refer to [Upgrade to dataplane architecture](/consul/docs/ecs/upgrade-to-dataplanes) for instructions.
</Tab>
</Tabs>
## Feature support
Consul Dataplane supports the following features:
Consul Dataplane on Kubernetes supports the following features:
- Single and multi-cluster installations, including those with WAN federation, cluster peering, and admin partitions are supported.
- Ingress, terminating, and mesh gateways are supported.
@ -82,10 +122,17 @@ Consul Dataplane supports the following features:
- xDS load balancing is supported.
- Servers running in Kubernetes and servers external to Kubernetes are both supported.
- HCP Consul is supported.
- Consul API Gateway is supported.
- Consul API Gateway
Consul Dataplane on ECS support the following features:
- Single and multi-cluster installations, including those with WAN federation, cluster peering, and admin partitions
- Mesh gateways
- Running Consul service mesh in AWS Fargate and EC2
- xDS load balancing
- Self-managed and HCP Consul managed servers
### Technical Constraints
Be aware of the following limitations and recommendations for Consul Dataplane:
- Consul Dataplane is not supported on Windows.

276
website/content/docs/ecs/architecture.mdx
View File

@ -1,257 +1,85 @@
---
layout: docs
page_title: Consul on AWS Elastic Container Service (ECS) Architecture
page_title: Consul on AWS Elastic Container Service (ECS) architecture
description: >-
Consul's architecture supports Amazon Web Services ECS deployments. Learn about how the two work together, including the order tasks and containers startup and shutdown, as well as requirements for the AWS IAM auth method, the ACL controller and tokens, and health check syncing.
Learn about the Consul architecture on Amazon Web Services ECS deployments. Learn about how the two work together, including the order tasks and containers startup and shutdown, as well as requirements for the AWS IAM auth method, the ACL controller and tokens, and health check syncing.
---
# Consul on AWS Elastic Container Service (ECS) Architecture
# Consul on AWS Elastic Container Service (ECS) architecture
The following diagram shows the main components of the Consul architecture when deployed to an ECS cluster:
This topic provides reference information about the Consul's deployment architecture on AWS ECS. The following diagram shows the main components of the Consul architecture when deployed to an ECS cluster.
![Consul on ECS Architecture](/img/consul-ecs-arch.png)
![Diagram that provides an overview of the Consul Architecture on ECS](/img/ecs/consul-on-ecs-architecture-dataplanes.jpg#light-theme-only)
![Diagram that provides an overview of the Consul Architecture on ECS ](/img/ecs/consul-on-ecs-architecture-dataplanes-dark.jpg#dark-theme-only)
1. **Consul servers:** Production-ready Consul server cluster
1. **Application tasks:** Runs user application containers along with two helper containers:
1. **Consul client:** The Consul client container runs Consul. The Consul client communicates
with the Consul server and configures the Envoy proxy sidecar. This communication
is called _control plane_ communication.
1. **Sidecar proxy:** The sidecar proxy container runs [Envoy](https://envoyproxy.io/). All requests
to and from the application container(s) run through the sidecar proxy. This communication
is called _data plane_ communication.
1. **Mesh Init:** Each task runs a short-lived container, called `mesh-init`, which sets up initial configuration
for Consul and Envoy.
1. **Health Syncing:** Optionally, an additional `health-sync` container can be included in a task to sync health statuses
from ECS into Consul.
1. **ACL Controller:** The ACL controller is responsible for automating configuration and cleanup in the Consul servers.
The ACL controller will automatically configure the [AWS IAM Auth Method](/consul/docs/security/acl/auth-methods/aws-iam), and cleanup
unused ACL tokens from Consul. When using Consul Enterprise namespaces, the ACL controller will automatically create Consul
namespaces for ECS tasks.
## Components
Consul starts several components and containers inside the ECS cluster. Refer to [Startup sequence](#startup-sequence) for details about the order of the startup procedure:
For more information about how Consul works in general, see Consul's [Architecture Overview](/consul/docs/architecture).
### Control-plane container
## Task Startup
The control-plane container performs the following actions:
This diagram shows the timeline of a task starting up and all its containers:
- Logs into Consul servers
- Communicates directly with Consul server
- Registers proxies and services
- Creates a bootstrap configuration file for Consul dataplane container and stores it in a shared volume
- Synchronizes ECS health checks
- Watches the Consul server for changes
<ImageConfig width={400}>
### Dataplane containers
![Task Startup Timeline](/img/ecs-task-startup.svg)
The dataplane process runs in the same container as the Envoy proxy and performs the following actions:
</ImageConfig>
- Consumes and configures itself according to the bootstrap configuration written by the control-plane container.
- Contains and starts up the Envoy sidecar.
- **T0:** ECS starts the task. The `consul-client` and `mesh-init` containers start:
- `consul-client` does the following:
- If ACLs are enabled, a startup script runs a `consul login` command to obtain a
token from the AWS IAM auth method for the Consul client. This token has `node:write`
permissions.
- It uses the `retry-join` option to join the Consul cluster.
- `mesh-init` does the following:
- If ACLs are enabled, mesh-init runs a `consul login` command to obtain a token from
the AWS IAM auth method for the service registration. This token has `service:write`
permissions for the service and its sidecar proxy. This token is written to a shared
volume for use by the `health-sync` container.
- It registers the service for the current task and its sidecar proxy with Consul.
- It runs `consul connect envoy -bootstrap` to generate Envoy's bootstrap JSON file and
writes it to a shared volume.
- **T1:** The following containers start:
- `sidecar-proxy` starts using a custom entrypoint command, `consul-ecs envoy-entrypoint`.
The entrypoint command starts Envoy by running `envoy -c <path-to-bootstrap-json>`.
- `health-sync` starts if ECS health checks are defined or if ACLs are enabled. It syncs health
checks from ECS to Consul (see [ECS Health Check Syncing](#ecs-health-check-syncing)).
- **T2:** The `sidecar-proxy` container is marked as healthy by ECS. It uses a health check that
detects if its public listener port is open. At this time, your application containers are started
since all Consul machinery is ready to service requests.
### ECS controller container
## Task Shutdown
One ECS task in the cluster contains the controller container, which performs the following actions:
This diagram shows an example timeline of a task shutting down:
- Creates AWS IAM auth methods
- Creates ACL policies and roles
- Maintains ACL state
- Removes tokens when services exit
- Deregisters services if the ECS task exits without deregistering them
- Registers a _synthetic node_ that enables Consul to register services to the catalog
<ImageConfig width={400}>
## Startup sequence
![Task Shutdown Timeline](/img/ecs-task-shutdown.svg)
Deploying Consul to ECS starts the following process to build the architecture:
</ImageConfig>
1. The control-plane container starts and logs into Consul.
1. The control-plane container registers services and proxies with the Consul servers.
1. The control-plane container writes the bootstrap configuration for the Consul dataplane process and stores it in a shared volume.
1. The dataplane container starts and configures itself using the bootstrap configuration generated by the control-plane container.
1. The dataplane container starts the Envoy sidecar proxy.
1. The control-plane container starts listening for ECS health checks.
1. When the ECS task indicates that the application instance is healthy, the control-plane container marks the service as healthy and starts allowing traffic to flow.
- **T0**: ECS sends a TERM signal to all containers. Each container reacts to the TERM signal:
- `consul-client` begins to gracefully leave the Consul cluster.
- `health-sync` stops syncing health status from ECS into Consul checks.
- `sidecar-proxy` ignores the TERM signal and continues running until the `user-app` container
exits. The custom entrypoint command, `consul-ecs envoy-entrypoint`, monitors the local ECS task
metadata. It waits until the `user-app` container has exited before terminating Envoy. This
enables the application to continue making outgoing requests through the proxy to the mesh for
graceful shutdown.
- `user-app` exits if it is not configured to ignore the TERM signal. The `user-app` container
will continue running if it is configured to ignore the TERM signal.
- **T1**:
- `health-sync` does the following:
- It updates its Consul checks to critical status and exits. This ensures this service instance is marked unhealthy.
- If ACLs are enabled, it runs `consul logout` for the two tokens created by the `consul-client` and `mesh-init` containers.
This removes those tokens from Consul. If `consul logout` fails for some reason, the ACL controller will remove the tokens
after the task has stopped.
- `sidecar-proxy` notices the `user-app` container has stopped and exits.
- **T2**: `consul-client` finishes gracefully leaving the Consul datacenter and exits.
- **T3**:
- ECS notices all containers have exited, and will soon change the Task status to `STOPPED`
- Updates about this task have reached the rest of the Consul cluster, so downstream proxies have been updated to stopped sending traffic to this task.
- **T4**: At this point task shutdown should be complete. Otherwise, ECS will send a KILL signal to any containers still running. The KILL signal cannot be ignored and will forcefully stop containers. This will interrupt in-progress operations and possibly cause errors.
## Consul security components
## ACL Tokens
Consul leverages AWS components to facilitate its own security features.
Two types of ACL tokens are required by ECS tasks:
### Auth methods
* **Client tokens:** used by the `consul-client` containers to join the Consul cluster
* **Service tokens:** used by sidecar containers for service registration and health syncing
Consul on ECS uses the AWS IAM auth method so that ECS tasks can automatically obtain Consul ACL tokens during startup.
With Consul on ECS, these tokens are obtained dynamically when a task starts up by logging
in via Consul's AWS IAM auth method.
When ACLs are enabled, the Terraform modules for Consul on ECS support AWS IAM auth methods by default. The ECS controller sets up the auth method on the Consul servers. The `mesh-task` module configures the ECS task definition to be compatible with the auth method.
### Consul Client Token
A unique task IAM role is required for each ECS task family. A task family represents only one Consul service and the task IAM role must encode the Consul service name. As a result, task IAM roles must not be shared by different task families.
Consul client tokens require `node:write` for any node name, which is necessary because the Consul node
names on ECS are not known until runtime.
By default, the mesh-task module creates and configures the task IAM role for you.
### Service Token
To pass an existing IAM role to the mesh-task module using the `task_role` input variable, configure the IAM role as described in ECS Task Role Configuration to be compatible with the AWS IAM auth method.
Service tokens are associated with a [service identity](/consul/docs/security/acl#service-identities).
The service identity includes `service:write` permissions for the service and sidecar proxy.
### ECS task roles
## AWS IAM Auth Method
The [ECS task role](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html) is an IAM role associated with an ECS task.
Consul's [AWS IAM Auth Method](/consul/docs/security/acl/auth-methods/aws-iam) is used by ECS tasks to
automatically obtain Consul ACL tokens. When a service mesh task on ECS starts up, it runs two
`consul login` commands to obtain a client token and a service token via the auth method. When the
task stops, it attempts two `consul logout` commands in order to destroy these tokens.
When an ECS task starts up, it runs a `consul login` command. The command obtains credentials for the task role from AWS and then uses those credentials to sign the login request to the AWS IAM auth method. The credentials prove the ECS task's identity to the Consul servers.
During a `consul login`, the [task's IAM
role](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html) is presented
to the AWS IAM auth method on the Consul servers. The role is validated with AWS. If the role is
valid, and if the auth method trusts the IAM role, then the role is permitted to login. A new Consul
ACL token is created and [Binding Rules](/consul/docs/security/acl/auth-methods#binding-rules) associate
permissions with the newly created token. These permissions are mapped to the token based on the IAM
role details. For example, tags on the IAM role are used to specify the service name and the
Consul Enterprise namespace to be associated with a service token that is created by a successful
login to the auth method.
You must configure the task role with the following details for it to be compatible with the AWS IAM auth method:
### Task IAM Role
The following configuration is required for the task IAM role in order to be compatible with the
auth method. When using Terraform, the `mesh-task` module creates the task role with this
configuration by default.
* A scoped `iam:GetRole` permission must be included on the IAM role, enabling the role to fetch
details about itself.
* A `consul.hashicorp.com.service-name` tag on the IAM role must be set to the Consul service name.
* <EnterpriseAlert inline /> A <code>consul.hashicorp.com.namespace</code> tag must be set on the
IAM role to the Consul Enterprise namespace of the Consul service for the task.
Task IAM roles should not typically be shared across task families. Since a task family represents a
single Consul service, and since the task role must include the Consul service name, one task role
is required for each task family when using the auth method.
### Security
The auth method relies on the configuration of AWS resources, such as IAM roles, IAM policies, and
ECS tasks. If these AWS resources are misconfigured or if the account has loose access controls,
then the security of your service mesh may be at risk.
Any entity in your AWS account with the ability to obtain credentials for an IAM role could potentially
obtain a Consul ACL token and impersonate a Consul service. The `mesh-task` Terraform module
mitigates against this concern by creating the task role with an `AssumeRolePolicyDocument` that
allows only the AWS ECS service to assume the task role. By default, other entities are unable
to obtain credentials for task roles, and are unable to abuse the AWS IAM auth method to obtain
Consul ACL tokens.
However, other entities in your AWS account with the ability to create or modify IAM roles can
potentially circumvent this. For example, if they are able to create an IAM role with the correct
tags, they can obtain a Consul ACL token for any service. Or, if they can pass a role to an ECS task
and start an ECS task, they can use the task to obtain a Consul ACL token via the auth method.
The IAM policy actions `iam:CreateRole`, `iam:TagRole`, `iam:PassRole`, and `sts:AssumeRole` can be
used to restrict these capabilities in your AWS account and improve security when using the AWS IAM
auth method. See the [AWS
documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html) to learn how
to restrict these permissions in your AWS account.
## ACL Controller
The ACL controller performs the following operations on the Consul servers:
* Configures the Consul AWS IAM auth method.
* Monitors tasks in ECS cluster where the controller is running.
* Cleans up unused Consul ACL tokens created by tasks in this cluster.
* <EnterpriseAlert inline /> Manages Consul admin partitions and namespaces.
### Auth Method Configuration
The ACL controller is responsible for configuring the AWS IAM auth method. The following resources
are created by the ACL controller when it starts up:
* **Client role**: The controller creates the Consul (not IAM) role and policy used for client
tokens if these do not exist. This policy has `node:write` permissions to enable Consul clients to
join the Consul cluster.
* **Auth method for client tokens**: One instance of the AWS IAM auth method is created for client
tokens, if it does not exist. A binding rule is configured that attaches the Consul client role to each
token created during a successful login to this auth method instance.
* **Auth method for service tokens**: One instance of the AWS IAM auth method is created for service
tokens, if it does not exist:
* A binding rule is configured to attach a [service identity](/consul/docs/security/acl#service-identities)
to each token created during a successful login to this auth method instance. The service name for
this service identity is taken from the tag, `consul.hashicorp.com.service-name`, on the IAM role
used to log in.
* <EnterpriseAlert inline /> A namespace binding rule is configured to create service tokens in
the namespace specified by the tag, <code>consul.hashicorp.com.namespace</code>, on the IAM
role used to log in.
The ACL controller configures both instances of the auth method to permit only certain IAM roles to login,
by setting the [`BoundIAMPrincipalARNs`](/consul/docs/security/acl/auth-methods/aws-iam#boundiamprincipalarns)
field of the AWS IAM auth method as follows:
* By default, the only IAM roles permitted to log in must have an ARN matching the pattern,
`arn:aws:iam::<ACCOUNT>:role/consul-ecs/*`. This allows IAM roles at the role path `/consul-ecs/`
to log in, and only those IAM roles in the same AWS account where the ACL controller is running.
* The role path can be changed by setting the `iam_role_path` input variable for the `mesh-task` and
`acl-controller` modules, or by passing the `-iam-role-path` flag to the `consul-ecs
acl-controller` command.
* Each instance of the auth method is shared by ACL controllers in the same Consul datacenter. Each
controller updates the auth method, if necessary, to include additional entries in the
`BoundIAMPrincipalARNs` list. This enables the use of the auth method with ECS clusters in
different AWS accounts, for example. This does not apply when using Consul Enterprise admin
partitions because auth method instances are not shared by multiple controllers in that case.
### Task Monitoring
After startup, the ACL controller monitors tasks in the same ECS cluster where the ACL controller is
running in order to discover newly running tasks and tasks that have stopped.
The ACL controller cleans up tokens created by `consul login` for tasks that are no longer running.
Normally, each task attempts `consul logout` commands when the task stops to destroy its tokens.
However, in unstable conditions the `consul logout` command may fail to clean up a token.
The ACL controller runs continually to ensure those unused tokens are soon removed.
### Admin Partitions and Namespaces<EnterpriseAlert inline />
When [admin partitions and namespaces](/consul/docs/ecs/enterprise#admin-partitions-and-namespaces) are enabled,
the ACL controller is assigned to its configured admin partition. It supports one ACL controller instance per ECS
cluster. This results in an architecture with one admin partition per ECS cluster.
When admin partitions and namespace are enabled, the ACL controller performs the following
additional actions:
* At startup, creates its assigned admin partition if it does not exist.
* Inspects task tags for new ECS tasks to discover the task's intended partition
and namespace. The ACL controller ignores tasks with a partition tag that does not match the
controller's assigned partition.
* Creates namespaces when tasks start up. Namespaces are only created if they do not exist.
* Creates auth method instances for client and service tokens in controller's assigned admin partition.
## ECS Health Check Syncing
If the following conditions apply, ECS health checks automatically sync with Consul health checks for all application containers:
* marked as `essential`
* have ECS `healthChecks`
* are not configured with native Consul health checks
The `mesh-init` container creates a TTL health check for every container that fits these criteria
and the `health-sync` container ensures that the ECS and Consul health checks remain in sync.
- An `iam:GetRole` permission to fetch itself. Refer to [IAM Policies](/consul/docs/security/acl/auth-methods/aws-iam#iam-policies) for additional information.
- A `consul.hashicorp.com.service-name` tag on the task role which contains the Consul service name for the application in this task.
- When using Consul Enterprise, add a `consul.hashicorp.com.namespace` tag on the task role indicating the Consul Enterprise namespace where this service is registered.

47
website/content/docs/ecs/deploy/bind-addresses.mdx Normal file
View File

@ -0,0 +1,47 @@
---
layout: docs
page_title: Configure the ECS task bind address
description: >-
Learn how to bind workloads to the loopback address, also called localhost and 127.0.0.1, so that your applications only send and receive traffic through Consul service mesh.
---
# Configure the ECS task bind address
This topic describes how to configure the bind address for your workloads to the loopback address.
## Introduction
Binding workloads to the loopback address ensures that your application only receives traffic through the dataplane container running in the same task, which limits requests to the service mesh. The loopback address is also called `localhost`, `lo`, and `127.0.0.1`. If your application is listening on all interfaces, such as `0.0.0.0`, then other applications can bypass the proxy and call it directly.
## Requirements
Consul service mesh must be deployed to ECS before you can bind a network address. For more information, refer to the following topics:
- [Deploy Consul to ECS using the Terraform module](/consul/docs/ecs/deploy/install-terraform)
- [Deploy Consul to ECS manually](/consul/docs/ecs/deploy/install-manual)
## Change the listening address
Changing the listening address is specific to your language and framework, but binding the loopback address to a dynamic value, such as an environment variable, is a best practice:
```bash
$ export BIND_ADDRESS="127.0.0.1:8080"
```
The following examples demonstrate how to bind the loopback address to an environment variable in golang and Django (Python):
<CodeTabs>
```go
s := &http.Server{
Addr: os.Getenv("BIND_ADDRESS"),
...
}
log.Fatal(s.ListenAndServe())
```
```bash
python manage.py runserver "$BIND_ADDRESS"
```
</CodeTabs>

79
website/content/docs/ecs/deploy/configure-routes.mdx Normal file
View File

@ -0,0 +1,79 @@
---
layout: docs
page_title: Configure routes between ECS tasks
description: >-
Learn how to configure routes between tasks after deploying Consul service mesh to your ECS workloads.
---
# Configure routes between ECS tasks
This topic describes how to configure routes between tasks after registering the tasks to Consul service mesh.
## Overview
To enable tasks to call through the service mesh, complete the following steps:
1. Configure the sidecar proxy to listen on a different port for each upstream service your application needs to call.
1. Modify your application to make requests to the sidecar proxy on the specified port.
## Requirements
Consul service mesh must be deployed to ECS before you can bind a network address. For more information, refer to the following topics:
- [Deploy Consul to ECS using the Terraform module](/consul/docs/ecs/deploy/install-terraform)
- [Deploy Consul to ECS manually](/consul/docs/ecs/deploy/install-manual)
## Configure the sidecar proxy
Add the `upstreams` block to your application configuration and specify the following fields:
- `destinationName`: Specifies the name of the upstream service as it is registered in the Consul service catalog.
- `localBindPort`: Specifies the port that the proxy forwards requests to. You must specify an unused port but it does not need to match the upstream service port.
In the following example, the route from an application named `web` to an application named `backend` goes through port `8080`:
```hcl
module "web" {
family = "web"
upstreams = [
{
destinationName = "backend"
localBindPort = 8080
}
]
}
```
You must include all upstream services in the `upstream` configuration.
## Configure your application
Use an appropriate environment variable in your container definition to configure your application to call the upstream service at the loopback address.
In the following example, the `web` application calls the `backend` service by sending requests to the
`BACKEND_URL` environment variable:
```hcl
module "web" {
family = "web"
upstreams = [
{
destinationName = "backend"
localBindPort = 8080
}
]
container_definitions = [
{
name = "web"
environment = [
{
name = "BACKEND_URL"
value = "http://localhost:8080"
}
]
...
}
]
...
}
```

342
website/content/docs/ecs/deploy/manual.mdx Normal file
View File

@ -0,0 +1,342 @@
---
layout: docs
page_title: Deploy Consul to ECS manually
description: >-
Manually install Consul on Amazon Web Services ECS by using the Docker `consul-ecs` image to create task definitions that include required containers. Learn how to configure task definitions with example configurations.
---
# 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](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/Welcome.html) for details.
### Secure configuration requirements
You must meet the following requirements and prerequisites to enable security features in Consul service mesh:
- Enable [TLS encryption](https://developer.hashicorp.com/consul/docs/security/encryption#rpc-encryption-with-tls) on your Consul servers so that they can communicate security with Consul dataplane containers over gRPC.
- Enable [access control lists (ACLs)](/consul/docs/security/acl) on your Consul servers. ALCs 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](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/specifying-sensitive-data.html) 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](/consul/docs/security/acl/tokens/create/create-a-service-token)
- [Day 1: Security tutorial](https://developer.hashicorp.com/consul/tutorials/security) 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](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definitions.html) 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:
| Field name | Description | Type |
| --- | --- | --- |
| `family` | The task family name. This is used as the Consul service name by default. | string |
| `networkMode` | Must be `awsvpc`, which is the only network mode supported by Consul on ECS. | string |
| `volumes` | Volumes on the host for sharing configuration between containers for initial task setup. You must define a `consul_data` and `consul_binary` bind mount. Bind mounts can be mounted into one or more containers in order to share files among containers. For Consul on ECS, certain binaries and configuration are shared among containers during task startup. | list |
| `containerDefinitions` | Defines the application container that runs in the task. Refer to [Define your application container](#define-your-application-container). | list |
The following example shows the top-level fields:
```json
{
"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](/consul/docs/ecs/deploy/manual#secure-configuration-requirements).
Without these tags, the ACL controller is unable to provision a service token for the task.
| Tag | Description | Type | Default |
| --- | --- | --- | --- |
| `consul.hashicorp.com/mesh` | Enables the ECS controller. Set to `false` to disable the ECS controller. | String | `true` |
| `consul.hashicorp.com/service-name` | Specifies the name of the Consul service associated with this task. Required if the service name is different than the task `family`. | String | None |
| `consul.hashicorp.com/partition` | <EnterpriseAlert inline/> Specifies the Consul admin partition associated with this task. | String | `default` |
| `consul.hashicorp.com/namespace` | <EnterpriseAlert inline/> Specifies the name of the Consul namespace associated with this task. | String | `default` |
## Define your application container
Specify your application container configurations in the `containerDefinitions` field. The following table describes all `containerDefinitions` fields:
| Field name | Description | Type |
| --- | --- | --- |
| `name` | The name of your application container. | string |
| `image` | The container image used to run your application. | string |
| `essential` | Must be `true` to ensure the health of your application container affects the health status of the task. | boolean |
| `dependsOn` | Specifies container dependencies that ensure your application container starts after service mesh setup is complete. Refer to [Application container dependency configuration](#application-container-dependency-configuration) for details. | list |
Refer to the [ECS Task Definition](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html) 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:
```json
{
{
"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:
| Field name | Description | Type |
| --- | --- | --- |
| `name` | Specifies the name of the container. This must be `consul-dataplane`. | string |
| `image` | Specifies the Envoy image. This must be a [supported version of Envoy](/consul/docs/connect/proxies/envoy#supported-versions). | string |
| `dependsOn` | Specifies container dependencies that ensure the dataplane container starts after the control-pane container has written the Envoy bootstrap configuration file. Refer to [Dataplane container dependency configuration](#dataplane-container-dependency-configuration) for details. | list |
| `healthCheck` | Must be set as shown above to monitor the health of Envoy's primary listener port, which ties into container dependencies and startup ordering. | map |
| `mountPoints` | Specifies a shared volume so that the dataplane container can access and consume the Envoy configuration file that the control-plane container generates. The keys and values in this configuration must be defined as described in [Dataplane container dependency configuration](#dataplane-container-dependency-configuration). | list |
| `ulimits` | The nofile ulimit must be raised to a sufficiently high value so that Envoy does not fail to open sockets. | list |
| `entrypoint` | Must be set to the custom Envoy entrypoint `consul-ecs envoy-entrypoint` to facilitate graceful shutdown. | list |
| `command` | Specifies the startup command to pass the bootstrap configuration to Envoy. | list |
### 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:
```json
[
{
"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:
```json
{
"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:
| Field name | Description | Type |
| --- | --- | --- |
| `name` | Specifies the name of the container. This must be `control-plane`. | string |
| `image` | Specifies the `consul-ecs` image. Specify the following public AWS registry to avoid rate limits: `public.ecr.aws/hashicorp/consul-ecs` | string |
| `mountPoints` | Specifies a shared volume to store the Envoy bootstrap configuration file that the dataplane container can access and consume. The keys and values in this configuration must be defined as described in [Control-plane shared volume configuration](#control-plane-shared-volume-configuration). | list |
| `command` | Set to `["control-plane"]` so that the container runs the `control-plane` command. | list |
| `environment` | Specifies the `CONSUL_ECS_CONFIG_JSON` environment variable, which configures the container to connect to the Consul servers. Refer to [Control-plane to Consul servers configuration](#control-plane-to-Consul-servers-configuration) for details. | list |
### 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:
```json
"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](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task?tab=inputs) for information about the variables you can define. In the following example, the Consul server address is defined in the `consul_server_hosts` variable:
```hcl
variable "consul_server_hosts" {
description = "Address of Consul servers."
type = string
}
```
1. Add an `environment` block to the control-plane and ECS controller containers definition
1. Set the `environment.name` field to the `CONSUL_ECS_CONFIG_JSON` environment variable and the value to `local.encoded_config`.
```hcl
environment = [
{
name = "CONSUL_ECS_CONFIG_JSON",
value = local.encoded_config
}
]
```
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](/consul/docs/ecs/reference/config-json-schema).
## 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](https://docs.aws.amazon.com/AmazonECS/latest/userguide/create-task-definition-classic.html)
- [Register task definition CLI](https://docs.aws.amazon.com/cli/latest/reference/ecs/register-task-definition.html)
## 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](/consul/docs/ecs/architecture#consul-security-components) for additional information.
Verify that you have completed the prerequisites described in [Secure configuration requirements](#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`
The policy allows Consul to generate a token linked to the policy. Refer to [Create a service token](/consul/docs/security/acl/tokens/create/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](/consul/docs/security/acl/auth-methods/aws-iam#iam-policies) for instructions.
1. Add an `consul.hashicorp.com.service-name` tag to the task role that contains the Consul service name for the application in the task.
1. 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.
```shell-session
$ 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:
| Flag | Description | Type |
| --- | --- | --- |
| `-type` | Must be `aws-iam`. | String |
| `-name` | Specify a name for the auth method. Must be unique among all auth methods. | String |
| `-description` | Specify a description for the auth method. | String |
| `-config` | A JSON string containing the configuration for the auth method. Refer to [Auth method `-config` parameter](#auth-method–config-parameter) for details. | String |
| `-partition` | <EnterpriseAlert inline/> Specifies an admin partition that the auth method is valid for. | String |
#### Auth method `-config` parameter
You must specify the following configuration in the `-config` flag:
| Flag | Description | Type |
| --- | --- | --- |
| `BoundIAMPrincipalArns` | Specifies a list of trusted IAM roles. We recommend using a wildcard to trust IAM roles at a particular path. | List |
| `EnableIAMEntityDetails` | Must be `true` so that the auth method can retrieve IAM role details, such as the role path and role tags. | Boolean |
| `IAMEntityTags` | Specifies a list of IAM role tags to make available to binding rules. Must include the service name tag. | List |
Refer to the [auth method configuration parameters documentation](/consul/docs/security/acl/auth-methods/aws-iam#config-parameters) 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.
```shell-session
$ 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](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/specifying-sensitive-data-parameters.html)
- [AWS Secrets Manager](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/specifying-sensitive-data-secrets.html)
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 <EnterpriseAlert inline/>
You can configure Consul servers connected to your ECS workloads to capture a log of authenticated events. Refer to [Audit Logging](/consul/docs/enterprise/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](/consul/docs/ecs/deploy/configure-routes)
- [Configure the ECS task bind address](/consul/docs/ecs/deploy/bind-addresses)

99
website/content/docs/ecs/deploy/migrate-existing-tasks.mdx Normal file
View File

@ -0,0 +1,99 @@
---
layout: docs
page_title: Migrate existing tasks to Consul service mesh
description: >-
You can migrate tasks in existing Amazon Web Services ECS deployments to a service mesh deployed with Terraform. Learn how to convert a task specified as an ECS task definition into a `mesh-task` Terraform module.
---
# Migrate existing tasks to Consul on ECS with Terraform
To migrate existing tasks to Consul, rewrite the existing Terraform code for your tasks so that the container definitions include the [`mesh-task` Terraform module](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task).
Your tasks must already be defined in Terraform using the `ecs_task_definition` resource so that they can then be converted to use the `mesh-task` module.
## Example
The following example shows an existing task definition configured in Terraform:
```hcl
resource "aws_ecs_task_definition" "my_task" {
family = "my_task"
requires_compatibilities = ["FARGATE"]
network_mode = "awsvpc"
cpu = 256
memory = 512
execution_role_arn = "arn:aws:iam::111111111111:role/execution-role"
task_role_arn = "arn:aws:iam::111111111111:role/task-role"
container_definitions = jsonencode(
[{
name = "example-client-app"
image = "docker.io/org/my_task:v0.0.1"
essential = true
portMappings = [
{
containerPort = 9090
hostPort = 9090
protocol = "tcp"
}
]
cpu = 0
mountPoints = []
volumesFrom = []
}]
)
}
resource "aws_ecs_service" "my_task" {
name = "my_task"
cluster = "arn:aws:ecs:us-east-1:111111111111:cluster/my-cluster"
task_definition = aws_ecs_task_definition.my_task.arn
desired_count = 1
network_configuration {
subnets = ["subnet-abc123"]
}
launch_type = "FARGATE"
}
```
Replace the `aws_ecs_task_definition` resource with the `mesh-task` module so that Consul adds the necessary dataplane containers that enable your task to join the mesh. The `mesh-task` module uses inputs similar to your old ECS task definition but creates a new version of the task definition with additional containers.
The following Terraform configuration uses the `mesh-task` module to replace the previous example's task definition:
```hcl
module "my_task" {
source = "hashicorp/consul-ecs/aws//modules/mesh-task"
version = "<latest version>"
family = "my_task"
container_definitions = [
{
name = "example-client-app"
image = "docker.io/org/my_task:v0.0.1"
essential = true
portMappings = [
{
containerPort = 9090
hostPort = 9090
protocol = "tcp"
}
]
cpu = 0
mountPoints = []
volumesFrom = []
}
]
port = 9090
consul_server_hosts = "<address of the Consul server>"
}
```
Note the following differences:
- The `execution_role_arn` and `task_role_arn` fields are removed. The `mesh-task` module creates the task and execution roles by default. If you need to use existing IAM roles, set the `task_role` and `execution_role` fields to pass in existing roles.
- The `port` field specifes the port that your application listens on. If your application has no listening port, set `outbound_only = true` and remove the `port` field.
- The `jsonencode()` function is removed from the `container_definitions` field.
The `mesh-task` module creates a new version of your task definition with the necessary dataplane containers so you can delete your existing `aws_ecs_task_definition` resource.

478
website/content/docs/ecs/deploy/terraform.mdx Normal file
View File

@ -0,0 +1,478 @@
---
layout: docs
page_title: Deploy Consul to ECS using the Terraform module
description: >-
Terraform modules simplify the process to install Consul on Amazon Web Services ECS. Learn how to create task definitions, schedule tasks for your service mesh, and configure routes with example configurations so that you can Deploy Consul to ECS using Terraform.
---
# Deploy Consul to ECS using the Terraform module
This topic describes how to create a Terraform configuration that deploys Consul service mesh to your ECS cluster workloads. Consul server agents do not run on ECS and must be deployed to another runtime, such as EKS, and connected to your ECS workloads. Refer [Consul on AWS Elastic Container Service overview](/consul/docs/ecs) for additional information.
## Overview
Create a Terraform configuration file that includes the ECS task definition and Terraform modules that build the Consul service mesh components. The task definition is the ECS blueprint for your software services on AWS. Refer to the [ECS task definitions documentation](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definitions.html) for additional information.
You can add the following modules and resources to your Terraform configuration:
- `mesh-task` module: Adds the Consul ECS control-plane and Consul dataplane containers to the task definition along with your application container. Envoy runs as a subprocess within the Consul dataplane container.
- `aws_ecs_service` resource: Adds an ECS service to run and maintain your task instance.
- `gateway-task` module: Adds mesh gateway containers to the cluster. Mesh gateways enable service-to-service communication across different types of network areas.
To enable Consul security features for your production workloads, you must also deploy the `controller` module, which provisions ACL tokens for service mesh tasks.
After defining your Terraform configuration, use `terraform apply` to deploy Consul to your ECS cluster.
## Requirements
- You should be familiar with creating Terraform configuration files. Refer to the [Terraform documentation](/terraform/docs) for information about how to get started with Terraform.
- You should be familiar with AWS ECS. Refer to [What is Amazon Elastic Container Service](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/Welcome.html) in the Amazon AWS documentation for additional information.
- If you intend to use the `gateway-task` module to deploy mesh gateways, you must enable TLS. Refer to [Configure the ECS controller](#configure-the-ecs-controller) for additional information.
### Secure configuration requirements
You must meet the following requirements and prerequisites to enable security features in Consul service mesh:
- Enable [TLS encryption](/consul/docs/security/encryption#rpc-encryption-with-tls) on your Consul servers so that they can communicate securely with Consul containers over gRPC.
- Enable [access control lists (ACLs)](/consul/docs/security/acl) on your Consul servers. ALCs 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](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/specifying-sensitive-data.html) in the AWS documentation for additional information.
Additionally, 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.
You should be familiar with configuring Consul's secure features, including how to create ACL tokens and policies. Refer to the following resources for additional information:
- [Create a service token](/consul/docs/security/acl/tokens/create/create-a-service-token)
- [Day 1: Security tutorial](https://developer.hashicorp.com/consul/tutorials/security)
## Create the task definition
Create a Terraform configuration file and add your ECS task definition. The task definition includes your application containers, Consul control-plane container, dataplane container, and controller container. If you intend to peer the service mesh to multiple Consul datacenters or partitions, [add the gateway-task module](#configure-the-gateway-task-module), which deploys gateway containers that enable connectivity between network areas in your network.
## Configure the mesh task module
Add a `module` block to your Terraform configuration and specify the following fields:
- `source`: Specifies the location of the `mesh-task` module. This field must be set to `hashicorp/consul-ecs/aws//modules/mesh-task`. The `mesh-task` module automatically adds the Consul service mesh infrastructure when you apply the Terraform configuration.
- `version`: Specifies the version of the `mesh-task` module to use.
- `family`: Specifies the [ECS task definition family](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#family). Consul also uses the `family` value as the Consul service name by default.
- `container_definitions`: Specifies a list of [container definitions](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#container_definitions) for the task definition. This field is where you include your application containers.
Refer to the [`mesh-task` module reference documentation in the Terraform registry](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task?tab=inputs) for information about all options you can configure.
You should also configure the ACL and encryption settings if they are enabled on your Consul servers. Refer to [Enable secure deployment](#enable-secure-deployment) for additional information.
In the following example, the Terraform configuration file `mesh-task.tf` creates a task definition with an application container called `example-client-app`:
<CodeBlockConfig filename="mesh-task.tf">
```hcl
module "my_task" {
source = "hashicorp/consul-ecs/aws//modules/mesh-task"
version = "<latest version>"
family = "my_task"
container_definitions = [
{
name = "example-client-app"
image = "docker.io/org/my_task:v0.0.1"
essential = true
portMappings = [
{
containerPort = 9090
hostPort = 9090
protocol = "tcp"
}
]
cpu = 0
mountPoints = []
volumesFrom = []
}
]
port = 9090
}
```
</CodeBlockConfig>
The following fields are required. Refer to the [module reference documentation](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task?tab=inputs) for a complete reference.
## Configure Consul server settings
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 the TLS settings for gRPC and HTTP traffic. Refer to the [mesh task module reference](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/gateway-task?tab=inputs) for information about the variables you can define. In the following example, the Consul server address is defined in the `consul_server_hosts` variable:
```hcl
variable "consul_server_hosts" {
description = "Address of Consul servers."
type = string
}
```
1. Add an `environment` block to the control-plane and ECS controller containers definition.
1. Set the `environment.name` field to the `CONSUL_ECS_CONFIG_JSON` environment variable and the value to `local.encoded_config`.
```hcl
environment = [
{
name = "CONSUL_ECS_CONFIG_JSON",
value = local.encoded_config
}
]
```
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](/consul/docs/ecs/reference/consul-server-json).
## Configure an ECS service to run your task instances
To start a task using the task definition, add the `aws_ecs_service` resource to your configuration to create an ECS service. [ECS services](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs_services.html) are one of the most common ways to start tasks using a task definition.
Reference the `mesh-task` module's `task_definition_arn` output value in your `aws_ecs_service` resource. The following example adds an ECS service for a task definition referenced in as `module.my_task.task_defintion_arn`:
<CodeBlockConfig filename="mesh-task.tf" highlight="6-12">
```hcl
module "my_task" {
source = "hashicorp/consul-ecs/aws//modules/mesh-task"
...
}
resource "aws_ecs_service" "my_task" {
name = "my_task_service"
task_definition = module.my_task.task_definition_arn
launch_type = "FARGATE"
propagate_tags = "TASK_DEFINITION"
...
}
```
</CodeBlockConfig>
Refer to [`aws_ecs_service` in the Terraform registry](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ecs_service) for a complete configuration reference.
If you are deploying a test instance of your ECS application, you can apply your configuration in Terraform. Refer to [Run your configuration](#run-your-configuration) for instructions. To configure your deployment for a production environment, you must also deploy the ECS controller module. Refer to [Configure the ECS controller](#configure-the-ecs-controller) for instructions.
If you intend to leverage multi-datacenter Consul features, such as WAN federation and cluster peering, then you must add the `gateway-task` module for each Consul datacenter in your network. Refer to [Configure the gateway task module](#configure-the-gateway-task-module) for instructions.
## Configure the gateway task module
The `gateway-task` module deploys a mesh gateway, which enables service-to-service communication across network areas. Mesh gateways detect the server name indication (SNI) header from the service mesh session and route the connection to the appropriate destination.
Refer to the following documentation for additional information:
- [WAN Federation via Mesh Gateways](/consul/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways)
- [Service-to-service Traffic Across Datacenters](/consul/docs/connect/gateways/mesh-gateway/service-to-service-traffic-wan-datacenters)
To use mesh gateways, TLS must be enabled in your cluster. Refer to the [requirements section](#requirements) for additional information.
1. Add a `module` block to your Terraform configuration file and specify a label. The label is a unique identifier for the gateway.
1. Add a `source` to the `module` and specify the location of the `gateway-task`. The value must be `hashicorp/consul-ecs/aws//modules/gateway-task`.
1. Specify the following required inputs:
- `ecs_cluster_arn`: The ARN of the ECS cluster for the gateway.
- `family`: Specifies a name for multiple versions of the task. Refer to the [AWS documentation](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#family) for details.
- `kind`: Set to `mesh-gateway`
- `subnets`: Specifies a list of subnet IDs where the gateway task should be deployed.
1. If you are deploying to a production environment, you must also add the `acl` and `tls` configurations. Refer to [Configure the ECS controller](#configure-the-ecs-controller) for details.
1. Configure any additional parameters necessary for your environment. Refer to the [module reference documentation](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/gateway-task?tab=inputs) for information about all parameters.
The following example defines a mesh gateway task called `my-gateway`:
<CodeBlockConfig filename="mesh-gateway.tf">
```hcl
module "my_mesh_gateway" {
source = "hashicorp/consul-ecs/aws//modules/gateway-task"
version = "<latest version>"
kind = "mesh-gateway"
family = "my-gateway"
ecs_cluster_arn = "<ECS cluster ARN>"
subnets = ["<subnet ID>"]
consul_server_hosts = "<address of the Consul server>"
tls = true
consul_ca_cert_arn = "<Secrets manager secret ARN>"
}
```
</CodeBlockConfig>
Refer to [gateway-task module in the Terraform registry](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/gateway-task?tab=inputs) for a complete reference.
Refer to the [gateway task configuration examples](#gateway-task-configuration-examples) for additional example configurations.
## Configure the ECS controller
Deploy the ECS controller container to its own ECS task in the cluster. Refer to [ECS controller container](/consul/docs/ecs/reference/architecture#ecs-controller) for details about the container.
Verify that you have completed the prerequisites described in [Secure configuration requirements](#secure-configuration-requirements) and complete the following steps to configure the controller container.
### Create a an ACL token for the controller
1. On the Consul server, create a policy that grants the following access for the controller:
- `acl:write`
- `operator:write`
- `node:write`
The policy allows Consul to generate a token linked to the policy. Refer to [Create a service token](/consul/docs/security/acl/tokens/create/create-a-service-token) for instructions.
1. Create a token and link it to the ACL controller policy. Refer to the [ACL tokens documentation](/consul/docs/security/acl/tokens) for instructions.
### Configure an AWS secrets manager secret
Add the `aws_secretsmanager_secret` resource to your Terraform configuration and specify values for retrieving the CA and TLS certificates. The resource enables services to communicate over TLS and present ACL tokens. The ECS controller also uses the secret manager to retrieve the value of the bootstrap token.
In the following example, Terraform creates the CA certificates for gRPC and HTTPS in the secrets manager. Consul retrieves the CA certificate PEM file from the secret manager so that the mesh task can use TLS for HTTP and gRPC traffic:
<CodeBlockConfig filename="secret.tf">
```hcl
resource "tls_private_key" "ca" {
algorithm = "ECDSA"
ecdsa_curve = "P384"
}
resource "tls_self_signed_cert" "ca" {
private_key_pem = tls_private_key.ca.private_key_pem
subject {
common_name = "Consul Agent CA"
organization = "HashiCorp Inc."
}
// 5 years.
validity_period_hours = 43800
is_ca_certificate = true
set_subject_key_id = true
allowed_uses = [
"digital_signature",
"cert_signing",
"crl_signing",
]
}
resource "aws_secretsmanager_secret" "ca_key" {
name = "${var.name}-${var.datacenter}-ca-key"
recovery_window_in_days = 0
}
resource "aws_secretsmanager_secret_version" "ca_key" {
secret_id = aws_secretsmanager_secret.ca_key.id
secret_string = tls_private_key.ca.private_key_pem
}
resource "aws_secretsmanager_secret" "ca_cert" {
name = "${var.name}-${var.datacenter}-ca-cert"
recovery_window_in_days = 0
}
resource "aws_secretsmanager_secret_version" "ca_cert" {
secret_id = aws_secretsmanager_secret.ca_cert.id
secret_string = tls_self_signed_cert.ca.cert_pem
}
```
</CodeBlockConfig>
Note that you could use a single `CERT PEM` for both variables. The `consul_ca_cert_arn` is the default ARN applicable to both the protocols. You can also use protocol-specific certificate PEMs with the `consul_https_ca_cert_arn` and `consul_grpc_ca_cert_arn` variables.
The following Terraform configuration passes the generated CA certificate ARN to the `mesh-task` module and ensures that the CA certificate and PEM variable are set for both HTTPS and gRPC communication.
<CodeBlockConfig filename="secret.tf">
```hcl
module "my_task" {
source = "hashicorp/consul-ecs/aws//modules/mesh-task"
version = "<version>"
...
tls = true
consul_ca_cert_arn = aws_secretsmanager_secret.ca_cert.arn
}
```
</CodeBlockConfig>
### Enable secure deployment
To enable secure deployment, add the following configuration to the task module.
<CodeBlockConfig filename="secret.tf">
```hcl
module "my_task" {
source = "hashicorp/consul-ecs/aws//modules/mesh-task"
version = "<version>"
...
tls = true
consul_grpc_ca_cert_arn = aws_secretsmanager_secret.ca_cert.arn
acls = true
consul_server_hosts = "https://consul-server.example.com"
consul_https_ca_cert_arn = aws_secretsmanager_secret.ca_cert.arn
}
```
</CodeBlockConfig>
### Complete configuration examples
The [terraform-aws-consul-ecs GitHub repository](https://github.com/hashicorp/terraform-aws-consul-ecs/tree/main/examples) contains examples that you can reference to help you deploy Consul service mesh to your ECS workloads.
## Apply your Terraform configuration
Run Terraform to create the task definition.
Save the Terraform configuration for the task definition to a file, such as `mesh-task.tf`.
You should place this file in a directory alongside other Terraform configuration files for your project.
The `mesh-task` module requires the AWS Terraform provider. The following example shows how to include
and configure the AWS provider in a file called `provider.tf`. Refer to [AWS provider in the Terraform registry](https://registry.terraform.io/providers/hashicorp/aws/latest/docs)
for additional documentation and specifications.
<CodeBlockConfig filename="provider.tf">
```hcl
terraform {
required_providers {
aws = {
source = "hashicorp/aws"
version = "<latest version>"
}
}
}
provider "aws" {
region = "<AWS region>"
...
}
```
</CodeBlockConfig>
Specify any additional AWS resources for your project in Terraform configuration files
in the same directory. The following example shows a basic project directory:
```shell-session
$ ls
mesh-task.tf
provider.tf
...
```
Issue the following commands to run the configuration:
1. `terraform init`: This command downloads dependencies, such as Terraform providers.
1. `terraform apply`: This command directs Terraform to create the AWS resources, such as the task definition from the `mesh-task` module.
Terraform reads all files in the current directory that have a `.tf` file extension.
Refer to the [Terraform documentation](/terraform/docs) for more information and Terraform best practices.
## 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](/consul/docs/ecs/deploy/configure-routes)
- [Configure the ECS task bind address](/consul/docs/ecs/deploy/bind-addresses)
## Gateway task configuration examples
The following examples illustrate how to configure the `gateway-task` for different use cases.
### Ingress
Mesh gateways need to be reachable over the WAN to route traffic between datacenters. Configure the following options in the `gateway-task` module to enable ingress through the mesh gateway.
| Input variable | Type | Description |
| --- | --- | --- |
| `lb_enabled` | Boolean | Set to `true` to automatically deploy and configure a network load balancer for ingress to the mesh gateway. |
| `lb_vpc_id` | string | Specifies the VPC to launch the load balancer in. |
| `lb_subnets` | list of strings | Specifies one or more public subnets to associate with the load balancer. |
<CodeBlockConfig filename="mesh-gateway.tf">
```hcl
module "my_mesh_gateway" {
...
lb_enabled = true
lb_vpc_id = "<VPC ID>"
lb_subnets = ["<public subnet IDs>"]
}
```
</CodeBlockConfig>
Alternatively, you can manually configure ingress to the mesh gateway and provide the `wan_address` and `wan_port` inputs to the `gateway-task` module. The `wan_port` field is optional. Port `8443` is used by default.
<CodeBlockConfig filename="mesh-gateway.tf">
```hcl
module "my_mesh_gateway" {
...
wan_address = "<public WAN address>"
wan_port = <public WAN port>
}
```
</CodeBlockConfig>
Mesh gateways route L4 TCP connections and do not terminate mTLS sessions. If you manually configure [AWS Elastic Load Balancing](https://aws.amazon.com/elasticloadbalancing/) for ingress to a mesh gateway, you must use an [AWS Network Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/introduction.html) or a [Classic Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/classic/introduction.html).
### ACLs
When ACLs are enabled, configure the following options in the `gateway-task` module.
| Option | Type | Description |
| --- | --- | --- |
| `acl` | Boolean | Set to `true` when ACLs are enabled. |
| `consul_server_hosts` | string | Specifies the HTTP `address` of the Consul server. Required for the mesh gateway task to log into Consul using the IAM auth method so that it can obtain its client and service tokens. |
| `consul_https_ca_cert_arn` | string | Specifies ARN of the Secrets Manager secret that contains the certificate for the Consul HTTPS API. |
<CodeBlockConfig filename="mesh-gateway.tf">
```hcl
module "my_mesh_gateway" {
...
acls = true
consul_server_hosts = "<HTTP address of the Consul server>"
tls = true
consul_https_ca_cert_arn = "<Secrets Manager secret ARN>"
}
```
</CodeBlockConfig>
### WAN federation
Configure the following options in the `gateway-task` to enable [WAN federation through mesh gateways](/consul/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways).
| Option | Type | Description |
| --- | --- | --- |
| `consul_datacenter` | string | Specifies the name of the local Consul datacenter. |
| `consul_primary_datacenter` | string | Specifies the name of the primary Consul datacenter. |
| `enable_mesh_gateway_wan_federation` | Boolean | Set to `true` to enable WAN federation. |
| `enable_acl_token_replication` | Boolean | Set to `true` to enable ACL token replication and allow the creation of local tokens secondary datacenters. |
The following example shows how to configure the `gateway-task` module.
<CodeBlockConfig filename="mesh-gateway.tf">
```hcl
module "my_mesh_gateway" {
...
enable_mesh_gateway_wan_federation = true
}
```
</CodeBlockConfig>
When federating Consul datacenters over the WAN with ACLs enabled, [ACL Token replication](/consul/docs/security/acl/acl-federated-datacenters) must be enabled on all server and client agents in all datacenters.

4
website/content/docs/ecs/enterprise.mdx
View File

@ -26,7 +26,7 @@ module "my_task" {
## Licensing
!> **Warning:** Consul Enterprise is currently only fully supported when [ACLs are enabled](/consul/docs/ecs/terraform/secure-configuration).
!> **Warning:** Consul Enterprise is currently only fully supported when [ACLs are enabled](/consul/docs/ecs/deploy/terraform#secure-configuration-requirements).
Consul Enterprise [requires a license](/consul/docs/enterprise/license/overview). If running
Consul on ECS with ACLs enabled, the license will be automatically pulled down from Consul servers.
@ -95,7 +95,7 @@ module "acl_controller" {
</CodeBlockConfig>
Services are assigned to admin partitions and namespaces through the use of [task tags](/consul/docs/ecs/manual/install#task-tags).
Services are assigned to admin partitions and namespaces through the use of [task tags](/consul/docs/ecs/deploy/manual#configure-task-tags).
The `mesh-task` module automatically adds the necessary tags to the task definition.
If the ACL controller is configured for admin partitions, services on the mesh will
always be assigned to an admin partition and namespace. If the `mesh-task` does not define

58
website/content/docs/ecs/index.mdx
View File

@ -2,39 +2,53 @@
layout: docs
page_title: Consul on AWS Elastic Container Service (ECS) Overview
description: >-
Consul's architecture adapts to Amazon Web Services ECS by running each task with an application container, a client agent, and an Envoy proxy. Learn how Consul service mesh works on ECS and find getting started tutorials for several scenarios.
You can deploy Consul service mesh applications to Amazon Web Services ECS by running each task with an application container, a client agent, and an Envoy proxy. Learn how Consul service mesh works on ECS and find getting started tutorials for several scenarios.
---
# Consul on AWS Elastic Container Service (ECS) Overview
# Consul on AWS Elastic Container Service (ECS) overview
This overview provides information about connecting your workloads managed by [AWS Elastic Container Service (ECS)](https://aws.amazon.com/ecs/) to a Consul service mesh. A Consul service mesh automates service-to-service authorization and encryption across your Consul services. You can use a service mesh in ECS networks to secure communication between ECS tasks and communication between tasks and external services.
You can deploy Consul service mesh applications to [AWS Elastic Container Service](https://aws.amazon.com/ecs/) (ECS) using either our official [Terraform modules](/consul/docs/ecs/terraform/install) or by [manually configuring the task definition](/consul/docs/ecs/manual/install).
## Service Mesh
## Workflow
Using Consul on AWS ECS enables you to add your ECS tasks to the service mesh and
take advantage of features such as zero-trust-security, intentions, observability,
traffic policy, and more. You can also connect service meshes so that services deployed across your infrastructure environments can communicate.
You can install Consul on ECS with the [HashiCorp Terraform modules](/consul/docs/ecs/deploy/terraform) or by [manually configuring the task definition](/consul/docs/ecs/deploy/manual). We strongly recommend using the Terraform modules and resources because Terraform automatically builds and enables Consul service mesh containers for your workloads. The Terraform module installation method also allows you to add your existing ECS task definitions to the Consul service mesh without additional configuration.
## Architecture
### Terraform module installation
![Consul on ECS Architecture](/img/consul-ecs-arch.png)
1. Create and run a Terraform configuration that includes the ECS task, modules, and resources.
1. Configure routes between ECS tasks in your cluster. Once the service mesh is built, you must define paths for traffic between services.
1. Configure the ECS bind address. Binding to the loopback address allows the sidecar proxy running in the same task to only make requests within the service mesh.
Consul on ECS follows an [architecture](/consul/docs/architecture) similar to other platforms, but each ECS task is a
Consul node. An ECS task runs the user application container(s), as well as a Consul client container for control plane
communication and an [Envoy](https://envoyproxy.io/) sidecar proxy container to facilitate data plane communication for
[Consul service mesh](/consul/docs/connect).
For a detailed architecture overview, see the [Architecture](/consul/docs/ecs/architecture) page.
### Manual installation
## Getting Started
To manually install Consul, you must create definitions for each container that operates in the ECS cluster. Refer to [Architecture](/consul/docs/ecs/architecture) for information about the Consul containers you must deploy. Note that there is no manual process for creating gateway task containers. Gateways enable you to connect multiple datacenters or admin partitions. You must use Terraform if you want to deploy gateways to your network.
There are several ways to get started with Consul with ECS.
## Guidance
- The [Integrate your AWS ECS services into Consul service mesh](/consul/tutorials/cloud-integrations/consul-ecs) tutorial shows how to use Terraform to run Consul service mesh applications on ECS with self-managed Consul or HCP-managed Consul.
- The [Consul with Dev Server on Fargate](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/examples/dev-server-fargate) example installation deploys a sample application in ECS using the Fargate launch type.
- The [Consul with Dev Server on EC2](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/examples/dev-server-ec2) example installation deploys a sample application in ECS using the EC2 launch type.
Refer to the following documentation and tutorials for additional guidance.
Refer to the [Requirements](/consul/docs/ecs/requirements) and use one of the following sets of instructions when you're ready to install Consul on an existing ECS cluster and add tasks to the service mesh:
### Tutorials
- [Install with Terraform](/consul/docs/ecs/terraform/install)
- [Install Manually](/consul/docs/ecs/manual/install)
- [Integrate your AWS ECS services into Consul service mesh](/consul/tutorials/cloud-integrations/consul-ecs): Shows how to use Terraform to run Consul service mesh applications on ECS with self-managed Consul or HCP-managed Consul.
You can also refer to the following example configurations:
- [Examples on GitHub](https://github.com/hashicorp/terraform-aws-consul-ecs/tree/main/examples)
- [Consul with dev server on ECS using the Fargate launch type](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/examples/dev-server-fargate)
- [Consul with dev server onn ECS using the EC2 launch type](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/examples/dev-server-ec2)
### Documentation
- [Install Consul on ECS with Terraform](/consul/docs/ecs/deploy/terraform)
- [Configure routes between ECS tasks](/consul/docs/ecs/deploy/configure-routes)
- [Configure the ECS task bind address](/consul/docs/ecs/deploy/bind-addresses)
- [Install Consul on ECS manually](/consul/docs/ecs/deploy/manual)
### Reference
- [Architecture](/consul/docs/ecs/architecture)
- [Technical specifications](/consul/docs/ecs/tech-specs)
- [Task configuration reference](/consul/docs/ecs/reference/configuration-reference)
- [Cross-compatibility reference](/consul/docs/ecs/reference/compatibility)
- [Consul server JSON schema reference](/consul/docs/ecs/reference/consul-server-json)

190
website/content/docs/ecs/manual/acl-controller.mdx
View File

@ -1,190 +0,0 @@
---
layout: docs
page_title: ACL Controller Manual Installation - Consul on AWS Elastic Container Service (ECS)
description: >-
An ACL Controller is required to configure the AWS IAM auth method on Amazon Web Services ECS. Learn how to manually install ACL controllers by defining a task and a service and then configuring role policies.
---
# Manual Installation of ACL Controller for Consul on AWS Elastic Container Service (ECS)
This topic describes how to manually deploy the ACL controller, which will automatically configure the [AWS IAM Auth Method](/consul/docs/security/acl/auth-methods/aws-iam). If you are using Terraform, refer to the [Terraform Secure Configuration](/consul/docs/ecs/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](/consul/docs/ecs/manual/install#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 [Consul Security tutorials](/consul/tutorials/security) for an introduction and the [ACL system](/consul/docs/security/acl) 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](https://docs.aws.amazon.com/secretsmanager/latest/userguide/manage_create-basic-secret.html) from Consul in AWS Secrets Manager.
| Secret | Sample Secret Name | Description |
| --------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Consul server CA cert | `my-consul-ca-cert` | The 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 Token | `my-consul-bootstrap-token` | A 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.
```json
{
"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.
| Field name | Type | Description |
| ----------- | ------- | ---------------------------------------------------------------------------- |
| `family` | string | The task family name of your choice. |
| `networkMode` | string | Must 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 name | Type | Description |
| ------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | string | The container name, which should be `acl-controller` |
| `image` | string | The `consul-ecs` image. Use our public AWS registry, `public.ecr.aws/hashicorp/consul-ecs`, to avoid rate limits. |
| `command` | list | Should be set as shown. The startup command for the ACL controller. |
| `essential` | boolean | Must be `true` to ensure the health of your application container affects the health status of the task. |
| `secrets` | list | Should be set as shown. Configures the secrets the ECS service will retrieve and set as environment variables in the `acl-controller` container. |
| `environment` | string | Must 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.
| Flag | Type | Description |
| ------------------ | ------- | --------------------------------------------------------------------------------------------- |
| `-iam-role-path` | string | Specifies the path to IAM roles trusted by the AWS IAM auth method created by the controller. |
| `-log-level` | string | The 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.
| Name | Description |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `CONSUL_HTTP_TOKEN` | Must be set to the secret containing the bootstrap ACL token. |
| `CONSUL_CACERT_PEM` | If 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](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/service_definition_parameters.html) documentation
to complete the remaining details for your use case.
```json
{
"cluster": "<Your ECS cluster ARN>"
"desiredCount": 1,
"launchType": "FARGATE",
"serviceName": "my-acl-controller",
"taskDefinition": "<task definition ARN>",
...
}
```
| Field name | Type | Description |
| ---------------- | ------- | ---------------------------------------------------------------------------------------------------------------- |
| `cluster` | string | Set to your ECS cluster name or ARN. This must be the same ECS cluster where your service mesh applications run. |
| `desiredCount` | integer | Must be `1`. Only one instance of the ACL controller should run per ECS cluster. |
| `launchType` | string | Consul on ECS supports both the `FARGATE` and `EC2` launch types. |
| `serviceName` | string | The service name of your choice. |
| `taskDefinition` | string | Must be set to the ACL controller [task definition](/consul/docs/ecs/manual/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.
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ecs:ListTasks",
"ecs:DescribeTasks"
],
"Resource": ["*"]
}
]
}
```
The following are the required permissions.
| Action | Resource | Description |
| --------------------- | --------- | ------------------------------------------------------------ |
| `ecs:ListTasks` | `*` | Allow the ACL controller to watch for new tasks. |
| `ecs:DescribeTasks` | `*` | Allow 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.
```json
{
"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.
| Action | Resource | Description |
| ------------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------- |
| `secretsmanager:GetSecretValue` | `arn:aws:secretsmanager:us-west-2:000000000000:secret:<NAME>` | Allow ECS to retrieve this secret and inject the secret into the task. |

556
website/content/docs/ecs/manual/install.mdx
View File

@ -1,556 +0,0 @@
---
layout: docs
page_title: Install Manually - Consul on AWS Elastic Container Service (ECS)
description: >-
Manually install Consul on Amazon Web Services ECS by using the Docker `consul-ecs` image to create task definitions that include required containers. Learn how to configure task definitions with example configurations.
---
# Manual Installation of Consul on AWS Elastic Container Service (ECS)
The following instructions describe how to use the [`consul-ecs` Docker image](https://gallery.ecr.aws/hashicorp/consul-ecs) to manually create the ECS task definition without Terraform. If you prefer to use Terraform, refer to [Consul ECS Terraform module](/consul/docs/ecs/terraform/install).
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. Manually configuring mesh gateways without using the `gateway-task` Terraform module is not supported.
This topic does not include instructions for creating all AWS resources necessary to install Consul, such as a VPC or the ECS cluster. Refer to the linked guides in the [Getting Started](/consul/docs/ecs#getting-started) section for complete, runnable examples.
## Prerequisites
You should have some familiarity with AWS ECS. See [What is Amazon Elastic Container Service](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/Welcome.html) for details.
## Task Definition
Configure a task definition that creates the containers:
- Your application container
- An Envoy sidecar-proxy container
- A Consul client container
- A `consul-ecs-mesh-init` container for service mesh setup
- (Optional) A `consul-ecs-health-sync` container to sync ECS health checks into Consul
## Top-level fields
Your task definition must include the following top-level fields.
The `volumes` list contains two [bind mounts](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/bind-mounts.html),
named `consul_data` and `consul_binary`. Bind mounts are directories on the host which can be mounted into one or more containers
in order to share files among containers. For Consul on ECS, certain binaries and configuration are shared among containers
during task startup.
```json
{
"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"
}
]
}
```
| Field name | Type | Description |
| ---------------------- | ------ | ------------------------------------------------------------------------------------------------------------------ |
| `family` | string | The task family name. This is used as the Consul service name by default. |
| `networkMode` | string | Must be `awsvpc`, which is the only network mode supported by Consul on ECS. |
| `volumes` | list | Must be defined as shown above. Volumes are used to share configuration between containers for initial task setup. |
| `containerDefinitions` | list | The list of containers to run in this task (see [Application container](#application-container)). |
### Task Tags
The `tags` list must include the following if you are using the ACL controller in a [secure configuration](/consul/docs/ecs/manual/secure-configuration).
Without these tags, the ACL controller will be unable to provision a service token for the task.
| Tag Key | Tag Value | Description |
| ----------------------------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `consul.hashicorp.com/mesh` | `true` (string) | The ACL controller ignores tasks without this tag set to `true`. |
| `consul.hashicorp.com/service-name` | Consul service name | Specifies the Consul service associated with this task. Required if the service name is different than the task `family`. |
| `consul.hashicorp.com/partition` | Consul admin partition | <EnterpriseAlert inline />Specifies the Consul admin partition associated with this task. Defaults to the `default` admin partition if omitted. |
| `consul.hashicorp.com/namespace` | Consul namespace | <EnterpriseAlert inline />Specifies the Consul namespace associated with this task. Defaults to the `default` namespace if omitted. |
## Application container
First, include your application container in the `containerDefinitions` list
in the task definition.
Ensure that the `containerName` and `condition` fields in the `dependsOn` list
are specified as described in the following example. These are container dependencies,
which must be used to enforce a specific [startup order](/consul/docs/ecs/architecture#task-startup).
By using the following settings, your application container will start after `consul-ecs-mesh-init`
has completed task setup and after `sidecar-proxy` is ready to proxy traffic between
this task and the service mesh.
```json
{
"containerDefinitions": [
{
"name": "example-client-app",
"image": "docker.io/org/my_task:v0.0.1",
"essential": true,
"dependsOn": [
{
"containerName": "consul-ecs-mesh-init",
"condition": "SUCCESS"
},
{
"containerName": "sidecar-proxy",
"condition": "HEALTHY"
}
],
...
}
]
}
```
| Field name | Type | Description |
| ----------- | ------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `name` | string | The name of your application container. |
| `image` | string | The container image used to run your application. |
| `essential` | boolean | Must be `true` to ensure the health of your application container affects the health status of the task. |
| `dependsOn` | list | Must be set as shown above. Container dependencies ensure your application container starts after service mesh setup is complete. |
See the [ECS Task Definition](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html) documentation for a complete reference.
## `sidecar-proxy` container
The `sidecar-proxy` container runs [Envoy proxy](/consul/docs/connect/proxies/envoy) for Consul service mesh. In most cases, the container should contain the following parameters and values.
The `mountPoints` list must be set as shown in the following example. This will mount the shared `consul_data` volume into the
`sidecar-proxy` container at the path `/consul`. This volume is where the `consul-ecs-mesh-init` container copies the `envoy-bootstrap.json`
file and the `consul-ecs` binary, which are required to start Envoy. The `dependsOn` list must also be defined as follows to ensure the
`sidecar-proxy` container starts after `consul-ecs-mesh-init` has successfully written these files to the shared volume.
<CodeBlockConfig highlight="8-40">
```json
{
"containerDefinitions": [
{
"name": "example-client-app",
"image": "docker.io/org/my_task:v0.0.1",
...
},
{
"name": "sidecar-proxy",
"image": "envoyproxy/envoy-alpine:<VERSION>",
"essential": false,
"dependsOn": [
{
"containerName": "consul-ecs-mesh-init",
"condition": "SUCCESS"
}
],
"healthCheck": {
"retries": 3,
"command": ["nc", "-z", "127.0.0.1", "20000"],
"timeout": 5,
"interval": 30
},
"mountPoints": [
{
"readOnly": true,
"containerPath": "/consul",
"sourceVolume": "consul_data"
}
],
"ulimits": [
{
"name": "nofile",
"softLimit": 1048576,
"hardLimit": 1048576
}
],
"command": ["envoy", "--config-path", "/consul/envoy-bootstrap.json"],
"entryPoint": ["/consul/consul-ecs", "envoy-entrypoint"],
}
]
}
```
</CodeBlockConfig>
The following table describes the necessary configuration settings.
| Field name | Type | Description |
| ------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | string | The container name, which must be `sidecar-proxy`. |
| `image` | string | The Envoy image. This must be a [supported version of Envoy](/consul/docs/connect/proxies/envoy#supported-versions). |
| `dependsOn` | list | Must be set as shown above to ensure Envoy starts after the `consul-ecs-mesh-init` container has written the `envoy-bootstrap.json` config file for Envoy. |
| `healthCheck` | list | Must be set as shown above to monitor the health of Envoy's primary listener port, which ties into container dependencies and startup ordering. |
| `mountPoints` | list | Must be set as shown above to access the files shared in the `/consul` directory, like the Envoy bootstrap configuration file and the `consul-ecs` binary. |
| `ulimits` | list | The `nofile` ulimit must be raised to a sufficiently high value so that Envoy does not fail to open sockets. |
| `entrypoint` | list | Must be set to the custom Envoy entrypoint, `consul-ecs envoy-entrypoint`, to facilitate graceful shutdown. |
| `command` | list | The startup command. This passes the bootstrap configuration to Envoy. |
-> **NOTE**: Envoy and Consul must be compatible versions. See the [supported versions of Envoy](/consul/docs/connect/proxies/envoy#supported-versions) in the Consul documentation.
## `consul-client` container
Each task must include a Consul client container in order for the task to join your Consul cluster.
<CodeBlockConfig highlight="13-31">
```json
{
"containerDefinitions": [
{
"name": "example-client-app",
"image": "docker.io/org/my_task:v0.0.1",
...
},
{
"name": "sidecar-proxy",
"image": "envoyproxy/envoy-alpine:<ENVOY_VERSION>",
...
}
{
"name": "consul-client",
"image": "public.ecr.aws/hashicorp/consul:<CONSUL_VERSION>",
"mountPoints": [
{
"readOnly": false,
"containerPath": "/consul",
"sourceVolume": "consul_data"
},
{
"containerPath": "/bin/consul-inject",
"sourceVolume": "consul_binary"
}
],
"entryPoint": ["/bin/sh", "-ec"],
"command": [
"cp /bin/consul /bin/consul-inject/consul\n\nECS_IPV4=$(curl -s $ECS_CONTAINER_METADATA_URI_V4 | jq -r '.Networks[0].IPv4Addresses[0]')\n\n\ncat << EOF > /consul/agent-defaults.hcl\naddresses = {\n dns = \"127.0.0.1\"\n grpc = \"127.0.0.1\"\n http = \"127.0.0.1\"\n}\nadvertise_addr = \"$ECS_IPV4\"\nadvertise_reconnect_timeout = \"15m\"\nclient_addr = \"0.0.0.0\"\ndatacenter = \"dc1\"\nenable_central_service_config = true\nleave_on_terminate = true\nports {\n grpc = 8502\n}\nretry_join = [\n \"<Consul server location>\",\n]\ntelemetry {\n disable_compat_1.9 = true\n}\n\nEOF\n\ncat << EOF > /consul/agent-extra.hcl\naddresses = {\n dns = \"0.0.0.0\"\n}\nlog_level = \"debug\"\n\nEOF\n\nexec consul agent \\\n -data-dir /consul/data \\\n -config-file /consul/agent-defaults.hcl \\\n -config-file /consul/agent-extra.hcl\n"
]
}
]
}
```
</CodeBlockConfig>
| Field name | Type | Description |
| ------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `name` | string | The container name, which should always be `consul-client`. |
| `image` | string | The Consul image. Use our public AWS registry, `public.ecr.aws/hashicorp/consul`, to avoid rate limits. |
| `mountPoints` | list | Must be set as shown above. Volumes are mounted to share information with other containers for task setup. |
| `entrypoint` | list | Must be set to a plain shell so that the startup `command` works properly. |
| `command` | list | Specifies the contents of the [startup script](#consul-client-startup-script). Copy the script and format it into a JSON string. |
### Consul client startup script
The following script is used to start the Consul client for Consul on ECS.
```shell
# Copy the consul binary to a shared volume for `consul-ecs-mesh-init` to use to generate Envoy configuration.
cp /bin/consul /bin/consul-inject/consul
# At runtime, determine the IP address assigned to this ECS Task.
ECS_IPV4=$(curl -s $ECS_CONTAINER_METADATA_URI_V4 | jq -r '.Networks[0].IPv4Addresses[0]')
# Write the Consul agent configuration file.
cat << EOF > /consul/agent-defaults.hcl
addresses = {
dns = "127.0.0.1"
grpc = "127.0.0.1"
http = "127.0.0.1"
}
advertise_addr = "$ECS_IPV4"
advertise_reconnect_timeout = "15m"
client_addr = "0.0.0.0"
datacenter = "dc1"
enable_central_service_config = true
leave_on_terminate = true
ports {
grpc = 8502
}
retry_join = ["<consul server location>"]
telemetry {
disable_compat_1.9 = true
}
EOF
# Start the consul agent.
exec consul agent \
-data-dir /consul/data \
-config-file /consul/agent-defaults.hcl
```
The following table describes the values that you should use to configure the `command` script:
| Field name | Type | Description |
| -------------------- | ------- | ------------------------------------------------------------------------------------------------------------ |
| `addresses.*` | strings | Set the DNS, GRPC, and HTTP addresses to `127.0.0.1` to ensure these are not accessible outside of the task. |
| `advertise_addr` | string | Must be set to the task IP address so that other Consul agents know how to reach this agent. |
| `client_addr` | string | Must be set to an interface reachable by other Consul agents. |
| `datacenter` | string | Must be set to the Consul datacenter this task will join. |
| `leave_on_terminate` | boolean | Must be set to `true` so that the Consul agent leaves the cluster gracefully before exiting. |
| `retry_join` | string | Must be set to your Consul server location(s) so this agent can join the Consul cluster. |
-> **NOTE**: Use `exec` to start the Consul agent so that the Consul agent runs as PID 1. This ensures
the Consul agent directly receives signals from ECS, which is important for graceful shutdown of the Consul agent.
Refer to the [Consul Agent documentation](/consul/docs/agent/config/config-files#configuration_files) for a complete reference of Consul agent
configuration options.
## `consul-ecs-mesh-init` container
The `consul-ecs-mesh-init` container runs at task startup to setup this instance for Consul service mesh.
It registers the service and proxy for this task with Consul and writes Envoy bootstrap
configuration to a shared volume.
<CodeBlockConfig highlight="18-41">
```json
{
"containerDefinitions": [
{
"name": "example-client-app",
"image": "docker.io/org/my_task:v0.0.1",
...
},
{
"name": "sidecar-proxy",
"image": "envoyproxy/envoy-alpine:<ENVOY_VERSION>",
...
},
{
"name": "consul-client"
"image": "public.ecr.aws/hashicorp/consul:<CONSUL_VERSION>",
...
},
{
"name": "consul-ecs-mesh-init",
"image": "public.ecr.aws/hashicorp/consul-ecs:<CONSUL_ECS_VERSION>",
"command": ["mesh-init"],
"essential": false,
"environment": [
{
"name": "CONSUL_ECS_CONFIG_JSON",
"value": "{\"bootstrapDir\":\"/consul\",\"healthSyncContainers\":[],\"proxy\":{\"upstreams\":[{\"destinationName\":\"example-server-app\",\"localBindPort\":1234}]},\"service\":{\"checks\":[],\"meta\":{},\"name\":\"example-client-app\",\"port\":9090,\"tags\":[]}}"
}
],
"mountPoints": [
{
"readOnly": false,
"containerPath": "/consul",
"sourceVolume": "consul_data"
},
{
"readOnly": true,
"containerPath": "/bin/consul-inject",
"sourceVolume": "consul_binary"
}
]
}
]
}
```
</CodeBlockConfig>
| Field name | Type | Description |
| ----------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | string | The container name should be `consul-ecs-mesh-init`. |
| `image` | string | The `consul-ecs` image. Use our public AWS registry, `public.ecr.aws/hashicorp/consul-ecs`, to avoid rate limits. |
| `mountPoints` | list | Must be set as show above, so the `consul` and `consul-ecs` binaries can be shared among containers for task setup. |
| `command` | list | Set to `["mesh-init"]` so that the container runs the `consul-ecs mesh-init` command. |
| `environment` | list | This must include the [`CONSUL_ECS_CONFIG_JSON`](/consul/docs/ecs/manual/install#consul_ecs_config_json) variable. See below for details. |
### `CONSUL_ECS_CONFIG_JSON`
Consul uses the `CONSUL_ECS_CONFIG_JSON` environment variable to passed configurations to the `consul-ecs` binary in JSON format.
The following example configures a service named `example-client-app` with one upstream
service name `example-server-app`. The `proxy` and `service` blocks include information used by `consul-ecs-mesh-init` to register the service with Consul during task start up.
The same configuration format is used for
the `consul-ecs-health-sync` container.
```json
{
"bootstrapDir": "/consul",
"healthSyncContainers": [],
"proxy": {
"upstreams": [
{
"destinationName": "example-server-app",
"localBindPort": 1234
}
]
},
"service": {
"checks": [],
"meta": {},
"name": "example-client-app",
"port": 9090,
"tags": []
}
}
```
| Field name | Type | Description |
| ---------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `bootstrapDir` | string | This is the path of a shared volume that is mounted to other containers, where `consul-ecs-mesh-init` will write out Envoy configuration. |
| `healthSyncContainers` | list | Used for [health status syncing](/consul/docs/ecs/architecture#ecs-health-check-syncing) from ECS to Consul. See below for details. |
| `proxy.upstreams` | list | The upstream services that your application calls over the service mesh, if any. The `destinationName` and `localBindPort` fields are required. |
| `service.name` | string | The name used to register this service into the Consul service catalog. |
| `service.port` | integer | The port your application listens on. Set to `0` if your application does not listen on any port. |
| `service.checks` | list | Consul [checks](/consul/docs/services/usage/checks) to include so that Consul can run health checks against your application. |
See the [Configuration Reference](/consul/docs/ecs/configuration-reference) for a complete reference of fields.
## `consul-ecs-health-sync` container
Optionally, Consul ECS can sync health checks for this task into Consul checks.
This allows you to configure a health check for your application in one place and
see a consistent health status in both ECS and Consul.
For example, the following defines an ECS health check command that runs `curl localhost:9090/health`:
<CodeBlockConfig highlight="6-11">
```json
{
"containerDefinitions": [
{
"name": "example-client-app",
"image": "docker.io/org/my_task:v0.0.1",
"healthCheck": {
"retries": 3,
"command": ["CMD-SHELL", "curl localhost:9090/health"],
"timeout": 5,
"interval": 30
},
...
},
...
]
}
```
</CodeBlockConfig>
First, define which containers need their health status synced into Consul. To do this,
add the container name(s) to the `healthSyncContainers` list of the `CONSUL_ECS_CONFIG_JSON` variable,
as shown in the following example. This configuration must be passed to both the `consul-ecs-mesh-init`
and `consul-ecs-health-sync` containers.
<CodeBlockConfig highlight="3-3">
```json
{
"bootstrapDir": "/consul",
"healthSyncContainers": ["example-client-app"],
...
}
```
</CodeBlockConfig>
Next, set the `CONSUL_ECS_CONFIG_JSON` variable for the `consul-ecs-mesh-init` container.
The following example shows how the `CONSUL_ECS_CONFIG_JSON` variable should be formatted.
The JSON configuration is compacted down to a single line and escaped.
<CodeBlockConfig highlight="7-10">
```json
{
"containerDefinitions": [
{
"name": "consul-ecs-mesh-init",
"image": "public.ecr.aws/hashicorp/consul-ecs:<VERSION>",
"environment": [
{
"name": "CONSUL_ECS_CONFIG_JSON",
"value": "{\"bootstrapDir\":\"/consul\",\"healthSyncContainers\":[\"example-client-app\"],\"proxy\":{\"upstreams\":[{\"destinationName\":\"example-server-app\",\"localBindPort\":1234}]},\"service\":{\"checks\":[],\"meta\":{},\"name\":\"example-client-app\",\"port\":9090,\"tags\":[]}}"
}
],
...
},
...
]
}
```
</CodeBlockConfig>
Finally, include the `consul-ecs-health-sync` container in the `containerDefinitions` list.
Pass the same value for `CONSUL_ECS_CONFIG_JSON` for both the `consul-ecs-health-sync`
and `consul-ecs-mesh-init` containers.
<CodeBlockConfig highlight="23-40">
```json
{
"containerDefinitions": [
{
"name": "example-client-app",
"image": "docker.io/org/my_task:v0.0.1",
...
},
{
"name": "sidecar-proxy",
"image": "envoyproxy/envoy-alpine:<ENVOY_VERSION>",
...
},
{
"name": "consul-client"
"image": "public.ecr.aws/hashicorp/consul:<CONSUL_VERSION>",
...
},
{
"name": "consul-ecs-mesh-init",
"image": "public.ecr.aws/hashicorp/consul-ecs:<CONSUL_ECS_VERSION>",
...
},
{
"name": "consul-ecs-health-sync",
"image": "public.ecr.aws/hashicorp/consul-ecs:<CONSUL_ECS_VERSION>",
"command": ["health-sync"],
"essential": false,
"dependsOn": [
{
"containerName": "consul-ecs-mesh-init",
"condition": "SUCCESS"
}
],
"environment": [
{
"name": "CONSUL_ECS_CONFIG_JSON",
"value": "{\"bootstrapDir\":\"/consul\",\"healthSyncContainers\":[\"example-client-app\"],\"proxy\":{\"upstreams\":[{\"destinationName\":\"example-server-app\",\"localBindPort\":1234}]},\"service\":{\"checks\":[],\"meta\":{},\"name\":\"example-client-app\",\"port\":9090,\"tags\":[]}}"
}
]
}
]
}
```
</CodeBlockConfig>
| Field name | Type | Description |
| ------------- | ------ | ----------------------------------------------------------------------------------------------------------------- |
| `name` | string | The container name, which must be `consul-ecs-health-sync`. |
| `image` | string | The `consul-ecs` image. Use our public AWS registry, `public.ecr.aws/hashicorp/consul-ecs`, to avoid rate limits. |
| `command` | list | Must be set to `["health-sync"]` to run the `consul-ecs health-sync` command. |
| `dependsOn` | list | Must be set as shown above to ensure the `health-sync` container starts after service registration has completed. |
| `environment` | list | Must include the `CONSUL_ECS_CONFIG_JSON` variable to pass configuration to the `consul-ecs health-sync` command. |
# Next Steps
* Create the task definition using the [AWS Console](https://docs.aws.amazon.com/AmazonECS/latest/userguide/create-task-definition-classic.html) or the [AWS CLI](https://docs.aws.amazon.com/cli/latest/reference/ecs/register-task-definition.html), or another method of your choice.
* Create an [ECS Service](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs_services.html) to start tasks using the task definition.
* Follow the [Secure Configuration](/consul/docs/ecs/manual/secure-configuration) to get production-ready.

545
website/content/docs/ecs/manual/secure-configuration.mdx
View File

@ -1,545 +0,0 @@
---
layout: docs
page_title: Manual Secure Configuration - Consul on AWS Elastic Container Service (ECS)
description: >-
Securely configure Consul Service Mesh on Amazon Web Services ECS to protect the communication of sensitive data in production workloads. Learn how to manually configure auth methods to create tokens for clients and services and then apply tokens by role or policy.
---
# Manual Secure Configuration of Consul on AWS Elastic Container Service (ECS)
This topic describes how to enable Consul security features for your production workloads.
## Prerequisites
The following features must be configured for your Consul server cluster:
- [TLS encryption](/consul/docs/security/encryption#rpc-encryption-with-tls) for RPC communication between Consul clients and servers.
- [Gossip encryption](/consul/docs/security/encryption#gossip-encryption) for encrypting gossip traffic.
- [Access control lists (ACLs)](/consul/docs/security/acl) for authentication and authorization for Consul clients and services on the mesh.
You should already have followed the [manual installation instructions](/consul/docs/ecs/manual/install) to define the necessary components of the task definition for Consul on ECS.
You should be familiar with [specifying sensitive data](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/specifying-sensitive-data.html) on ECS.
You should be familiar with configuring Consul's secure features, including how to create ACL tokens and policies. Refer to the [ACL system documentation](/consul/docs/security/acl) and [Day 1: Security tutorials](/consul/tutorials/security) for an introduction and additional information.
## Auth Method
Tokens are artifacts within the ACL system that authenticate users, services, and Consul agents. Tokens are linked to policies that specify the resources the token bearer has access to when making requests in the network.
Auth Methods are a Consul server component that performs authentication against a trusted external party to authorize the creation of ACL tokens. The [AWS IAM auth method](/consul/docs/security/acl/auth-methods/aws-iam) is used to enable an ECS task to automatically obtain ACL tokens when the task starts up.
There are two types of ACL tokens for Consul on ECS:
* **Client tokens:** used by the `consul-client` containers to join the Consul cluster
* **Service tokens:** used by sidecar containers for service registration and health syncing
This section describes how to manually configure the AWS IAM auth method for Consul on ECS. Alternatively, you can install the ACL controller to ease the burden of creating these resources. The ACL controller can automatically configure ACL resources for Consul on ECS. For additional details, refer to [ACL Controller](/consul/docs/ecs/manual/acl-controller) and [Architecture](/consul/docs/ecs/architecture).
### ECS Task Role Configuration
The ECS [task role](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html)
is an IAM role associated with an ECS task.
When an ECS task starts up, it runs a `consul login` command. The `consul login` command obtains
credentials for the task role role from AWS. It uses those credentials to sign the login request to
the AWS IAM auth method. This proves the ECS task's identity to the Consul servers.
The task role must be configured with the following details to compatible with the AWS IAM auth
method.
* An `iam:GetRole` permission to fetch itself. See
[IAM Policies](/consul/docs/security/acl/auth-methods/aws-iam#iam-policies) for details.
* A `consul.hashicorp.com.service-name` tag on the task role which contains the Consul service name
for the application in this task.
* <EnterpriseAlert inline /> A <code>consul.hashicorp.com.namespace</code> tag on the task role
indicating the Consul Enterprise namespace where this service is registering.
The following sections describe how to configure the auth method to enable task roles to
successfully authenticate to the AWS IAM auth method and obtain tokens with the necessary
permissions.
### Auth Method for Client Tokens
The following steps configure an instance of the auth method that creates client tokens for tasks.
1. Create the auth method instance
2. Create the client policy and role
3. Create the binding rule
#### Create Auth Method for Client Tokens
The following Consul CLI command creates an instance of the auth method for client tokens.
```shell
consul acl auth-method create \
-type aws-iam \
-name iam-ecs-client-token \
-description="AWS IAM auth method for ECS client tokens" \
-config '{
"BoundIAMPrincipalArns": ["arn:aws:iam::<ACCOUNT>:role/consul-ecs/*"],
"EnableIAMEntityDetails": true
}'
```
The following flags are required:
| Flag | Type | Description |
| --------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `-type` | string | Must be `aws-iam`. |
| `-name` | string | A name of your choice. Must be unique among all auth methods. |
| `-description` | string | A description of your choice. |
| `-config` | string | A JSON string containing the [configuration](/consul/docs/security/acl/auth-methods/aws-iam#config-parameters) for the auth method. |
In the `-config` option, the following fields are required:
| Field | Type | Description |
| ------------------------- | ------- | --------------------------------------------------------------------------------------------------------- |
| `BoundIAMPrincipalArns` | list | The list of trusted IAM roles. We recommend using a wildcard to trust IAM roles at a particular path. |
| `EnableIAMEntityDetails` | boolean | Must be true so that the auth method can retrieve IAM role details, such as the role path and role tags. |
#### Create Client Policy and Role
Configure the following ACL policy for Consul client tokens:
<CodeBlockConfig filename="client-token-policy.hcl">
```hcl
node_prefix "" {
policy = "write"
}
service_prefix "" {
policy = "read"
}
```
</CodeBlockConfig>
The policy allows `node:write` for any node name, which is necessary because the Consul node names on ECS are not known until runtime.
You can add the policy in Consul using the [`consul acl policy create`](/consul/commands/acl/policy/create) command or the [`[PUT] /v1/acl/policy`](/consul/api-docs/acl/policies#create-a-policy) API endpoint.
After the policy is created, create a Consul role associated with the policy by using the [`consul acl role create`](/consul/commands/acl/role/create) command or the [`[PUT] /v1/acl/role`](/consul/api-docs/acl/roles#create-a-role) API endpoint.
The following example shows how to use the Consul CLI to create the client policy and role.
```shell
consul acl policy create -name consul-ecs-client-policy -rules @client-token-policy.hcl
consul acl role create -name consul-ecs-client-role -policy-name consul-ecs-client-policy
```
#### Create Binding Rule for Client Tokens
The following creates a binding rule for the auth method for client tokens. The binding rule
associates the client role with each token created by a successful login to this auth
method instance.
```shell
consul acl binding-rule create -method iam-ecs-client-token \
-description 'Bind a role for Consul clients on ECS' \
-bind-type role \
-bind-name consul-ecs-client-role
```
### Auth Method for Service Tokens
The following steps configure an instance of the auth method that creates service tokens for tasks.
* Create the auth method instance
* Create the binding rule
#### Create Auth Method for Service Tokens
The following uses the Consul CLI to create an instance of the auth method
for service tokens. This configures the auth method to associate a service identity
to each token created during login to this auth method instance.
```shell
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"
]
}'
```
The following flags are required:
| Flag | Type | Description |
| --------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `-type` | string | Must be `aws-iam`. |
| `-name` | string | A name of your choice. Must be unique among all auth methods. |
| `-description` | string | A description of your choice. |
| `-config` | string | A JSON string containing the [configuration](/consul/docs/security/acl/auth-methods/aws-iam#config-parameters) for the auth method. |
In the `-config` option, the following fields are required:
| Field | Type | Description |
| --- | --- | --- |
| `BoundIAMPrincipalArns` | list | The list of trusted IAM roles. We recommend using a wildcard to trust IAM roles at a particular path. |
| `EnableIAMEntityDetails` | boolean | Must be true so that the auth method can retrieve IAM role details, such as the role path and role tags. |
| `IAMEntityTags` | list | The list of IAM role tags to make available to binding rules. Must include the service name tag as shown. |
The following binding rule is used to associate a service identity with each token created by
successful login to this instance of the auth method. The service identity name is taken from the
`consul.hashicorp.com.service-name` tag from the authenticating IAM role identity.
#### Create Binding Rule
```shell
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}'
```
### Configuration for Consul Enterprise<EnterpriseAlert inline />
When using Consul Enterprise namespaces and admin partitions, pass 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.
The following shows how to create the ACL policy for client tokens. This ensures permissions for the
client token are scoped to a particular partition.
<CodeBlockConfig filename="client-token-policy-ent.hcl">
```hcl
partition "<partition-name>" {
node_prefix "" {
policy = "write"
}
namespace_prefix "" {
service_prefix "" {
policy = "read"
}
}
}
```
</CodeBlockConfig>
The following commands show how to use the Consul CLI to create the policy and role.
```shell
consul acl policy create -partition <partition-name> \
-name consul-ecs-client-policy \
-rules @client-token-policy-ent.hcl
consul acl role create \
-partition <partition-name> \
-name consul-ecs-client-role \
-policy-name consul-ecs-client-policy
```
The auth method for *service tokens* requires the following additional configuration to include a
namespace binding rule. This ensures the service tokens are created in the right namespace during
login. (The namespace binding rule must not be configured on the instance of the auth method
instance for *client tokens*.)
<CodeBlockConfig highlight="2-2,6-7,13-13">
```shell
consul acl auth-method create \
-partition <partition-name> \
-type aws-iam \
-name iam-ecs-service-token \
-description="AWS IAM auth method for ECS service tokens" \
-namespace-rule-selector 'entity_tags["consul.hashicorp.com.namespace"] != ""' \
-namespace-rule-bind-namespace '${entity_tags.consul.hashicorp.com.namespace}' \
-config '{
"BoundIAMPrincipalArns": ["arn:aws:iam::<ACCOUNT>:role/consul-ecs/*"],
"EnableIAMEntityDetails": true,
"IAMEntityTags": [
"consul.hashicorp.com.service-name",
"consul.hashicorp.com.namespace"
]
}'
```
</CodeBlockConfig>
| Field | Type | Description |
| -------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-partition` | string | The Consul Enterprise admin partition in which the auth method is created. |
| `-namespace-rule-selector` | string | When this expression evaluates to true during login, the `-namespace-rule-bind-namespace` is applied. As shown, it evaluates to true when the `consul.hashicorp.com.namespace` tag is non-empty on the task IAM role. |
| `-namespace-rule-bind-namespace` | string | This expression is evaluated to determine the namespace where the token is created during login. As shown, it uses the namespace from the `consul.hashicorp.com.namespace` tag on the task IAM role. |
| `IAMEntityTags` | list | Must include `consul.hashicorp.com.namespace` to enable use of this tag in binding rules. |
## Secret storage
You should securely store the following secrets in order to make them available to ECS tasks.
1. Consul Server CA certificates. More than one may be required for different Consul protocols.
2. Consul gossip encryption key
These secrets can be securely stored and passed to ECS tasks using either of the following AWS secret services:
* [AWS Systems Manager Parameter Store](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/specifying-sensitive-data-parameters.html)
* [AWS Secrets Manager](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/specifying-sensitive-data-secrets.html)
Once the secrets are stored they can be referenced using their ARN. The following shows
example secret ARNs when using AWS Secrets Manager:
| Secret | Sample Secret ARN |
| ---------------------- | ---------------------------------------------------------------------------------- |
| 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` |
| Gossip encryption key | `arn:aws:secretsmanager:us-west-2:000000000000:secret:my-consul-gossip-key` |
## Configure `consul-client`
The following secrets must be passed to the `consul-client` container:
* Consul server CA certificates
* Gossip encryption key
The following example shows how to include these secrets in the task definition. The `secrets`
list specifies environment variable `name`s that will be set to the secret values for this container.
ECS automatically fetches the secret values specified in the `valueFrom` fields during task provisioning.
```json
{
"containerDefinitions": [
{
"name": "consul-client"
"image": "public.ecr.aws/hashicorp/consul:<CONSUL_VERSION>",
"secrets": [
{
"name": "CONSUL_CACERT_PEM",
"valueFrom": "arn:aws:secretsmanager:us-west-2:000000000000:secret:my-consul-ca-cert"
},
{
"name": "CONSUL_HTTPS_CACERT_PEM",
"valueFrom": "arn:aws:secretsmanager:us-west-2:000000000000:secret:my-consul-https-ca-cert"
},
{
"name": "CONSUL_GOSSIP_ENCRYPTION_KEY",
"valueFrom": "arn:aws:secretsmanager:us-west-2:000000000000:secret:my-consul-gossip-key"
}
]
},
...
]
}
```
Next, update the Consul client startup script with the `consul login` command and additional Consul configuration
options for a secure configuration.
The following is an example of the *additional* content to include in the `consul-client` startup script. Refer to the [install
page](/consul/docs/ecs/manual/install#consul-client-container) for the remainder of the startup script and how to pass this
script to the container.
<CodeBlockConfig highlight="3-60,66-91">
```shell
...
# Obtain details from the task metadata
ECS_TASK_META=$(curl -s $ECS_CONTAINER_METADATA_URI_V4/task)
TASK_REGION=$(echo "$ECS_TASK_META" | jq --raw-output '.TaskARN / ":" | .[3]')
TASK_ID=$(echo "$ECS_TASK_META" | jq --raw-output '.TaskARN / "/" | .[2]')
CLUSTER_ARN=$(echo "$ECS_TASK_META" | jq --raw-output '.TaskARN | sub(":task/(?<cluster>[^/]+).*"; ":cluster/\(.cluster)")')
# Write the CA certs to a files in the shared volume
echo "$CONSUL_CACERT_PEM" > /consul/consul-ca-cert.pem
echo "$CONSUL_HTTPS_CACERT_PEM" > /consul/consul-https-ca-cert.pem
consul_login() {
echo "Logging into auth method"
consul login \
-http-addr "<consul server address>" \
-ca-file /consul/consul-https-ca-cert.pem \
-partition "<partition>" \
-type aws-iam \
-method iam-ecs-client-token \
-meta "consul.hashicorp.com/task-id=$TASK_ID" \
-meta "consul.hashicorp.com/cluster=$CLUSTER_ARN" \
-aws-region "$TASK_REGION" \
-aws-auto-bearer-token -aws-include-entity \
-token-sink-file /consul/client-token
}
read_token_stale() {
consul acl token read -http-addr ${ consul_http_addr } \
-ca-file /consul/consul-https-ca-cert.pem \
-stale -self -token-file /consul/client-token \
> /dev/null
}
# Retry in order to login successfully.
while ! consul_login; do
sleep 2
done
# Allow the health-sync container to read this token for consul logout.
chmod 0644 /consul/client-token
# Wait for raft replication to hopefully occur. Without this, an "ACL not found" may be cached for a while.
COUNT=20
while [ "$COUNT" -gt 0 ]; do
echo "Checking that the ACL token exists when reading it in the stale consistency mode ($COUNT attempts remaining)"
if read_token_stale; then
echo "Successfully read ACL token from the server"
break
fi
sleep 0.1
COUNT=$((COUNT - 1))
done
if [ "$COUNT" -eq 0 ]; then
echo "Unable to read ACL token from a Consul server; please check that your server cluster is healthy"
exit 1
fi
# This is interpolated into the agent-defaults.hcl
export AGENT_TOKEN=$(cat /consul/client-token)
# Write the Consul agent configuration file.
cat << EOF > /consul/agent-defaults.hcl
...
# Configure gossip encryption key
encrypt = "$CONSUL_GOSSIP_ENCRYPTION_KEY"
# Configure TLS settings
auto_encrypt = {
tls = true
ip_san = ["$ECS_IPV4"]
}
tls {
defaults {
ca_file = "/consul/consul-ca-cert.pem"
verify_outgoing = true
}
}
# Configure ACLs
acl {
enabled = true
default_policy = "deny"
down_policy = "async-cache"
tokens {
agent = "$AGENT_TOKEN"
}
}
partition = "<partition>"
EOF
```
</CodeBlockConfig>
The following describes the additional steps added to the startup script:
* Fetch additional details from the task metadata: the AWS region, task id, and cluster arn.
These details are necessary for the `consul login` command used to obtain a Consul client token.
* Write CA certificates to files for Consul CLI and Consul client
* Run the `consul login` command in a retry loop.
* Wait for Raft replication to hopefully occur for this token.
* Configure the Consul client config file with additional fields necessary for secure configuration.
The following flags are passed to the `consul login` command:
| Field name | Type | Description |
| ------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------ |
| [`-http-addr`](/consul/commands/login#http-addr) | string | HTTP(S) address of the Consul server. |
| [`-ca-file`](/consul/commands/login#ca-file) | string | Path of the CA cert for Consul's HTTPS interface. Not required when using Consul servers on HCP. |
| `-partition` | string | <EnterpriseAlert inline /> The Consul Enterprise admin partition the auth method belongs to. |
| [`-type`](/consul/commands/login#type) | string | The auth method type. Must be `aws-iam`. |
| [`-method`](/consul/commands/login#type) | string | The auth method name. Must be the name of the auth method for ECS client tokens. |
| [`-meta`](/consul/commands/login#meta) | string | Metadata to set in description of the created token. Should include the task id and cluster as shown. |
| `-aws-region` | string | The AWS region where the task is running. |
| `-aws-auto-bearer-token` | | Must be set to login to the AWS IAM auth method. |
| `-aws-include-entity` | | Must be set to enable IAM role details. |
The following table describes the additional fields that must be included in the Consul client configuration file.
| Field name | Type | Description |
| ------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------ |
| [`encrypt`](/consul/docs/agent/config/cli-flags#_encrypt) | string | Gossip encryption key |
| [`tls.defaults.ca_file`](/consul/docs/agent/config/config-files#tls_defaults_ca_file) | string | Consul server CA cert for TLS verification. |
| [`acl.enabled`](/consul/docs/agent/config/config-files#acl_enabled) | boolean | Enable ACLs for this agent. |
| [`acl.tokens.agent`](/consul/docs/agent/config/config-files#acl_tokens_agent) | string | Consul client token which authorizes this agent with Consul servers. |
| [`partition`](/consul/docs/agent/config/config-files#partition-1) | string | <EnterpriseAlert inline /> The Consul Enterprise admin partition this agent belongs to. |
### Configure Audit Logging <EnterpriseAlert inline />
[Audit logging](/consul/docs/enterprise/audit-logging) is supported on clients running Consul Enterprise with ACLs enabled.
To enable audit logging, update the startup script to add an `audit` stanza to the Consul client configuration file.
The following example modifies the `consul-client` startup script to configure audit logs to be written to the `stdout` of the `consul-client` container.
<CodeBlockConfig highlight="9-17">
```shell
...
# Write the Consul agent configuration file.
cat << EOF > /consul/agent-defaults.hcl
...
partition = "<partition>"
audit {
enabled = true
sink "stdout" {
type = "file"
format = "json"
path = "/dev/stdout"
delivery_guarantee = "best-effort"
}
}
EOF
```
</CodeBlockConfig>
The following table describes the fields that must be included to configure audit logging.
| Field name | Type | Description |
| ------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------ |
| [`audit.enabled`](/consul/docs/agent/config/config-files#enabled) | boolean | Enable audit logging for this agent. |
| [`audit.sink`](/consul/docs/agent/config/config-files#sink) | object | The audit logging sink for this agent. |
## Configure `consul-ecs-mesh-init` and `consul-ecs-health-sync`
The following *additional* options should be set in the [`CONSUL_ECS_CONFIG_JSON`](/consul/docs/ecs/manual/install#consul_ecs_config_json) environment variable. When these options are specified, the `consul-ecs mesh-init` command will run the `consul login` command to obtain a service token from the Consul AWS IAM Auth method. The `consul-ecs health-sync` command is responsible for running a `consul logout` command for both the service and client tokens when the task shuts down.
<CodeBlockConfig highlight="2-8">
```json
{
"consulHTTPAddr": "<Consul server address>",
"consulCACertFile": "/consul/consul-https-ca-cert.pem",
"consulLogin": {
"enabled": true,
"method": "iam-ecs-service-token",
"extraLoginFlags": ["-partition", "<partition>"]
},
"bootstrapDir": "/consul",
"healthSyncContainers": [],
...
}
```
</CodeBlockConfig>
The following table explains the additional fields for the `CONSUL_ECS_CONFIG_JSON`:
| Field name | Type | Description |
| ----------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `consulHTTPAddr` | string | HTTP(S) address for the Consul server. |
| `consulCACertFile` | string | Path of the CA cert file for Consul's HTTPS interface. Not required for Consul servers in HCP. |
| `consulLogin.enabled` | boolean | Must be set to true to log in to the auth method. |
| `consulLogin.method` | string | Must be set to the name of the auth method instance for service tokens. |
| `consulLogin.extraLoginFlags` | list | Additional flags passed to the `consul login` command. <EnterpriseAlert inline /> This shows how to pass the Consul Enterprise admin partition to the `consul login` command. |

0
website/content/docs/ecs/compatibility.mdx → website/content/docs/ecs/reference/compatibility.mdx
View File

2
website/content/docs/ecs/configuration-reference.mdx → website/content/docs/ecs/reference/configuration-reference.mdx
View File

@ -7,7 +7,7 @@ description: >-
# Consul on AWS Elastic Container Service (ECS) Configuration Reference
This pages details the configuration options for the JSON config format used
This topic describes configuration options for the JSON configuration format used
by the `consul-ecs` binary. This configuration is passed to the `consul-ecs`
binary as a string using the `CONSUL_ECS_CONFIG_JSON` environment variable.

31
website/content/docs/ecs/reference/consul-server-json.mdx Normal file
View File

@ -0,0 +1,31 @@
---
layout: docs
page_title: Consul server configuration JSON schema reference
description: Learn about the fields available in the JSON scheme for configuring ECS task connections to Consul servers.
---
# Consul server configuration JSON schema reference
This topic provides reference information about the JSON schema used to build the `config.tf` file. Refer to [Configure Consul server settings](/consul/docs/ecs/deploy/terraform#configure-consul-server-settings) for information about how Consul on ECS uses the JSON schema.
```json
`consulServers`
`hosts`: string
`skipServerWatch`: boolean; set to true if the Consul server is already behind a load balancer
`defaults`: map - applies to both gRPC and HTTP
`caCertFile`: string path to the certificate .pem file
`tlsServerName`: string name of the TLS server
`tls`: boolean that enables TLS
`grpc`: map - overrides for gRPC traffic
`port`: number specifying the port for gRPC communication
`caCertFile`: string path to the certificate .pem file for authorizing gRPC
`tlsServerName`: string name of the TLS server
`tls`: boolean that enables TLS for gRPC
`http`: map - overrides for HTTP traffic
`https`: boolean that enables HTTPS
`port`: number specifying the port for HTTPS communication
`caCertFile`: string path to the certificate .pem file for authorizing HTTPS
`tlsServerName`: string name of the TLS server
`tls`: boolean that enables TLS for HTTPS
```

32
website/content/docs/ecs/requirements.mdx
View File

@ -1,32 +0,0 @@
---
layout: docs
page_title: Requirements - Consul on AWS Elastic Container Service (ECS)
description: >-
Consul has requirements to install and run on Amazon Web Services ECS. Learn about Consul's requirements for Fargate and EC2, including network mode and subnet information, as well as server, routing, and ACL controller considerations to keep in mind.
---
# Requirements for Consul on AWS Elastic Container Service (ECS)
The following requirements must be met in order to install Consul on ECS:
* **Launch Type:** Fargate and EC2 launch types are supported.
* **Network Mode:** Only `awsvpc` mode is supported.
* **Subnets:** ECS Tasks can run in private or public subnets. Tasks must have [network access](https://aws.amazon.com/premiumsupport/knowledge-center/ecs-pull-container-api-error-ecr/) to Amazon ECR or other public container registries to pull images.
* **Consul Servers:** You can use your own Consul servers running on virtual machines or use [HashiCorp Cloud Platform Consul](https://www.hashicorp.com/cloud-platform) to host the servers for you. For development purposes or testing, you may use the `dev-server` [Terraform module](https://github.com/hashicorp/terraform-aws-consul-ecs/tree/main) that runs the Consul server as an ECS task. The `dev-server` does not support persistent storage.
* **ACL Controller:** If you are running a secure Consul installation with ACLs enabled, configure the ACL controller.
* **Admin Partitions:** <EnterpriseAlert inline />Consul on ECS supports [admin partitions](/consul/docs/enterprise/admin-partitions) when ACLs are enabled and the ACL controller is configured.
The ACL controller manages one admin partition and each ECS cluster requires an ACL controller.
Each `mesh-task` must also be configured to use a Consul Enterprise client.
* **Namespaces:** <EnterpriseAlert inline />[Namespaces](/consul/docs/enterprise/namespaces) are supported when ACLs are enabled and the ACL controller is configured.
Each `mesh-task` must also be configured to use a Consul Enterprise client.
* **Sidecar containers:** Consul on ECS requires two sidecar containers to run in each ECS task: a
Consul agent container and a sidecar proxy container. These additional sidecar containers must
be included in the ECS task definition. The [Consul ECS Terraform module](/consul/docs/ecs/terraform/install)
will include these sidecar containers for you. If you do not use Terraform, you can construct
the task definition yourself by following [our documentation](/consul/docs/ecs/manual/install).
* **Routing:** With your application running in tasks as part of the mesh, you must specify the
upstream services that your application calls. You will also need to change the URLs your
application uses to ensure the application is making requests through the service mesh.
* **Bind Address:** Once all communication is flowing through the service mesh, you should change
the address your application is listening on to `127.0.0.1` so that it only receives requests
through the sidecar proxy.

37
website/content/docs/ecs/task-resource-usage.mdx
View File

@ -1,37 +0,0 @@
---
layout: docs
page_title: Resource Usage - Consul on AWS Elastic Container Service (ECS)
description: >-
Learn about the CPU and memory resources Consul uses while running on Amazon Web Services ECS, including performance test procedures and results.
---
# Resource Usage for Consul on AWS Elastic Container Service (ECS)
We ran performance tests of Consul on ECS to determine the resource usage of
the sidecar containers Consul on ECS injects along with the ACL controller.
[The architecture page](/consul/docs/ecs/architecture) describes each Consul on ECS
component in depth.
We used the following procedure to measure resource usage:
- Executed performance tests while deploying clusters of various sizes. We
ensured that deployment conditions stressed Consul on ESC components.
- After each performance test session, we recorded resource usage for each
component to determine worst-case scenario resource usage in a production
environment.
- We used Fargate's minimum allowed CPU (256 shares) and memory settings (512
MB) on ECS during performance testing to demonstrate that Consul on ECS along
with application containers can run on the smallest ECS tasks.
Here is the maximum resource usage we observed for each container:
| Container | CPU | Memory |
| -------------- | --- | ------ |
| ACL Controller | 5% | 43 MB |
| Health Sync | 6% | 35 MB |
| Consul Client | 10% | 87 MB |
| Envoy | 18% | 55 MB |
The containers added by Consul on ECS consume resources well below the minimum CPU and
memory limits for an ECS Task. Use the `memory` and `cpu` settings for the task definition
if additional resources are necessary for your application task.

52
website/content/docs/ecs/tech-specs.mdx Normal file
View File

@ -0,0 +1,52 @@
---
layout: docs
page_title: Technical specifications for Consul on AWS Elastic Container Service (ECS)
description: >-
Consul has requirements to install and run on Amazon Web Services ECS. Learn about Consul's requirements for Fargate and EC2, including network mode and subnet information, as well as server, routing, and ACL controller considerations.
---
# Technical specifications for Consul on ECS
This topic describes the supported runtimes and environments for using Consul service mesh for your ECS workloads.
For requirements associated with using the Terraform `mesh-task` module to deploy Consul service mesh, refer [Deploy Consul with the Terraform module](/consul/docs/ecs/deploy/terraform). For requirements associated with manually deploying Consul service mesh to your ECS cluster, refer [Deploy Consul manually](/consul/docs/ecs/deploy/manual).
## Supported environments and runtimes
Consul on ECS supports the following environments and runtimes:
- **Launch Types**: Fargate and EC2
- **Network Modes**: `awsvpc`
- **Subnets**: Private and public subnets. Tasks must have network access to Amazon ECR or other public container registries to pull images.
- **Consul servers**: You can use your own Consul servers running on virtual machines or [use HCP Consul to host the servers for you](/hcp/docs/consul/hcp-managed).
- **ECS controller**: The ECS controller assists with reconciling state back to Consul and facilitates Consul security features.
- **Admin partitions**: <EnterpriseAlert inline/> Enable ACLs and configure the ECS controller to use admin partitions. You must deploy one controller for each admin partition.
- **Namespaces**: <EnterpriseAlert inline/> Enable ACLs and configure the ECS controller to use namespaces.
- **Dataplane containers**: To manage proxies using Consul dataplane, you must use the Terraform `mesh-task` module to install Consul service mesh.
## Resource usage
We used the following procedure to measure resource usage:
- Executed performance tests while deploying clusters of various sizes. We
ensured that deployment conditions stressed Consul on ESC components.
- After each performance test session, we recorded resource usage for each
component to determine worst-case scenario resource usage in a production
environment.
- We used Fargate's minimum allowed CPU (256 shares) and memory settings (512
MB) on ECS during performance testing to demonstrate that Consul on ECS along
with application containers can run on the smallest ECS tasks.
The following table describes the maximum resource usage we observed for each container under these testing conditions:
| Container | CPU | Memory |
| -------------- | --- | ------ |
| ECS controller | 5% | 43 MB |
| Control plane | 6% | 35 MB |
| Dataplane | 10% | 87 MB |
The containers added by Consul on ECS consume resources well below the minimum CPU and
memory limits for an ECS task. Use the `memory` and `cpu` settings for the task definition
if additional resources are necessary for your application task.
Refer to [Architecture](/consul/docs/ecs/architecture) for details about each component.

452
website/content/docs/ecs/terraform/install.mdx
View File

@ -1,452 +0,0 @@
---
layout: docs
page_title: Install with Terraform - Consul on AWS Elastic Container Service (ECS)
description: >-
When you install Consul on Amazon Web Services ECS, you can use Terraform modules to simplify the process. Learn how to create task definitions, schedule tasks for your service mesh, and configure routes with example configurations.
---
# Install Consul on AWS Elastic Container Service (ECS) with Terraform
This topic describes how to use HashiCorp's Terraform modules to launch your application in AWS ECS as part of Consul service mesh. If you do not use Terraform, refer to the [Manual Installation](/consul/docs/ecs/manual/install) page to install Consul on ECS without Terraform.
This topic does not include instructions for creating all AWS resources necessary to install Consul, such as a VPC or the ECS cluster. Refer to the guides in the [Getting Started](/consul/docs/ecs#getting-started) section for complete and runnable examples.
## Overview
The following procedure describes the general workflow:
1. Create Terraform configuration files for the necessary components:
- [ECS task definition](#create-the-task-definition): Use the HashiCorp Terraform modules to create the ECS task definition.
- [ECS service](#ecs-service): Use the `aws_ecs_service` resource to create an ECS service that schedules service mesh tasks to run on ECS.
2. [Run Terraform](#running-terraform) to deploy the resources in AWS
If you want to operate Consul in production environments, follow the instructions in the [Secure Configuration](/consul/docs/ecs/terraform/secure-configuration) documentation. The instructions describe how to enable ACLs and TLS and gossip encryption, which provide network security for production-grade deployments.
## Requirements
* You should have some familiarity with using Terraform. Refer to the [Terraform documentation](/terraform/docs) to learn about infrastructure as code and how to get started with Terraform.
* You should also be familiar with AWS ECS before following these instructions. See [What is Amazon Elastic Container Service](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/Welcome.html) for details.
* If you intend to [use the `gateway-task` module to deploy mesh gateways](#configure-the-gateway-task-module), all Consul server and client agents in all datacenters must have TLS and gossip encryption enabled. Refer to the [Secure Configuration](/consul/docs/ecs/terraform/secure-configuration) documentation for instructions.
## Create the task definition
To run an application in ECS with Consul service mesh, you must create an ECS task definition. The task definition includes your application containers and additional sidecar containers, such as the Consul agent container and the Envoy sidecar proxy container.
Create a Terraform configuration file and include the `mesh-task` module. The module automatically adds the necessary sidecar containers.
If you intend to peer the service mesh to multiple Consul datacenters or partitions, you can also include the `gateway-task` module. The module enables connectivity between datacenters across service meshes.
### Configure the mesh task module
Create a Terraform configuration file and specify the `mesh-task` module in the `source` field. The [`mesh-task` module](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task) automatically includes the necessary sidecar containers.
In the following example, the Terraform configuration file called `mesh-task.tf` creates a task definition with an application container called `example-client-app`:
<CodeBlockConfig filename="mesh-task.tf">
```hcl
module "my_task" {
source = "hashicorp/consul-ecs/aws//modules/mesh-task"
version = "<latest version>"
family = "my_task"
container_definitions = [
{
name = "example-client-app"
image = "docker.io/org/my_task:v0.0.1"
essential = true
portMappings = [
{
containerPort = 9090
hostPort = 9090
protocol = "tcp"
}
]
cpu = 0
mountPoints = []
volumesFrom = []
}
]
port = 9090
retry_join = ["<address of the Consul server>"]
consul_datacenter = "<name of your Consul datacenter>"
}
```
</CodeBlockConfig>
The following fields are required. Refer to the [module reference documentation](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task?tab=inputs) for a complete reference.
| Input Variable | Type | Description |
| ----------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `source` | string | Must be set to the source location of the `mesh-task` module, `hashicorp/consul-ecs/aws//modules/mesh-task`. |
| `version` | string | Must be set to the version of the `mesh-task` module. |
| `family` | string | The [ECS task definition family](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#family). The family is also used as the Consul service name by default. |
| `container_definitions` | list | This is the list of [container definitions](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#container_definitions) for the task definition. This is where you include your application containers. |
| `essential` | boolean | Must be `true` to ensure the health of your application container affects the health status of the task. |
| `port` | integer | The port that your application listens on, if any. If your application does not listen on a port, set `outbound_only = true`. |
| `retry_join` | list | This is the [`retry_join`](/consul/docs/agent/config/config-files#retry_join) option for the Consul agent, which specifies the locations of your Consul servers. |
### Configure an ECS service for the mesh task module
[ECS services](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs_services.html) are one of the most common
ways to start tasks using a task definition.
To define an ECS service, reference the `mesh-task` module's `task_definition_arn` output value
in your `aws_ecs_service` resource. The following example shows how to include the service in the `mesh-task.tf` file.
<CodeBlockConfig filename="mesh-task.tf" highlight="6-12">
```hcl
module "my_task" {
source = "hashicorp/consul-ecs/aws//modules/mesh-task"
...
}
resource "aws_ecs_service" "my_task" {
name = "my_task_service"
task_definition = module.my_task.task_definition_arn
launch_type = "FARGATE"
propagate_tags = "TASK_DEFINITION"
...
}
```
</CodeBlockConfig>
The example shows a partially configured ECS service to highlight significant fields. Refer to [`aws_ecs_service`](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ecs_service) for a complete configuration reference.
| Input Variable | Type | Description |
| ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------- |
| `name` | string | The name of the ECS service. This name is required by AWS but is not used by Consul service mesh. |
| `task_definition` | string | The task definition used to start tasks. Set this option to the task definition ARN returned by the `mesh-task` module. |
| `launch_type` | string | The launch type. Consul on ECS supports the `FARGATE` and `EC2` launch types. |
| `propagate_tags` | string | This option must be set to `TASK_DEFINITION` so that tags added by `mesh-task` to the task definition are copied to tasks. |
After including the ECS service in your Terraform configuration, run `terraform apply`
from your project directory to create the ECS service resource. The ECS service
then starts your application in a task. The task automatically registers itself
into the Consul service catalog during startup.
-> **NOTE:** If your tasks run in a public subnet, they must have `assign_public_ip = true`
in their [`network_configuration`](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ecs_service#network_configuration) block so that ECS can pull the Docker images.
### Configure the gateway task module
Add the `gateway-task` to your Terraform configuration if you want to deploy a mesh gateway. Mesh gateways enable service to service communication across the WAN, as well as federate service mesh traffic across Consul admin partitions and Consul datacenters over the WAN. Refer to the following documentation to learn more about mesh gateways:
* [WAN Federation via Mesh Gateways](/consul/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways)
* [Service-to-service Traffic Across Datacenters](/consul/docs/connect/gateways/mesh-gateway/service-to-service-traffic-wan-datacenters).
You must add and configure a `gateway-task` for each Consul datacenter in your network. You must also enable TLS and gossip encryption on all server and client agents in all data centers per the [Requirements](#requirements). Mesh gateways operate by sniffing and extracting the server name indication (SNI) header from the service mesh session and routing the connection to the appropriate destination based on the server name requested.
The module creates an ECS service and a task definition that includes the following containers:
- Consul client
- Envoy gateway proxy
- Mesh init
You will need to provide inputs for the artifacts created by the `gateway-task` module. The following example defines a mesh gateway task called `my-gateway` in a file called `mesh-gateway.tf`:
<CodeBlockConfig filename="mesh-gateway.tf">
```hcl
module "my_mesh_gateway" {
source = "hashicorp/consul-ecs/aws//modules/gateway-task"
version = "<latest version>"
kind = "mesh-gateway"
family = "my-gateway"
ecs_cluster_arn = "<ECS cluster ARN>"
subnets = ["<subnet ID>"]
retry_join = ["<address of the Consul server>"]
tls = true
consul_server_ca_cert_arn = "<Secrets Manager secret ARN>"
gossip_key_secret_arn = "<Secrets Manager secret ARN>"
}
```
</CodeBlockConfig>
The following fields are required. Refer to the [module reference documentation](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/gateway-task?tab=inputs) for a complete reference.
| Input variable | Type | Description |
| --- | --- | --- |
| `source` | string | Specifies the source location of the `gateway-task` module. Must be set to `hashicorp/consul-ecs/aws//modules/gateway-task`. |
| `version` | string | Specifies the version of the `gateway-task` module. |
| `kind` | string | Declares the kind of gateway to create. Must be set to `mesh-gateway` to create a mesh-gateway. |
| `family` | string | Specifies the [ECS task definition family](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#family). The family is also used as the Consul service name by default. |
| `ecs_cluster_arn` | string | Specifies the ARN of the ECS cluster where the mesh gateway task should be launched. |
| `subnets` | list of strings | Specifies the subnet IDs where the task will be launched. |
| `retry_join` | list of strings | Defines a set of arguments to pass to the Consul agent [`-retry-join`](/consul/docs/agent/config/cli-flags#_retry_join) flag. The arguments specify locations of the Consul servers in the local datacenter that Consul client agents can connect to. |
| `tls` | boolean | Set to `true` to enable TLS. |
| `consul_server_ca_cert_arn` | string | Specifies the ARN of the Secrets Manager containing the Consul server CA certificate |
| `gossip_key_secret_arn` | string | Specifies the ARN of the Secrets Manager containing the Consul's gossip encryption key. |
Refer to the [gateway task configuration examples](#gateway-task-configuration-examples) for additional example configurations.
#### ECS service
The ECS service is automatically created by the `gateway-task` module. The service can run one or more instances of the gateway.
#### Mesh init
The `mesh-init` container is a short-lived container that sets up the initial configurations for Consul and Envoy. The `gateway-task` module automatically configures the `mesh-init` container based on the inputs specified in the [task definition](#task-definition) and [ECS service](#ecs-service) configuration.
For additional information, refer to [Task Startup](/consul/docs/ecs/architecture#task-startup) for additional information.
#### Gateway task configuration examples
The following examples illustrate how to configure the `gateway-task` for different use cases.
##### Ingress
Mesh gateways need to be reachable over the WAN to route traffic between datacenters. Configure the following options in the `gateway-task` to enable ingress through the mesh gateway.
| Input variable | Type | Description |
| --- | --- | --- |
| `lb_enabled` | Boolean | Set to `true` to automatically deploy and configure a network load balancer for ingress to the mesh gateway. |
| `lb_vpc_id` | string | Specifies the VPC to launch the load balancer in. |
| `lb_subnets` | list of strings | Specifies one or more public subnets to associate with the load balancer. |
<CodeBlockConfig filename="mesh-gateway.tf">
```hcl
module "my_mesh_gateway" {
...
lb_enabled = true
lb_vpc_id = "<VPC ID>"
lb_subnets = ["<public subnet IDs>"]
}
```
</CodeBlockConfig>
Alternatively, you can manually configure ingress to the mesh gateway and provide the `wan_address` and `wan_port` inputs to the `gateway-task` module. The `wan_port` field is optional. Port `8443` is used by default.
<CodeBlockConfig filename="mesh-gateway.tf">
```hcl
module "my_mesh_gateway" {
...
wan_address = "<public WAN address>"
wan_port = <public WAN port>
}
```
</CodeBlockConfig>
Mesh gateways route L4 TCP connections and do not terminate mTLS sessions. If you manually configure [AWS Elastic Load Balancing](https://aws.amazon.com/elasticloadbalancing/) for ingress to a mesh gateway, you must use an AWS [Network Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/introduction.html) or a [Classic Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/classic/introduction.html).
##### ACLs
Configure the following options in the `gateway-task` when ACLs are enabled.
| Option | Type | Description |
| --- | --- | --- |
| `acl` | Boolean | Set to `true` if ACLs are enabled. |
| `consul_http_addr` | string | Specifies the HTTP `address:port` of the Consul server. Required for the mesh gateway task to log into Consul via the IAM Auth Method to obtain its client and service tokens. |
| `consul_https_ca_cert_arn` | string | Specifies ARN of the Secrets Manager secret that contains the certificate for the Consul HTTPS API. |
<CodeBlockConfig filename="mesh-gateway.tf">
```hcl
module "my_mesh_gateway" {
...
acls = true
consul_http_addr = "<HTTP address of the Consul server>"
consul_https_ca_cert_arn = "<Secrets Manager secret ARN>"
}
```
</CodeBlockConfig>
##### WAN federation
Configure the following options in the `gateway-task` to enable [WAN federation via mesh gateways](/consul/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways).
| Option | Type | Description |
| --- | --- | --- |
| `consul_datacenter` | string | Specifies the name of the local Consul datacenter. |
| `consul_primary_datacenter` | string | Specifies the name of the primary Consul datacenter. |
| `enable_mesh_gateway_wan_federation` | Boolean | Set to `true` to enable WAN federation. |
| `enable_acl_token_replication` | Boolean | Set to `true` to enable ACL token replication and allow the creation of local tokens secondary datacenters. |
The following example shows how to configure the `gateway-task` module.
<CodeBlockConfig filename="mesh-gateway.tf">
```hcl
module "my_mesh_gateway" {
...
consul_datacenter = "<name of the local Consul datacenter>"
consul_primary_datacenter = "<name of the primary Consul datacenter>"
enable_mesh_gateway_wan_federation = true
enable_acl_token_replication = true
}
```
</CodeBlockConfig>
When federating Consul datacenters over the WAN with ACLs enabled, [ACL Token replication](/consul/docs/security/acl/acl-federated-datacenters) must be enabled on all server and client agents in all datacenters.
## Run Terraform
You will need to run Terraform to create the task definition.
Save the Terraform configuration for the task definition to a file, such as `mesh-task.tf`.
You should place this file in a directory alongside other Terraform configuration files for your project.
The `mesh-task` module requires the AWS Terraform provider. The following example shows how to include
and configure the AWS provider in a file called `provider.tf`. Refer to the [AWS Terraform provider](https://registry.terraform.io/providers/hashicorp/aws/latest/docs)
documentation for complete configuration details.
<CodeBlockConfig filename="provider.tf">
```hcl
terraform {
required_providers {
aws = {
source = "hashicorp/aws"
version = "<latest version>"
}
}
}
provider "aws" {
region = "<AWS region>"
...
}
```
</CodeBlockConfig>
Additional AWS resources for your project can be included in additional Terraform configuration files
in the same directory. The following example shows a basic project directory:
```shell-session
$ ls
mesh-task.tf
provider.tf
...
```
Terraform should be run in your project directory as follows.
* Run `terraform init` first to download dependencies, such as Terraform providers
* Run `terraform apply` to have Terraform create AWS resources, such as the task definition from the `mesh-task` module.
Terraform automatically reads all files in the current directory that have a `.tf` file extension.
Refer to the [Terraform documentation](/terraform/docs) for more information and Terraform best practices.
## Configure routes
Now that your tasks are registered in the mesh, you're able to use the service
mesh to route between them.
In order to make calls through the service mesh, you must configure the sidecar
proxy to listen on a different port for each upstream service your application
needs to call. You then must modify your application to make requests to the sidecar
proxy on that port.
For example, if your application `web` makes calls to another application called `backend`, then you would first configure the `mesh-task` module's upstream(s):
```hcl
module "web" {
family = "web"
upstreams = [
{
destinationName = "backend"
localBindPort = 8080
}
]
}
```
| Input Variable | Type | Description |
| ----------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `destinationName` | string | The name of the upstream service, as it is registered in the Consul service catalog. |
| `localBindPort` | integer | Requests to this port will be forwarded by the proxy to the upstream service. This must be an unused port, but does not need to match the upstream service port. |
If you have multiple upstream services they each need to be listed here.
Next, configure your application to make requests to `localhost:8080` when
it wants to call the `backend` service.
For example, if your service allows configuring the URL for `backend` via the
`BACKEND_URL` environment variable, you would set:
```hcl
module "web" {
family = "web"
upstreams = [
{
destinationName = "backend"
localBindPort = 8080
}
]
container_definitions = [
{
name = "web"
environment = [
{
name = "BACKEND_URL"
value = "http://localhost:8080"
}
]
...
}
]
...
}
```
## Configure the bind address
To ensure that your application only receives traffic through the service mesh,
you must change the address that your application listens on to the loopback address. The loopback address is also called `localhost`, `lo`, and `127.0.0.1`.
Binding to the loopback address allows the sidecar proxy running in the same task to only make requests within the service mesh.
If your application is listening on all interfaces, such as `0.0.0.0`, then other
applications can call it directly, bypassing its sidecar proxy.
Changing the listening address is specific to the language and framework you're
using in your application. Regardless of which language or framework you're using,
binding the loopback address to a dynamic value, such as an environment variable, is a best practice:
```bash
export BIND_ADDRESS="127.0.0.1:8080"
```
The following examples demonstrate how to bind the loopback address to an environment variable in golang and Django (Python):
<CodeTabs>
```go
s := &http.Server{
Addr: os.Getenv("BIND_ADDRESS"),
...
}
log.Fatal(s.ListenAndServe())
```
```bash
python manage.py runserver "$BIND_ADDRESS"
```
</CodeTabs>
## Next steps
- Follow the [Secure Configuration](/consul/docs/ecs/terraform/secure-configuration) to get production-ready.
- Now that your applications are running in the service mesh, read about
other [Service Mesh features](/consul/docs/connect).
- View the [Architecture](/consul/docs/ecs/architecture) documentation to understand
what's going on under the hood.

115
website/content/docs/ecs/terraform/migrate-existing-tasks.mdx
View File

@ -1,115 +0,0 @@
---
layout: docs
page_title: Migrate Tasks with Terraform - Consul on AWS Elastic Container Service (ECS)
description: >-
You can migrate tasks in existing Amazon Web Services ECS deployments to a service mesh deployed with Terraform. Learn how to convert a task specified as an ECS task definition into a `mesh-task` Terraform module.
---
# Migrate Tasks to Consul on AWS Elastic Container Service (ECS) with Terraform
This topic describes how to migrate your existing ECS Tasks to use our [`mesh-task` Terraform module](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task).
## Define Tasks in Terraform
Your tasks must first be specified in Terraform using the [`ecs_task_definition`](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ecs_task_definition)
resource so that they can then be converted to use the [`mesh-task` module](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task).
For example, your tasks should be defined with Terraform similar to the following:
```hcl
resource "aws_ecs_task_definition" "my_task" {
family = "my_task"
requires_compatibilities = ["FARGATE"]
network_mode = "awsvpc"
cpu = 256
memory = 512
execution_role_arn = "arn:aws:iam::111111111111:role/execution-role"
task_role_arn = "arn:aws:iam::111111111111:role/task-role"
container_definitions = jsonencode(
[{
name = "example-client-app"
image = "docker.io/org/my_task:v0.0.1"
essential = true
portMappings = [
{
containerPort = 9090
hostPort = 9090
protocol = "tcp"
}
]
cpu = 0
mountPoints = []
volumesFrom = []
}]
)
}
resource "aws_ecs_service" "my_task" {
name = "my_task"
cluster = "arn:aws:ecs:us-east-1:111111111111:cluster/my-cluster"
task_definition = aws_ecs_task_definition.my_task.arn
desired_count = 1
network_configuration {
subnets = ["subnet-abc123"]
}
launch_type = "FARGATE"
}
```
## Convert to the `mesh-task` Module
In order to add the necessary sidecar containers for your task to join the mesh,
you must use the [`mesh-task` module](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task).
The `mesh-task` module uses inputs similar to your old ECS task definition but
creates a new version of the task definition with additional containers.
The `mesh-task` module is used as follows:
```hcl
module "my_task" {
source = "hashicorp/consul-ecs/aws//modules/mesh-task"
version = "<latest version>"
family = "my_task"
container_definitions = [
{
name = "example-client-app"
image = "docker.io/org/my_task:v0.0.1"
essential = true
portMappings = [
{
containerPort = 9090
hostPort = 9090
protocol = "tcp"
}
]
cpu = 0
mountPoints = []
volumesFrom = []
}
]
port = 9090
retry_join = ["<address of the Consul server>"]
}
```
The main differences are:
- You should remove the `execution_role_arn` and `task_role_arn` fields. The `mesh-task` module creates the task and execution roles by default. If you need to use existing IAM role(s), set the `task_role` and `execution_role` fields to pass in existing roles.
- You must set the `port` field to the port that your application listens on.
If your application has no listening port, set `outbound_only = true` and remove the `port` field.
- You must add the `retry_join` field. This specifies the location of your Consul servers so that your task can join the mesh.
- You must remove the `jsonencode()` function from the `container_definitions` field.
The `mesh-task` module will create a new version of your task definition with the
necessary sidecar containers added so you can delete your existing `aws_ecs_task_definition`
resource.
## Next Steps
Now that your task(s) are migrated to the `mesh-task` module,
- Start at the [ECS Service section](/consul/docs/ecs/terraform/install#configure-an-ecs-service-for-the-mesh-task-module) of the Installation Guide to continue installing Consul on ECS.
- Refer to the [`mesh-task` reference documentation](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task?tab=inputs) for all available inputs to your mesh tasks.

177
website/content/docs/ecs/terraform/secure-configuration.mdx
View File

@ -1,177 +0,0 @@
---
layout: docs
page_title: Secure Configuration with Terraform - Consul on AWS Elastic Container Service (ECS)
description: >-
When running Consul on Amazon Web Services ECS, you can use Terraform to secure your service mesh with an auth method and ACL controller. Learn how to configure Terraform modules to enable secure deployment.
---
# Secure Configuration for Consul on AWS Elastic Container Service (ECS) with Terraform
This topic describes how to enable Consul security features for your production workloads.
## Overview
To enable security in your production workloads, you must deploy the [ACL controller](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/acl-controller), which provisions tokens for other service mesh tasks. Refer to [Architecture](/consul/docs/ecs/architecture#acl-controller) to learn more about the ACL controller.
The controller cannot provision tokens for itself, so you must create the token for the ACL controller. The following steps describe the overall process of enabling security features for your production workloads:
1. Enable the security features on your Consul server cluster per the [Prerequisites](#prerequisites).
1. Create the ACL token for the ACL controller in the datacenter.
1. Create a Secrets Manager secret containing the ACL controller's token.
1. Create a Secrets Manager secret containing the Consul CA certificate.
1. Deploy the ACL controller
1. Deploy the other services on the mesh.
## Prerequisites
Implement the following security features for your Consul server clusters before applying them to your workloads:
1. [TLS encryption](/consul/docs/security/encryption#rpc-encryption-with-tls) for RPC communication between Consul clients and servers.
1. [Gossip encryption](/consul/docs/security/encryption#gossip-encryption) for encrypting gossip traffic.
1. [Access control lists (ACLs)](/consul/docs/security/acl) for authentication and authorization for Consul clients and services on the mesh.
## Auth Method
Consul on ECS uses the [AWS IAM Auth Method](/consul/docs/ecs/architecture#aws-iam-auth-method) to enable
tasks to automatically obtain Consul ACL tokens during startup.
With the Terraform modules for Consul on ECS, the auth method is supported by default when ACLs are
enabled. The ACL controller sets up the auth method on the Consul servers. The `mesh-task` module
configures the ECS task definition to be compatible with the auth method.
A unique task IAM role is required for each ECS task family. Task IAM roles must not be shared by
different task families. This is because the task family represents only one Consul service and the
task IAM role must encode the Consul service name.
By default, the `mesh-task` module will create and configure the task IAM role for you.
~> **Note:** When passing an existing IAM role to the `mesh-task` module using the `task_role` input
variable, you must configure the IAM role as described in [ECS Task Role
Configuration](/consul/docs/ecs/manual/secure-configuration#ecs-task-role-configuration) to be compatible with
the AWS IAM auth method.
## ACL controller
1. Create a policy that grants `acl:write` and `operator:write` access for the controller. Refer to the [ACL policies documentation](/consul/docs/security/acl/acl-policies) for instructions.
1. Create a token and link it to the ACL controller policy. Refer to the [ACL tokens documentation](/consul/docs/security/acl/tokens) for instructions.
1. Create a Secrets Manager secret containing the ACL controller's token and a Secrets Manager secret containing the Consul CA cert.
```hcl
resource "aws_secretsmanager_secret" "bootstrap_token" {
name = "bootstrap-token"
}
resource "aws_secretsmanager_secret_version" "bootstrap_token" {
secret_id = aws_secretsmanager_secret.bootstrap_token.id
secret_string = "<bootstrap token>"
}
resource "aws_secretsmanager_secret" "ca_cert" {
name = "server-ca-cert"
}
resource "aws_secretsmanager_secret_version" "ca_cert" {
secret_id = aws_secretsmanager_secret.ca_cert.id
secret_string = "<CA certificate for the Consul server's HTTPS endpoint>"
}
```
1. Use the [`acl-controller` terraform module](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/acl-controller?tab=inputs) to deploy the controller. You must provide the ARN's for the token and CA cert in the `consul_bootstrap_token_secret_arn` and `consul_server_ca_cert_arn` fields, respectively.
```hcl
module "acl_controller" {
source = "hashicorp/consul-ecs/aws//modules/acl-controller"
version = "<version>"
consul_bootstrap_token_secret_arn = aws_secretsmanager_secret.bootstrap_token.arn
consul_server_http_addr = "https://consul-server.example.com:8501"
consul_server_ca_cert_arn = aws_secretsmanager_secret.ca_cert.arn
ecs_cluster_arn = "arn:aws:ecs:us-east-1:111111111111:cluster/consul-ecs"
region = "us-east-1"
subnets = ["subnet-abcdef123456789"]
name_prefix = "consul-ecs"
}
```
The following table describes the required input variables for the `acl-controller` module.
| Input Variable | Type | Description |
| ----------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `source` | string | The location of the `acl-controller` module source. |
| `version` | string | The version of the `acl-controller` module. |
| `consul_bootstrap_token_secret_arn` | string | The Secrets Manager secret containing an ACL token for the ACL controller. The ACL token must have `acl:write` and `operator:write` permissions. |
| `consul_server_http_addr` | string | The HTTP(S) address of the Consul servers. |
| `consul_server_ca_cert_arn` | string | (Optional) The Secrets Manager secret containing the CA cert for HTTPS communication with Consul servers. Required if the server's certificate is self-signed or signed by an internal CA. This is not required for Consul servers in HCP. |
| `ecs_cluster_arn` | string | The ECS cluster where the ACL controller will be deployed. |
| `region` | string | The AWS region where the AWS resources will be created. |
| `subnets` | list | The AWS VPC subnet ids where the ACL controller will be deployed. |
| `name_prefix` | string | AWS resources created by the `acl-controller` module will include this prefix in the resource name. |
<EnterpriseAlert>
If you are using Consul Enterprise, see the [Admin Partitions and Namespaces requirements documentation](/consul/docs/ecs/requirements) for additional configuration required to support Consul Enterprise on ECS.
</EnterpriseAlert>
## Deploy your services
Follow the instructions described in [Create a task definition](/consul/docs/ecs/terraform/install#create-the-task-definition) to create the basic configuration for the task module. Add the following additional configurations to make the configuration production-ready.
### Create an AWS Secrets Manager secret
The secret stores the gossip encryption key that the Consul clients use.
<CodeBlockConfig>
```hcl
resource "aws_secretsmanager_secret" "gossip_key" {
name = "gossip-encryption-key"
}
resource "aws_secretsmanager_secret_version" "gossip_key" {
secret_id = aws_secretsmanager_secret.gossip_key.id
secret_string = "<Gossip encryption key>"
}
```
</CodeBlockConfig>
### Enable secure deployment
To enable secure deployment, add the following configuration to the task module.
```hcl
module "my_task" {
source = "hashicorp/consul-ecs/aws//modules/mesh-task"
version = "<version>"
...
tls = true
consul_server_ca_cert_arn = aws_secretsmanager_secret.ca_cert.arn
gossip_key_secret_arn = aws_secretsmanager_secret.gossip_key.arn
acls = true
consul_http_addr = "https://consul-server.example.com:8501"
consul_https_ca_cert_arn = aws_secretsmanager_secret.ca_cert.arn
audit_logging = true
}
```
The following table explains the `mesh-task` input variables relevant to a secure configuration:
| Input Variable | Type | Description |
| ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------- |
| `tls` | boolean | If true, TLS is enabled for RPC communication with the Consul servers. |
| `consul_server_ca_cert_arn` | string | The Secrets Manager secret containing the CA certificate for RPC communication with the Consul servers when TLS is enabled. |
| `gossip_key_secret_arn` | string | The Secrets Manager secret containing Consul's gossip encryption key. |
| `acls` | boolean | If true, ACLs are enabled. |
| `consul_http_addr` | string | The Consul server address. Required when `acls = true` in order to log in to Consul's AWS IAM auth method to obtain ACL tokens. |
| `consul_https_ca_cert_arn` | string | (optional) The Secrets Manager secret containing the CA cert for HTTPS communication with Consul servers. Required if the server's certificate is self-signed or signed by an internal CA. This is not required for Consul servers in HCP. |
| `audit_logging` | boolean | <EnterpriseAlert inline /> (optional) If true, ACL audit logging is enabled. Consul client is configured to print audit logs to `stdout`. |
Complete the following steps described in the Installation with Terraform chapter to deploy and connect your services:
1. [Run Terraform](/consul/docs/ecs/terraform/install#run-terraform)
1. [Configure routes](/consul/docs/ecs/terraform/install#configure-routes)
1. [Configure the bind address](/consul/docs/ecs/terraform/install#configure-the-bind-address)

68
website/content/docs/ecs/upgrade-to-dataplanes.mdx Normal file
View File

@ -0,0 +1,68 @@
---
layout: docs
page_title: Upgrade to Consul dataplane architecture
description: Learn how to upgrade your existing Consul service mesh on ECS workloads to the agentless dataplanes architecture.
---
# Upgrade to Consul dataplane architecture
This topic describes how to manually upgrade a live installation of Consul on ECS to the dataplane-based architecture with zero downtime. Since v0.7.0, Consul service mesh on ECS uses [Consul dataplanes](/consul/docs/connect/dataplane), which are lightweight processes for managing Envoy proxies in containerized networks. Refer to the [release notes](/consul/docs/release-notes/consul-ecs/v0_7_x) for additional information about the switch to Consul dataplanes.
## Requirements
Before you upgrading to the dataplane-based architecture, you must upgrade your Consul servers to a version compatible with Consul ECS:
- Consul 1.14.x and later
- Consul dataplane 1.3.x and later
## Deploy the latest version of the ECS controller module
In an ACL enabled cluster, deploy the latest version of the ECS controller module in `hashicorp/terraform-aws-consul-ecs` along with the older version of the ACL controller. Note that both the controllers should coexist until the upgrade is complete. The new version of the controller only tracks tasks that use dataplanes.
## Upgrade workloads
For application tasks, upgrade the individual task definitions to `v0.7.0` or later of the `mesh-task` module. You must upgrade each task one at a time.
```hcl
module "my_task" {
source = "hashicorp/consul-ecs/aws//modules/mesh-task"
version = "v0.7.0"
}
```
For gateway tasks, upgrade the individual task definitions to `v0.7.0` or later of the `gateway-task` module. You must upgrade each task one by one independently. ECS creates new versions of tasks before shutting down the older tasks to support zero downtime deployments.
```hcl
module "my_task" {
source = "hashicorp/consul-ecs/aws//modules/gateway-task"
version = "v0.7.0"
}
```
## Delete previous tasks
After upgrading all tasks, you can destroy the `acl-controller` containers, which are replaced by the ECS controller. You can manually remove any artifacts related to the old architecture, including Consul clients and ACL controllers, by executing the following commands:
1. Run `consul acl policy delete` to delete the client policy. You can pass either the ID of the policy or the name of the policy, for example:
```shell-session
$ consul acl policy delete -name="consul-ecs-client-policy"
```
Refer to the [`consul acl policy delete`](/consul/commands/acl/policy/delete) documentation for additional information.
1. Run the `consul acl role delete` command to delete the client role. You can pass either the ID of the role or the name of the role, for example:
```shell-session
$ consul acl role delete -name="consul-ecs-client-role"
```
Refer to the [`consul acl role delete`](/consul/commands/acl/role/delete) documentation for additional information.
1. Run the `consul acl auth-method delete` command and specify the auth method name to delete.
```shell-session
$ consul acl auth-method delete -name="iam-ecs-client-token"
```
Refer to the [`consul acl auth-method delete`](/consul/commands/acl/auth-method/delete) documentation for additional information.

4
website/content/docs/release-notes/consul-ecs/v0_5_x.mdx
View File

@ -11,9 +11,9 @@ description: >-
- **Audit Logging (Enterprise) :** Consul on ECS now captures authentication events and processes them with the HTTP API. Audit logging provides insight into access and usage patterns. Refer to [Audit Logging](/consul/docs/ecs/enterprise#audit-logging) for usage information.
- **AWS IAM Auth Method :** This feature provides support for Consul's AWS IAM auth method. This allows AWS IAM roles and users to authenticate with Consul to obtain ACL tokens. Refer to [ECS Configuration Reference](/consul/docs/ecs/configuration-reference#consullogin) for configuration information.
- **AWS IAM Auth Method :** This feature provides support for Consul's AWS IAM auth method. This allows AWS IAM roles and users to authenticate with Consul to obtain ACL tokens. Refer to [ECS Configuration Reference](/consul/docs/ecs/reference/configuration-reference#consullogin) for configuration information.
- **Mesh Gateways :** This feature introduces support for running mesh gateways as ECS tasks. Mesh gateways enable service mesh communication across datacenter and admin partition boundaries. Refer to [ECS Installation with Terraform](/consul/docs/ecs/terraform/install#configure-the-gateway-task-module) for usage information.
- **Mesh Gateways :** This feature introduces support for running mesh gateways as ECS tasks. Mesh gateways enable service mesh communication across datacenter and admin partition boundaries. Refer to [ECS Installation with Terraform](/consul/docs/ecs/deploy/terraform#configure-the-gateway-task-module) for usage information.
## Supported Software Versions

92
website/data/docs-nav-data.json
View File

@ -1539,63 +1539,63 @@
"title": "Overview",
"path": "ecs"
},
{
"title": "Requirements",
"path": "ecs/requirements"
},
{
"title": "Task Resource Usage",
"path": "ecs/task-resource-usage"
},
{
"title": "Install with Terraform",
"routes": [
{
"title": "Installation",
"path": "ecs/terraform/install"
},
{
"title": "Secure Configuration",
"path": "ecs/terraform/secure-configuration"
},
{
"title": "Migrate Existing Tasks",
"path": "ecs/terraform/migrate-existing-tasks"
}
]
},
{
"title": "Install Manually",
"routes": [
{
"title": "Installation",
"path": "ecs/manual/install"
},
{
"title": "Secure Configuration",
"path": "ecs/manual/secure-configuration"
},
{
"title": "ACL Controller",
"path": "ecs/manual/acl-controller"
}
]
},
{
"title": "Architecture",
"path": "ecs/architecture"
},
{
"title": "Technical specifications",
"path": "ecs/tech-specs"
},
{
"title": "Deploy Consul to ECS",
"routes": [
{
"title": "Deploy using the Terraform module",
"path": "ecs/deploy/terraform"
},
{
"title": "Deploy manually",
"path": "ecs/deploy/manual"
},
{
"title": "Configure the ECS task bind address",
"path": "ecs/deploy/bind-addresses"
},
{
"title": "Configure routes between ECS tasks",
"path": "ecs/deploy/configure-routes"
},
{
"title": "Migrate existing tasks",
"path": "ecs/deploy/migrate-existing-tasks"
}
]
},
{
"title": "Upgrade to Consul dataplane architecture",
"path": "ecs/upgrade-to-dataplanes"
},
{
"title": "Consul Enterprise",
"path": "ecs/enterprise"
},
{
"title": "Configuration Reference",
"path": "ecs/configuration-reference"
"title": "Reference",
"routes": [
{
"title": "ECS configuration reference",
"path": "ecs/reference/configuration-reference"
},
{
"title": "Compatibility Matrix",
"path": "ecs/compatibility"
"title": "ECS compatibility matrix",
"path": "ecs/reference/compatibility"
},
{
"title": "ECS Consul server JSON schema",
"path": "ecs/reference/consul-server-json"
}
]
}
]
},

BIN
website/public/img/ecs/consul-on-ecs-architecture-dataplanes-dark.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 67 KiB

BIN
website/public/img/ecs/consul-on-ecs-architecture-dataplanes.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 66 KiB

50
website/redirects.js
View File

@ -87,4 +87,54 @@ module.exports = [
destination: '/consul/docs/connect/proxies/deploy-sidecar-services',
permanent: true,
},
{
source: '/consul/docs/ecs/terraform/install',
destination: '/consul/docs/ecs/deploy/terraform',
permanent: true,
},
{
source: '/consul/docs/ecs/terraform/secure-configuration',
destination: '/consul/docs/ecs/deploy/terraform',
permanent: true,
},
{
source: '/consul/docs/ecs/terraform/migrate-existing-tasks',
destination: '/consul/docs/ecs/deploy/migrate-existing-tasks',
permanent: true,
},
{
source: '/consul/docs/ecs/manual/install',
destination: '/consul/docs/ecs/deploy/manual',
permanent: true,
},
{
source: '/consul/docs/ecs/manual/secure-configuration',
destination: '/consul/docs/ecs/deploy/manual',
permanent: true,
},
{
source: '/consul/docs/ecs/manual/acl-controller',
destination: '/consul/docs/ecs/deploy/manual',
permanent: true,
},
{
source: '/consul/docs/ecs/task-resource-usage',
destination: '/consul/docs/ecs/tech-specs',
permanent: true,
},
{
source: '/consul/docs/ecs/requirements',
destination: '/consul/docs/ecs/tech-specs',
permanent: true,
},
{
source: '/consul/docs/ecs/configuration-reference',
destination: '/consul/docs/ecs/reference/configuration-reference',
permanent: true,
},
{
source: '/consul/docs/ecs/compatibility',
destination: '/consul/docs/ecs/reference/compatibility',
permanent: true,
},
]