Merge pull request #11043 from hashicorp/pglass/consul-ecs-arch-doc

ECS architecture docs for Beta

website/content/docs/ecs/architecture.mdx

@@ -7,26 +7,25 @@ description: >-
 
 # Architecture
 
+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)
 
-As shown above there are two main components to the architecture.
-
-1. **Consul Server task:** Runs the Consul server.
+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
+   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
+   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. **ACL Controller:** Automatically provisions Consul ACL tokens for Consul clients and service mesh services
+   in an ECS Cluster.
 
 For more information about how Consul works in general, see Consul's [Architecture Overview](/docs/architecture).
 
-In addition to the long-running Consul Client and Sidecar Proxy containers, there
-are also two initialization containers that run:
-
-1. `discover-servers`: This container runs at startup and uses the AWS API to determine the IP address of the Consul server task.
-1. `mesh-init`: This container runs at startup and sets up initial configuration for Consul and Envoy.
+In addition to the long-running Consul client and sidecar proxy containers, the `mesh-init` container runs
+at startup and sets up initial configuration for Consul and Envoy.
 
 ### Task Startup
 
@@ -34,12 +33,27 @@ This diagram shows the timeline of a task starting up and all its containers:
 
 ![Task Startup Timeline](/img/ecs-task-startup.png)
 
-- **T0:** ECS starts the task. The `discover-servers` container starts looking for the Consul server task’s IP.
-  It waits for the Consul server task to be running on ECS, looks up its IP and then writes the address to a file.
-  Then the container exits.
-- **T1:** Both the `consul-client` and `mesh-init` containers start:
-  - `consul-client` starts up and uses the server IP to join the cluster.
+- **T0:** ECS starts the task. The `consul-client` and `mesh-init` containers start:
+  - `consul-client` uses the `retry-join` option to join the Consul cluster
   - `mesh-init` registers the service for this task and its sidecar proxy into Consul. It runs `consul connect envoy -bootstrap` to generate Envoy’s bootstrap JSON file and write it to a shared volume. After registration and bootstrapping, `mesh-init` exits.
-- **T2:** The `sidecar-proxy` container starts. It runs Envoy by executing `envoy -c <path-to-bootstrap-json>`.
-- **T3:** 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, the user’s application containers are started since all the Consul machinery is ready to service requests.
-- **T4:** Consul marks the service as healthy by running the health checks specified in the task Terraform. The service will now receive traffic. At this time the only running containers are `consul-client`, `sidecar-proxy` and the user’s application container(s).
+- **T1:** The `sidecar-proxy` container starts. It runs Envoy by executing `envoy -c <path-to-bootstrap-json>`.
+- **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. The only running containers are `consul-client`, `sidecar-proxy`, and your application container(s).
+
+### Automatic ACL Token Provisioning
+
+Consul ACL tokens secure communication between agents and services.
+The following containers in a task require an ACL token:
+
+- `consul-client`: The Consul client uses a token to authorize itself with Consul servers.
+  All `consul-client` containers share the same token.
+- `mesh-init`: The `mesh-init` container uses a token to register the service with Consul.
+  This token is unique for the Consul service, and is shared by instances of the service.
+
+The ACL controller automatically creates ACL tokens for mesh-enabled tasks in an ECS cluster.
+The `acl-controller` Terraform module creates the ACL controller task. The controller creates the
+ACL token used by `consul-client` containers at startup and then watches for tasks in the cluster. It checks tags
+to determine if the task is mesh-enabled. If so, it creates the service ACL token for the task, if the
+token does not yet exist.
+
+The ACL controller stores all ACL tokens in AWS Secrets Manager, and tasks are configured to pull these
+tokens from AWS Secrets Manager when they start.