Merge pull request #11583 from hashicorp/consul-ecs-ga-docs

Consul ECS GA Docs

website/content/docs/ecs/architecture.mdx

@@ -31,14 +31,39 @@ at startup and sets up initial configuration for Consul and Envoy.
 
 This diagram shows the timeline of a task starting up and all its containers:
 
-![Task Startup Timeline](/img/ecs-task-startup.png)
+<img alt="Task Startup Timeline" src="/img/ecs-task-startup.svg" style={{display: "block", maxWidth: "400px"}} />
 
 - **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.
-- **T1:** The `sidecar-proxy` container starts. It runs Envoy by executing `envoy -c <path-to-bootstrap-json>`.
+  - `mesh-init` 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 write it to a shared volume. `mesh-init` exits after completing these operations.
+
+- **T1:** The following containers start:
+  - The `sidecar-proxy` container starts and runs Envoy by executing `envoy -c <path-to-bootstrap-json>`.
+  - If applicable, the `health-sync` container 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. The only running containers are `consul-client`, `sidecar-proxy`, and your application container(s).
 
+### Task Shutdown
+
+This diagram shows an example timeline of a task shutting down:
+
+<img alt="Task Shutdown Timeline" src="/img/ecs-task-shutdown.svg" style={{display: "block", maxWidth: "400px"}} />
+
+- **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. This allows the application container to continue making outgoing requests through the proxy to the mesh.
+  - `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` updates its Consul checks to critical status and exits. This ensures this service instance is marked unhealthy.
+  - `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.
+
 ### Automatic ACL Token Provisioning
 
 Consul ACL tokens secure communication between agents and services.
@@ -57,3 +82,15 @@ 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.
+
+### 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.

website/content/docs/ecs/get-started/install.mdx

@@ -49,7 +49,7 @@ module "my_task" {
   ]
 
   port       = "9090"
-  retry_join = "<address of the Consul server>"
+  retry_join = ["<address of the Consul server>"]
 }
 ```
 
@@ -63,7 +63,7 @@ however there are some important inputs worth highlighting:
 - `port` is the port that your application listens on. This should be set to a
   string, not an integer, i.e. `port = "9090"`, not `port = 9090`.
 - `retry_join` is passed to the [`-retry-join`](/docs/agent/options#_retry_join) option for the Consul agent. This tells
-  the agent the location of your Consul server so that it can join the Consul cluster.
+  the agent the location of your Consul servers so that it can join the Consul cluster.
 
 -> **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.

website/content/docs/ecs/get-started/migrate-existing-tasks.mdx

@@ -91,7 +91,7 @@ module "my_task" {
   ]
 
   port       = "9090"
-  retry_join = "<address of the Consul server>"
+  retry_join = ["<address of the Consul server>"]
 }
 ```
 

website/content/docs/ecs/index.mdx

@@ -8,11 +8,7 @@ description: >-
 
 # AWS ECS
 
--> **Beta:** This functionality is currently in beta and is
-not recommended for use in production environments. Refer to the [consul-ecs project road map](https://github.com/hashicorp/consul-ecs/projects/1) for information about upcoming features and enhancements.
-
-Consul can be deployed on [AWS ECS](https://aws.amazon.com/ecs/) (Elastic Container Service) using our official
-Terraform modules.
+Consul can be deployed on [AWS ECS](https://aws.amazon.com/ecs/) (Elastic Container Service) using our official Terraform modules.
 
 ![Consul on ECS Architecture](/img/consul-ecs-arch.png)
 
@@ -22,12 +18,13 @@ Using Consul on AWS ECS enables you to add your ECS tasks to the service mesh an
 take advantage of features such as zero-trust-security, intentions, observability,
 traffic policy, and more.
 
-## Example Installation
+## Getting Started
 
-See our [Example Installation](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/examples/dev-server-fargate)
-to learn how to install Consul on an example ECS cluster along with example service mesh applications.
+There are several ways to get started with Consul with ECS.
 
-## Install
+* The [Serverless Consul Service Mesh with ECS and HCP](https://learn.hashicorp.com/tutorials/cloud/consul-ecs-hcp?in=consul/cloud-integrations) learn guide shows how to use Terraform to run Consul service mesh applications on ECS with managed Consul servers running in HashiCorp Cloud Platform (HCP).
+* The [Service Mesh with ECS and Consul on EC2](https://learn.hashicorp.com/tutorials/consul/consul-ecs-ec2?in=consul/cloud-integrations) learn guide shows how to use Terraform to run Consul service mesh applications on ECS with Consul servers running on EC2 instances.
+* 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 applciation in ECS using the EC2 launch type.
 
-See our full [Install Guide](/docs/ecs/get-started/install) when you're ready to install Consul
-on an existing ECS cluster and add existing tasks to the service mesh.
+See the [Requirements](/docs/ecs/get-started/requirements) and the full [Install Guide](/docs/ecs/get-started/install) when you're ready to install Consul on an existing ECS cluster and add existing tasks to the service mesh.

website/data/docs-nav-data.json

@@ -560,7 +560,7 @@
     ]
   },
   {
-    "title": "AWS ECS <sup>BETA</sup>",
+    "title": "AWS ECS",
     "routes": [
       {
         "title": "Overview",
@@ -569,14 +569,6 @@
       {
         "title": "Get Started",
         "routes": [
-          {
-            "title": "Example Installation on ECS Fargate",
-            "href": "https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/examples/dev-server-fargate"
-          },
-          {
-            "title": "Example Installation on ECS EC2",
-            "href": "https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/examples/dev-server-ec2"
-          },
           {
             "title": "Requirements",
             "path": "ecs/get-started/requirements"