SourceFuse's AWS Reference Architecture Terraform module leverages the terraform-aws-modules/terraform-aws-ecs GitHub repository to facilitate the deployment and management of an AWS ECS (Elastic Container Service) cluster. It streamlines the configuration of ECS tasks, services, and related components, providing a scalable and efficient solution for orchestrating containerized applications. With customizable settings for logging, load balancing, and service discovery, the module promotes seamless deployment and management of containerized workloads on AWS.
The module assumes that upstream dependencies, namely networking dependencies, are created upstream and the values are passed into this module via mechanisms such as Terraform data source queries.
The module provisions
Our approach to ECS Fargate clusters is to provision a cluster and allow downstream services to attach to it via convention based data source queries.
Before using this module, ensure you have the following:
Initially, it's essential to define a Terraform module, which is organized as a distinct directory encompassing Terraform configuration files. Within this module directory, input variables and output values must be defined in the variables.tf and outputs.tf files, respectively. The following illustrates an example directory structure:
ecs/
|-- main.tf
|-- variables.tf
|-- outputs.tf
Inside the variables.tf
or in *.tfvars
file, you should define values for the variables that the module requires.
module "ecs" {
source = "sourcefuse/arc-ecs/aws"
version = "1.5.2"
environment = var.environment
namespace = var.namespace
vpc_id = data.aws_vpc.vpc.id
alb_subnet_ids = data.aws_subnets.public.ids
health_check_subnet_ids = data.aws_subnets.private.ids
// --- Devs: DO NOT override, otherwise tests will fail --- //
access_logs_enabled = false
alb_access_logs_s3_bucket_force_destroy = true
alb_access_logs_s3_bucket_force_destroy_enabled = true
// -------------------------- END ------------------------- //
## create acm certificate and dns record for health check
route_53_zone_name = var.route_53_zone
route_53_zone_id = data.aws_route53_zone.this.id
acm_domain_name = "healthcheck-ecs-${var.namespace}-${var.environment}.${local.route_53_zone}"
acm_subject_alternative_names = []
health_check_route_53_records = [
"healthcheck-ecs-${var.namespace}-${var.environment}.${local.route_53_zone}"
]
service_discovery_private_dns_namespace = [
"${var.namespace}.${var.environment}.${local.route_53_zone}"
]
tags = module.tags.tags
}
Inside the outputs.tf
file of the module, you can define output values that can be referenced in the main configuration. For example:
output "cluster_name" {
description = "Name of the ECS Cluster"
value = module.ecs.cluster_name
}
output "health_check_fqdn" {
description = "Health check FQDN record created in Route 53."
value = module.ecs.health_check_fqdn
}
After defining your main configuration, navigate to the directory containing your Terraform files and run the following commands:
terraform init
terraform apply
Terraform will display a plan showing the changes it intends to make. Review the plan and confirm by typing 'yes' when prompted.
Name | Version |
---|---|
terraform | >= 1.4, < 2.0.0 |
aws | >= 4.0, < 6.0 |
Name | Version |
---|---|
aws | 4.67.0 |
Name | Source | Version |
---|---|---|
acm | git::https://github.com/cloudposse/terraform-aws-acm-request-certificate | 0.17.0 |
alb | ./modules/alb | n/a |
alb_sg | git::https://github.com/cloudposse/terraform-aws-security-group | 2.0.0 |
ecs | git::https://github.com/terraform-aws-modules/terraform-aws-ecs | v5.11.1 |
health_check | ./modules/health-check | n/a |
Name | Type |
---|---|
aws_cloudwatch_log_group.this | resource |
aws_iam_role.execution | resource |
aws_iam_role_policy_attachment.execution | resource |
aws_lb_listener.http | resource |
aws_lb_listener.https | resource |
aws_service_discovery_private_dns_namespace.this | resource |
aws_ssm_parameter.this | resource |
aws_iam_policy_document.assume | data source |
Name | Description | Type | Default | Required |
---|---|---|---|---|
access_logs_enabled | A boolean flag to enable/disable access_logs | bool |
true |
no |
acm_domain_name | Domain name the ACM Certificate belongs to | string |
n/a | yes |
acm_process_domain_validation_options | Flag to enable/disable processing of the record to add to the DNS zone to complete certificate validation | bool |
true |
no |
acm_process_domain_validation_record_ttl | The TTL of the record to add to the DNS zone to complete certificate validation | string |
"300" |
no |
acm_subject_alternative_names | Subject alternative names for the ACM Certificate | list(string) |
[] |
no |
additional_ssm_params | Additional SSM Parameters you would like to add for your ECS configuration. The optional value defaults are: description = "Managed by Terraform" type = "SecureString" overwrite = true |
list(object({ |
[] |
no |
alb_access_logs_s3_bucket_force_destroy | A boolean that indicates all objects should be deleted from the ALB access logs S3 bucket so that the bucket can be destroyed without error | bool |
false |
no |
alb_access_logs_s3_bucket_force_destroy_enabled | When true , permits force_destroy to be set to true .This is an extra safety precaution to reduce the chance that Terraform will destroy and recreate your S3 bucket, causing COMPLETE LOSS OF ALL DATA even if it was stored in Glacier. WARNING: Upgrading this module from a version prior to 0.27.0 to this version will cause Terraform to delete your existing S3 bucket CAUSING COMPLETE DATA LOSS unless you follow the upgrade instructions on the Wiki here. See additional instructions for upgrading from v0.27.0 to v0.28.0 here. |
bool |
false |
no |
alb_certificate_arn | ALB Certificate ARN. If var.create_acm_certificate is true , this will be ignored. |
string |
null |
no |
alb_idle_timeout | The time that the connection is allowed to be idle. | number |
300 |
no |
alb_internal | Determines if this load balancer is internally or externally facing. | bool |
false |
no |
alb_ssl_policy | Load Balancer SSL policy. | string |
"ELBSecurityPolicy-FS-1-2-Res-2020-10" |
no |
alb_subnet_ids | Subnet Ids assigned to the LB | list(string) |
n/a | yes |
cluster_name_override | Name to assign the cluster. If null, the default will be namespace-environment-cluster |
string |
null |
no |
create_acm_certificate | Create an ACM Certificate to use with the ALB | bool |
true |
no |
environment | ID element. Usually used for region e.g. 'uw2', 'us-west-2', OR role 'prod', 'staging', 'dev', 'UAT' | string |
n/a | yes |
execution_policy_attachment_arns | The ARNs of the policies you want to apply | list(string) |
[ |
no |
externally_managed_route_53_record | If there is a Route 53 Zone externally managed from the account you are running in. If true , you will have to manage your DNS yourself. |
bool |
false |
no |
health_check_route_53_records | List of Route 53 records for the health check service. | list(string) |
n/a | yes |
health_check_subnet_ids | Subnet IDs for the health check tasks to run in. If not defined, this will use var.alb_subnet_ids . |
list(string) |
[] |
no |
log_group_retention_days | Specifies the number of days you want to retain log events in the specified log group. Possible values are: 1, 3, 5, 7, 14, 30, 60, 90, 120, 150, 180, 365, 400, 545, 731, 1096, 1827, 2192, 2557, 2922, 3288, 3653, and 0. If you select 0, the events in the log group are always retained and never expire |
number |
30 |
no |
log_group_skip_destroy | Set to true if you do not wish the log group (and any logs it may contain) to be deleted at destroy time, and instead just remove the log group from the Terraform state. | bool |
false |
no |
namespace | Namespace your resource belongs to. Usually an abbreviation of your organization name, e.g. 'example' or 'arc', to help ensure generated IDs are globally unique" |
string |
n/a | yes |
route_53_zone_id | Route 53 zone ID | string |
null |
no |
route_53_zone_name | Route 53 domain to generate an ACM request for and to create A records against, i.e. sfrefarch.com. A wildcard subject alternative name is generated with the certificate. | string |
null |
no |
service_discovery_private_dns_namespace | The name of the namespace | list(string) |
[ |
no |
tags | Tags to assign the resources. | map(string) |
{} |
no |
vpc_id | Id of the VPC where the resources will live | string |
n/a | yes |
Name | Description |
---|---|
alb_arn | ARN to the ALB |
alb_certificate_arn | ACM Certificate ARN |
alb_dns_name | External DNS name to the ALB |
alb_dns_zone_id | External DNS name to the ALB |
alb_http_listener_arn | HTTP listener ARN for downstream services to use |
alb_https_listener_arn | HTTPS listener ARN for downstream services to use |
alb_security_group_id | ALB Security Group |
cluster_arn | ECS Cluster ARN |
cluster_id | ECS Cluster ID |
cluster_name | ECS Cluster name |
health_check_fqdn | Health check FQDN record created in Route 53. |
There are some commonly referenced outputs generated by this module.
These outputs are also published to SSM for ease of access for downstream resources.
The default SSM Parameter format used by this module is the following:
[
## alb
{
name = "/${var.namespace}/${var.environment}/alb/${module.alb.alb_name}/endpoint"
value = module.alb.alb_dns_name
description = "ALB DNS Endpoint"
type = "String"
},
{
name = "/${var.namespace}/${var.environment}/alb/${module.alb.alb_name}/arn"
value = module.alb.alb_arn
description = "ALB ARN"
type = "String"
},
## ecs
{
name = "/${var.namespace}/${var.environment}/ecs/${module.ecs.cluster_name}/id"
value = module.ecs.cluster_id
description = "ECS Cluster ID"
type = "String"
},
{
name = "/${var.namespace}/${var.environment}/ecs/${module.ecs.cluster_name}/arn"
value = module.ecs.cluster_arn
description = "ECS Cluster ARN"
type = "String"
}
]
You can append to this array by adding values to var.additional_ssm_params
.
while Contributing or doing git commit please specify the breaking change in your commit message whether its major,minor or patch
For Example
git commit -m "your commit message #major"
By specifying this , it will bump the version and if you don't specify this in your commit message then by default it will consider patch and will bump that accordingly
pre-commit install
test
directorycd test/
go mod init github.com/sourcefuse/terraform-aws-refarch-ecs
go get github.com/gruntwork-io/terratest/modules/terraform
go test -timeout 30m
This project is authored by: