Merge pull request #11033 from hashicorp/consul-ecs-beta-docs
updates to ECS docs per beta release
This commit is contained in:
Paul Glass
GitHub
commit
19ae767f6e
|
|
@ -11,8 +11,6 @@ Installing Consul on ECS is a multi-part process:
|
|||
|
||||
1. [**Terraform:**](#terraform) Your tasks must be specified in Terraform using [`ecs_task_definition`](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ecs_task_definition)
|
||||
and [`ecs_service`](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ecs_service) resources.
|
||||
1. [**Consul Server:**](#consul-server) You must deploy the Consul server onto the cluster using the [`dev-server` module](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/dev-server).
|
||||
1. [**Task IAM Role:**](#task-iam-role) Modify task IAM role to add `ecs:ListTasks` and `ecs:DescribeTasks` permissions.
|
||||
1. [**Task Module:**](#task-module) You can then take your `ecs_task_definition` resources and copy their configuration into a new [`mesh-task` module](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task)
|
||||
resource that will add the necessary containers to the task definition.
|
||||
1. [**Routing:**](#routing) With your tasks as part of the mesh, you must specify their upstream
|
||||
|
|
@ -39,8 +37,6 @@ resource "aws_ecs_task_definition" "my_task" {
|
|||
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"
|
||||
|
|
@ -72,136 +68,6 @@ resource "aws_ecs_service" "my_task" {
|
|||
}
|
||||
```
|
||||
|
||||
## Consul Server
|
||||
|
||||
With your tasks defined in Terraform, you're ready to run the Consul server
|
||||
on ECS.
|
||||
|
||||
-> **NOTE:** This is a development-only Consul server. It has no persistent
|
||||
storage and so will lose any data when it restarts. This should only be
|
||||
used for test workloads. In the future, we will support Consul servers
|
||||
running in HashiCorp Cloud Platform and on EC2 VMs for production workloads.
|
||||
|
||||
In order to deploy the Consul server, use the `dev-server` module:
|
||||
|
||||
```hcl
|
||||
module "dev_consul_server" {
|
||||
source = "hashicorp/consul/aws-ecs//modules/dev-server"
|
||||
version = "<latest version>"
|
||||
|
||||
ecs_cluster_arn = var.ecs_cluster_arn
|
||||
subnet_ids = var.subnet_ids
|
||||
lb_vpc_id = var.vpc_id
|
||||
load_balancer_enabled = true
|
||||
lb_subnets = var.lb_subnet_ids
|
||||
lb_ingress_rule_cidr_blocks = var.lb_ingress_rule_cidr_blocks
|
||||
log_configuration = {
|
||||
logDriver = "awslogs"
|
||||
options = {
|
||||
awslogs-group = aws_cloudwatch_log_group.log_group.name
|
||||
awslogs-region = var.region
|
||||
awslogs-stream-prefix = "consul-server"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
data "aws_security_group" "vpc_default" {
|
||||
name = "default"
|
||||
vpc_id = var.vpc_id
|
||||
}
|
||||
|
||||
resource "aws_security_group_rule" "ingress_from_server_alb_to_ecs" {
|
||||
type = "ingress"
|
||||
from_port = 8500
|
||||
to_port = 8500
|
||||
protocol = "tcp"
|
||||
source_security_group_id = module.dev_consul_server.lb_security_group_id
|
||||
security_group_id = data.aws_security_group.vpc_default.id
|
||||
}
|
||||
|
||||
output "consul_server_url" {
|
||||
value = "http://${module.dev_consul_server.lb_dns_name}:8500"
|
||||
}
|
||||
```
|
||||
|
||||
-> **NOTE:** The documentation for all possible inputs can be found in the [module reference
|
||||
docs](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/dev-server?tab=inputs).
|
||||
|
||||
The example code above will create a Consul server ECS task and Application Load
|
||||
Balancer for the Consul UI. You can then use the output `consul_server_url` as
|
||||
the URL to the Consul server.
|
||||
|
||||
## Task IAM Role
|
||||
|
||||
Your tasks must have an IAM role that allows them to list and describe
|
||||
other tasks. This is required in order for the tasks to find the IP
|
||||
address of the Consul server.
|
||||
|
||||
The specific permissions needed are:
|
||||
|
||||
1. `ecs:ListTasks` on resource `*`.
|
||||
1. `ecs:DescribeTasks` on all tasks in this account and region. You can either
|
||||
use `*` for simplicity or scope it to the region and account, e.g. `arn:aws:ecs:us-east-1:1111111111111:task/*`. If
|
||||
your account is configured to use the new, [longer ECS task ARN format](https://docs.aws.amazon.com/AmazonECS/latest/userguide/ecs-account-settings.html#ecs-resource-ids)
|
||||
then you can further scope `ecs:DescribeTasks` down to tasks in a specific cluster, e.g. `arn:aws:ecs:us-east-1:1111111111111:task/MY_CLUSTER_NAME/*`.
|
||||
|
||||
The IAM role's ARN will be passed into the `mesh-task` module in the next step
|
||||
via the `task_role_arn` input.
|
||||
|
||||
-> **NOTE:** There are two IAM roles needed by ECS Tasks: Execution roles and
|
||||
Task roles. Here we are referring to the Task role, not the Execution role.
|
||||
The Execution role is used by ECS itself whereas the Task role defines the
|
||||
permissions for the containers running in the task.
|
||||
|
||||
Terraform for creating the IAM role might look like:
|
||||
|
||||
```hcl
|
||||
data "aws_caller_identity" "this" {}
|
||||
|
||||
resource "aws_iam_role" "this_task" {
|
||||
name = "this_task"
|
||||
assume_role_policy = jsonencode({
|
||||
Version = "2012-10-17"
|
||||
Statement = [
|
||||
{
|
||||
Action = "sts:AssumeRole"
|
||||
Effect = "Allow"
|
||||
Sid = ""
|
||||
Principal = {
|
||||
Service = "ecs-tasks.amazonaws.com"
|
||||
}
|
||||
},
|
||||
]
|
||||
})
|
||||
|
||||
inline_policy {
|
||||
name = "this_task"
|
||||
policy = jsonencode({
|
||||
Version = "2012-10-17"
|
||||
Statement = [
|
||||
{
|
||||
Effect = "Allow"
|
||||
Action = [
|
||||
"ecs:ListTasks",
|
||||
]
|
||||
Resource = "*"
|
||||
},
|
||||
{
|
||||
Effect = "Allow"
|
||||
Action = [
|
||||
"ecs:DescribeTasks"
|
||||
]
|
||||
Resource = [
|
||||
"arn:aws:ecs:${var.region}:${data.aws_caller_identity.this.account_id}:task/*",
|
||||
]
|
||||
}
|
||||
]
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
## Task Module
|
||||
|
||||
In order to add the necessary sidecar containers for your task to join the mesh,
|
||||
|
|
@ -218,8 +84,6 @@ module "my_task" {
|
|||
version = "<latest version>"
|
||||
|
||||
family = "my_task"
|
||||
execution_role_arn = "arn:aws:iam::111111111111:role/execution-role"
|
||||
task_role_arn = "arn:aws:iam::111111111111:role/task-role"
|
||||
container_definitions = [
|
||||
{
|
||||
name = "example-client-app"
|
||||
|
|
@ -239,7 +103,7 @@ module "my_task" {
|
|||
]
|
||||
|
||||
port = "9090"
|
||||
consul_server_service_name = module.dev_consul_server.ecs_service_name
|
||||
retry_join = "<address of the Consul server>"
|
||||
}
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -7,16 +7,10 @@ description: >-
|
|||
|
||||
# Requirements
|
||||
|
||||
Currently, the following requirements must be met in order to install Consul on ECS:
|
||||
The following requirements must be met in order to install Consul on ECS:
|
||||
|
||||
1. **Terraform:** The tasks that you want to add to the service mesh must first be modeled in Terraform.
|
||||
1. **Launch Type:** Only the Fargate launch type is currently 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 to pull images.
|
||||
1. **Consul Servers:** Currently, Consul servers must run inside ECS on Fargate using the `dev-server` Terraform module. This is a development/testing only server that does not support persistent storage. In the future, we will support production-ready Consul servers running in HashiCorp Cloud Platform and on EC2 VMs.
|
||||
|
||||
## Future Improvements
|
||||
|
||||
- Support EC2 launch type.
|
||||
- Support production-ready Consul servers running outside of ECS in HashiCorp Cloud Platform or EC2.
|
||||
- Support Consul TLS, ACLs, and Gossip Encryption.
|
||||
- Support Consul service health checks.
|
||||
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 (VM) or use HCP Consul. For development purposes or testing, you may use the `dev-server` [Terraform module](https://github.com/hashicorp/terraform-aws-consul-ecs/tree/main). The `dev-server` does not support persistent storage.
|
||||
1. **ACL Controller:** If you are running a secure Consul installation, configure the ACL controller.
|
||||
|
|
|
|||
|
|
@ -8,8 +8,8 @@ description: >-
|
|||
|
||||
# AWS ECS
|
||||
|
||||
-> **Tech Preview:** This functionality is currently in Tech Preview and is
|
||||
not yet ready for production use.
|
||||
-> **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.
|
||||
|
|
|
|||
|
|
@ -556,7 +556,7 @@
|
|||
]
|
||||
},
|
||||
{
|
||||
"title": "AWS ECS <sup>Tech Preview</sup>",
|
||||
"title": "AWS ECS <sup>BETA</sup>",
|
||||
"routes": [
|
||||
{
|
||||
"title": "Overview",
|
||||
|
|
|
|||
Loading…
Reference in New Issue