luxolus
/
open-consul
2
0
Fork 0
Code Issues 1 Pull Requests Packages Releases Wiki Activity

Consul on ECS 0.4.0 (#12694) 

Update website docs for Consul on ECS 0.4.0
This commit is contained in:
Chris Thain 2022-04-07 11:43:12 -07:00 committed by GitHub
parent 6feb7abe57
commit a125e12c78
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 120 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -73,7 +73,13 @@ This diagram shows an example timeline of a task shutting down:
- 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
## ACL Controller
The ACL controller performs the following operations:
* Provisions Consul ACL tokens for Consul clients and service mesh services.
* Manages Consul admin partitions and namespaces.
### Automatic ACL Token Provisioning
Consul ACL tokens secure communication between agents and services.
The following containers in a task require an ACL token:
@ -92,6 +98,21 @@ 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.
### Admin Partitions and Namespaces<EnterpriseAlert inline />
When [admin partitions and namespaces](/docs/ecs/enterprise#admin-partitions-and-namespaces) are enabled,
the ACL controller is assigned to its configured admin partition. The ACL controller provisions ACL
tokens for tasks in a single admin partition and supports one ACL controller instance per ECS
cluster. This results in an architecture with one admin partition per ECS cluster.
The ACL controller automatically performs the following actions:
* Creates its admin partition at startup if it does not exist.
* Inspects ECS task tags for the task's intended partition and namespace.
The ACL controller ignores tasks that do not match the `partition` tag.
* Creates namespaces when tasks start up. Namespaces are only created if they do not exist.
* Provisions ACL tokens and ACL policies that are scoped to the applicable admin partition and namespace.
* Provision ACL tokens that allow services to communicate with upstreams across admin partitions and namespaces.
## ECS Health Check Syncing
If the following conditions apply, ECS health checks automatically sync with Consul health checks for all application containers:

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

@ -38,28 +38,86 @@ run Consul Enterprise clients then you must enable ACLs.
## Running Open Source Consul Clients
Consul supports running Consul Enterprise servers with Consul OSS (Open Source) clients. Since
currently no Consul Enterprise features are supported that require Consul client support,
you can run Consul OSS clients with Consul Enterprise servers without issue.
You can operate Consul Enterprise servers with Consul OSS (open source) clients as long as the features you are using do not require Consul Enterprise client support. Admin partitions and namespaces, for example, require Consul Enterprise clients and are not supported with Consul OSS.
## Feature Support
Consul on ECS does not currently support any Consul Enterprise features that require
support from Consul clients. That being said, there are many enterprise features that
are activated only on Consul servers and so Consul on ECS will run fine with those
features.
Consul on ECS supports the following Consul Enterprise features.
If you are only using features that run on Consul servers, then you can use an OSS client in your service mesh tasks on ECS.
If client support is required for any of the features, then you must use a Consul Enterprise client in your `mesh-tasks`.
| Feature | Supported | Description |
|-----------------------------------|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Automated Backups/Snapshot Agent | Yes* | Running the snapshot agent on ECS is not currently supported but you are able to run the snapshot agent alongside your Consul servers on VMs. |
| Automated Upgrades | Yes (servers) | This feature runs on Consul servers. |
| Enhanced Read Scalability | Yes (servers) | This feature runs on Consul servers. |
| Single Sign-On/OIDC | Yes (servers) | This feature runs on Consul servers. |
| Redundancy Zones | Yes (servers) | This feature runs on Consul servers. |
| Advanced Federation/Network Areas | Yes (servers) | This feature runs on Consul servers. |
| Sentinel | Yes (servers) | This feature runs on Consul servers. |
| Network Segments | No | Currently there is no capability to configure the network segment Consul clients on ECS run in. |
| Namespaces | No | Currently there is no capability to configure the Consul namespace for a service on ECS. |
| Admin Partitions | No* | Supported if Consul ECS clients run in the default partition. Otherwise there is currently no capability to configure the admin partition Consul clients in ECS run in. |
| Audit Logging | No* | Audit logging can be enabled on Consul servers that run outside of ECS but is not currently supported on the Consul clients that run inside ECS. |
| Feature | Supported | Description |
|-----------------------------------|---------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Automated Backups/Snapshot Agent | Yes* | Running the snapshot agent on ECS is not currently supported but you are able to run the snapshot agent alongside your Consul servers on VMs. |
| Automated Upgrades | Yes (servers) | This feature runs on Consul servers. |
| Enhanced Read Scalability | Yes (servers) | This feature runs on Consul servers. |
| Single Sign-On/OIDC | Yes (servers) | This feature runs on Consul servers. |
| Redundancy Zones | Yes (servers) | This feature runs on Consul servers. |
| Advanced Federation/Network Areas | Yes (servers) | This feature runs on Consul servers. |
| Sentinel | Yes (servers) | This feature runs on Consul servers. |
| Network Segments | No | Currently there is no capability to configure the network segment Consul clients on ECS run in. |
| Namespaces | Yes | This feature requires Consul Enterprise servers. OSS clients can register into the `default` namespace. Registration into a non-default namespace requires a Consul Enterprise client. |
| Admin Partitions | Yes | This feature requires Consul Enterprise servers. OSS clients can register into the `default` admin partition. Registration into a non-default partition requires a Consul Enterprise client. |
| Audit Logging | No* | Audit logging can be enabled on Consul servers that run outside of ECS but is not currently supported on the Consul clients that run inside ECS. |
### Admin Partitions and Namespaces
Consul on ECS supports [admin partitions](/docs/enterprise/admin-partitions) and [namespaces](/docs/enterprise/namespaces) when Consul Enterprise servers and clients are used.
These features have the following requirements:
* ACLs must be enabled.
* ACL controller must run in the ECS cluster.
* `mesh-tasks` must use a Consul Enterprise client image.
The ACL controller automatically manages ACL policies and token provisioning for clients and services on the service mesh.
It also creates admin partitions and namespaces if they do not already exist.
-> **NOTE:** The ACL controller does not delete admin partitions or namespaces once they are created.
Each ACL controller manages a single admin partition. Consul on ECS supports one ACL controller per ECS cluster;
therefore, the administrative boundary for admin partitions is one admin partition per ECS cluster.
The following example demonstrates how to configure the ACL controller to enable admin partitions
and manage an admin partition named `my-partition`. The `consul_partition` field is optional and if it
is not provided when `consul_partitions_enabled = true`, will default to the `default` admin partition.
<CodeBlockConfig highlight="6-7">
```hcl
module "acl_controller" {
source = "hashicorp/consul/aws-ecs//modules/acl-controller"
...
consul_partitions_enabled = true
consul_partition = "my-partition"
}
```
</CodeBlockConfig>
Services are assigned to admin partitions and namespaces through the use of [task tags](/docs/ecs/manual/install#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
the partition it will default to the `default` admin partition. Similarly, if a `mesh-task` does
not define the namespace it will default to the `default` namespace.
The following example demonstrates how to create a `mesh-task` assigned to the admin partition named
`my-partition`, in the `my-namespace` namespace.
<CodeBlockConfig highlight="7-9">
```hcl
module "my_task" {
source = "hashicorp/consul/aws-ecs//modules/mesh-task"
family = "my_task"
...
consul_image = "hashicorp/consul-enterprise:<version>-ent"
consul_partition = "my-partition"
consul_namespace = "my-namespace"
}
```
</CodeBlockConfig>

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

@ -24,7 +24,7 @@ traffic policy, and more.
Consul on ECS follows an [architecture](/docs/internals/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 faciliate data plane communication for
communication and an [Envoy](https://envoyproxy.io/) sidecar proxy container to facilitate data plane communication for
[Consul Connect](/docs/connect).
For a detailed architecture overview, see the [Architecture](/docs/ecs/architecture) page.

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

@ -72,10 +72,12 @@ during task startup.
The `tags` list must include the following if you are using the ACL controller in a [secure configuration](/docs/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`. |
| 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

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

@ -9,18 +9,23 @@ description: >-
The following requirements must be met in order to install Consul on ECS:
1. **Launch Type:** Fargate and EC2 launch types are supported.
1. **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.
1. **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.
1. **ACL Controller:** If you are running a secure Consul installation with ACLs enabled, configure the ACL controller.
1. **Sidecar containers:** Consul on ECS requires two sidecar containers to run in each ECS task: a
* **Launch Type:** Fargate and EC2 launch types are 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](/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](/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](/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](/docs/ecs/manual/install).
1. **Routing:** With your application running in tasks as part of the mesh, you must specify the
* **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.
1. **Bind Address:** Once all communication is flowing through the service mesh, you should change
* **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.

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

@ -21,7 +21,7 @@ A secure Consul cluster should include the following:
Before deploying your service, you will need to deploy the [ACL controller](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/acl-controller) so that it can provision the necessary tokens
for tasks on the service mesh. To learn more about the ACL Controller, please see [Automatic ACL Token Provisioning](/docs/ecs/architecture#automatic-acl-token-provisioning).
To deploy the controller, you will first need store an ACL token with `acl:write` privileges
To deploy the controller, you will first need to store an ACL token with `acl:write` and `operator:write` privileges,
and a CA certificate for the Consul server in AWS Secrets Manager.
```hcl