ECS architecture docs for Beta

website/content/docs/ecs/architecture.mdx

@@ -9,9 +9,9 @@ description: >-
 
 ![Consul on ECS Architecture](/img/consul-ecs-arch.png)
 
-As shown above there are two main components to the architecture.
+As shown above, these are the main components to the architecture for a secure installation:
 
-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
       with the Consul server and configures the Envoy proxy sidecar. This communication
@@ -19,14 +19,13 @@ As shown above there are two main components to the architecture.
    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,28 @@ 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, the user’s application containers are started since all the Consul machinery is ready to service requests.
+- **T3:** 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).
+
+### 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 token used by `consul-client` containers, and
+then starts the ACL controller task. The controller 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.