github
/
consul
mirror of https://github.com/hashicorp/consul
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge pull request #11033 from hashicorp/consul-ecs-beta-docs

Browse Source 
updates to ECS docs per beta release
pull/11053/head
Paul Glass 3 years ago committed by GitHub
parent 0eb4a98fab 1e97752f31
commit 2604719ce6
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 9 additions and 151 deletions
Show Stats Download Patch File Download Diff File

138
website/content/docs/ecs/get-started/install.mdx
Unescape View File

@ -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>"
}
```

16
website/content/docs/ecs/get-started/requirements.mdx
Unescape View File

@ -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.

4
website/content/docs/ecs/index.mdx
Unescape View File

@ -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.

2
website/data/docs-nav-data.json
Unescape View File

@ -556,7 +556,7 @@
]
},
{
"title": "AWS ECS <sup>Tech Preview</sup>",
"title": "AWS ECS <sup>BETA</sup>",
"routes": [
{
"title": "Overview",

Write Preview
Loading…
Cancel
Save