You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This module simplifies deploying containerized applications using AWS Fargate and ECS. It creates ECS services with task definitions, ALB integration, auto-scaling, CloudWatch logging, optional EFS, WAF, Shield, Route53, and IAM configurations.
4
+
5
+
## Features
6
+
7
+
- AWS Fargate ECS service with task definition
8
+
- Application Load Balancer (ALB) support
9
+
- Health checks and sticky sessions
10
+
- Auto scaling and scheduled scaling
11
+
- CloudWatch logging with configurable retention
12
+
- Optional WAF, Shield, and DNS integration
13
+
- Tagging support across all resources
14
+
15
+
## Prerequisites
16
+
17
+
To use this module, ensure you have the following:
18
+
19
+
-**Terraform**: Version 1.9.5
20
+
-**AWS Provider**: Version 5.0 or higher
21
+
-**AWS Account**: Configured with appropriate permissions to create ECS, ALB, IAM, and related resources
22
+
-**VPC and Subnets**: A pre-existing VPC with private subnets (and optionally public subnets for public-facing ALBs)
23
+
-**Security Groups**: Two pre-existing AWS security groups—one for the ECS tasks (`security_group_ids`) and one for the ALB (`alb_security_group_ids`)
24
+
-**Optional Resources** (if used):
25
+
- ECS cluster (if `cluster_name` is not `"default"`)
26
+
- ACM certificates (if `certificate_arns` is provided for HTTPS)
27
+
- Route53 hosted zone (if `hosted_zone_id` is provided for DNS)
28
+
- EFS file system (if `efs_configs` is used)
29
+
- S3 bucket (if `alb_log_bucket_name` is used for ALB logs)
30
+
- WAF ACLs (if `global_waf_acl` or `regional_waf_acl` is used)
|`task_definition`| The ECS task definition object |
100
+
|`service`| The ECS service object |
101
+
|`task_role`| The IAM role used by the ECS tasks |
102
+
|`alb_dns`| The DNS name of the Application Load Balancer |
103
+
|`alb`| The Application Load Balancer object |
104
+
105
+
## Notes
106
+
107
+
- For a full list of variables, see [`variables.tf`](./variables.tf).
108
+
- This module assumes IAM permissions and VPC networking is already set up.
109
+
- This module supports both public and internal ALBs.
4
110
5
-
### Variables
6
-
7
-
##### Common
8
-
9
-
*`family` - A unique name for the service family; Also used for naming various resources.
10
-
*`container_definitions` - List of `{name, image}` at minimum. If using more than 1 container, must also define `portMappings = [{ containerPort = <port> }]` on the container to be reached by the load balancer. See [AWS documentation](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ContainerDefinition.html) for more the complete list of settings. See [the examples directory](./examples) for different implementation examples.
11
-
12
-
##### Fargate Task and Service Configuration
13
-
14
-
*`cluster_name` - The name of the ECS cluster where the Fargate service will run. Default is the default AWS cluster.
15
-
*`enable_execute_command` - Enable executing command inside a container running in Fargate service. Default is false.
16
-
*`log_group_name` - The name of the log group. By default the `family` variable will be used.
17
-
*`log_group_retention_in_days` - The number of days to retain the log group. By default logs will never expire.
18
-
*`log_group_region` - The region where the log group exists. By default the current region will be used.
19
-
*`task_cpu` - How much CPU should be reserved for the container (in aws cpu-units). Default is `256`.
20
-
*`task_memory` - How much Memory should be reserved for the container (in MB). Default is `512`.
21
-
*`task_cpu_architecture` - The task CPU architecture (e.g. `X86_64`, `ARM64`); Only supported on platform version `1.4.0`.
22
-
*`container_port` - Port the container listens on. Default is `80` (only valid with single container configurations, if using more then one container the port will need to be defined with your container definitions).
23
-
*`platform_version` - The ECS backend platform version; Defaults to `1.4.0` so EFS is supported.
24
-
*`task_policy_json` - A JSON formatted IAM policy providing the running container with permissions. By default, no permissions granted.
25
-
*`iam_role_path` - Path attached to created IAM roles
26
-
*`iam_role_permissions_boundary` - Permissions Boundary ARN attached to created IAM roles
27
-
28
-
##### Container volume configuration
29
-
*`efs_configs` - List of EFS configurations, see examples.
30
-
*`nonpersistent_volume_configs` - List of {volume_name, container_name, container_path} non-persistent volumes
31
-
32
-
##### Deployment and Scaling Configuration
33
-
*`desired_capacity` - The desired number of containers running in the service. Default is `1`.
34
-
*`max_capacity` - The maximum number of containers running in the service. Default is same as `desired_capacity`.
35
-
*`min_capacity` - The minimum number of containers running in the service. Default is same as `desired_capacity`.
36
-
*`scaling_metric` - A type of target scaling. Needs to be either `cpu` or `memory`. Default is no scaling.
37
-
*`scaling_threshold` - The percentage in which the scaling metric will trigger a scaling event. Default is no scaling.
38
-
*`health_check_path` - A relative path for the services health checker to hit. Default is `/`.
39
-
*`health_check_healthy_threshold` - The number of consecutive health checks successes required before considering an unhealthy target healthy. Defaults to 10.
40
-
*`health_check_unhealthy_threshold` - The number of consecutive health check failures required before considering the target unhealthy. Defaults to 10.
41
-
*`health_check_timeout` - The amount of time, in seconds, during which no response means a failed health check. Defaults to 2.
42
-
*`health_check_interval` - The approximate amount of time, in seconds, between health checks of an individual target. Defaults to 30.
43
-
*`health_check_matcher` - The HTTP codes to use when checking for a successful response from a target. Defaults to `200-399`.
44
-
*`deregistration_delay` - The amount time for Elastic Load Balancing to wait before changing the state of a deregistering target from draining to unused. The range is 0-3600 seconds. The default value is 20 seconds.
45
-
*`deployment_maximum_percent` - Upper limit on the number of running tasks that can be during a deployment. Default is 200.
46
-
*`deployment_minimum_healthy_percent` - Lower limit percentage of tasks that must be reporting healthy during a deployment. Default is 100.
47
-
*`enable_deployment_rollbacks` - Turn on rollbacks for deployments. This means that if a deployment fails, it will roll back to the previous version. Defaults to `false`, but `true` is the recommended setting for production environments.
48
-
*`wait_for_steady_state` - Configure terraform to wait for ECS service to be deployed and stable before terraform finishes. Note that Fargate deployments can take a remarkably long time to reach a steady state, and thus your terraform deployment times will increase by a few minutes. Defaults to `false`, but `true` is recommended for production environments.
49
-
50
-
##### Network and Routing Configuration
51
-
52
-
*`vpc_id` - Required; A vpc-id.
53
-
*`private_subnet_ids` - Required; A list of subnet-ids; Application load-balancer will be internal unless `public_subnet_ids` are provided.
54
-
*`public_subnet_ids` - Optional; A list of subnet-ids; Application Load-balancer will be public facing.
55
-
*`security_group_ids` - Required; A set of Security Group IDs to be associated with the Fargate service.
56
-
*`alb_security_group_ids` - Required; A set of Security Group IDs to be associated with the Application Load-balancer.
57
-
*`certificate_arn` - A certificate ARN being managed via ACM. If provided we will redirect 80 to 443 and serve on 443/https. Otherwise traffic will be served on 80/http.
58
-
*`hosted_zone_id` - The hosted zone ID where the A record will be created. Required if `certificate_arn` is set.
59
-
*`service_fqdn` - Fully qualified domain name (www.example.com) you wish to use for your service. Must be valid against the ACM cert provided. Required if `certificate_arn` is set.
60
-
*`route53_allow_overwrite` - Set the `allow_overwrite` property of the route53 record. If `true`, there will be no `terraform import` necessary for pre-existing records. Default is `false`.
61
-
*`alb_log_bucket_name` - The S3 bucket name to store the ALB access logs in.
62
-
*`alb_log_prefix` - Prefix for each object created in ALB access log bucket.
63
-
*`alb_idle_timeout` - Idle Timeout configuration for ALB. Defaults to 60. If behind a CloudFront, maximum request time is 60 seconds. If not behind CloudFront, and your application has long-running requests, you might need to increase this timeout.
64
-
*`global_waf_acl` - Global Web Application Firewall ID that will be applied to the CloudFront distribution. For wafv1, provide the WAF ID. For WAFv2 provide the ARN. By default no association will be made.
65
-
*`regional_waf_acl` - Regional Web Application Firewall identifier. For wafv1, provide the WAF ID. For WAFv2 provide the ARN. By default no association will be made.
66
-
*`listeners` - The ALB listener port configuration. By default port 80 will be forwarded unless a certificate is provided then port 80 will redirect to port 443 which will then be forwarded. Here are some [examples](./examples/listener/main.tf) of listener configurations.
67
-
*`listener_ssl_policy` - The SSL policy name given to HTTPS listeners by default.
68
-
*`ipv6` - Boolean to enable ipv6 on the ALB and Route53. Ensure your VPC is configured to be ipv6 compatible before enabling. Defaults to `false`.
69
-
*`alb_sticky_duration` - By default, sticky sessions are disabled. Once a number value is provided, sticky sessions are enabled, and the provided number is used to determine sticky session's duration in seconds.
70
-
*`alb_sticky_cookie_type` - By default a cookie type of `lb_cookie` will be used. Only `lb_cookie` and `app_cookie` are supported.
71
-
*`alb_sticky_cookie_name` - Applicable only when `app_cookie` is configured. The sticky session cookie domain name used when the `app_cookie` type is used.
72
-
*`alb_drop_invalid_header_fields` - Optional; Indicates whether HTTP headers with header fields that are not valid are removed by the load balancer (true) or routed to targets (false). The default is false. Elastic Load Balancing requires that message header names contain only alphanumeric characters and hyphens. Only valid for Load Balancers of type application.
73
-
74
-
##### Lights On/Off
75
-
76
-
*`lights_on_schedule_expr` - Expression that will trigger an event to restore max/min capacity back to configured settings. Defaults to `""`. See [Application AutoScaling Schedule](https://docs.aws.amazon.com/autoscaling/application/APIReference/API_ScheduledAction.html#API_ScheduledAction_Contents) for details.
77
-
*`lights_off_schedule_expr` - Expression that will trigger an event to set max/min capacity to zero. Defaults to `""`. See [Application AutoScaling Schedule](https://docs.aws.amazon.com/autoscaling/application/APIReference/API_ScheduledAction.html#API_ScheduledAction_Contents) for details
78
-
*`schedule_timezone` - IANA Timezone in which to base `at` and `cron` schedule expressions. Defaults to `"UTC"`. See [Time Zone List](https://www.joda.org/joda-time/timezones.html)
79
-
80
-
##### Shield Advanced Protection
81
-
82
-
**NOTE:** This setting does not `enroll` your account into shield advanced and that is a requirement to use this feature! Please do your due diligence before enabling shield advanced for your account or organization as it costs $3000 / per month
83
-
84
-
*`enable_shield_protection` - Optional; Enables shield advanced protection on the Application Load Balancer. Default is false
85
-
86
-
##### Tagging
87
-
88
-
All tags are optional maps of key-value pairs, and default to empty
89
-
90
-
*`tags` - Tags to apply to all resources
91
-
*`tags_ecs` - Tags to apply to all ecs resources
92
-
*`tags_ecs_task_definition` - Tags to apply to the task definition
93
-
*`tags_ecs_service` - Tags to apply to the ECS service
94
-
*`tags_alb` - Tags to apply to ALB resources
95
-
*`tags_alb_tg` - Tags to apply to the ALB target group
96
-
*`tags_iam_role` - Tags to apply to the IAM Roles
97
-
98
-
*`tags_ecs_service_enabled` - Enable/Disable all tags on ECS Service to avoid conflicts with Accounts/Clusters using the old ARN formats. Defaults to true, adding tags to all ecs services
99
-
100
-
## Examples
111
+
## Usage
101
112
102
113
### Working examples
103
114
104
-
See the [examples directory](./examples) for some working terraform examples using different features
115
+
See the [examples directory](./examples) for some working terraform examples using different features.
0 commit comments