rvn-ecs-web / Latest version: 2.4.0
See ECS Web Service module reference for the full module page.
ECS cluster
$ref:rvn-ecs-cluster
required
Cluster.
- Immutable after creation
cluster to null.
Mapped inputs for cluster: set these keys alongside cluster, not inside it, when supplying existing infrastructure instead of a module reference.
string
AWS account.
- Default:
<<ref.input.aws_account_id>> - Immutable after creation
string
Region.
- Default:
<<ref.input.aws_region>> - Immutable after creation
string
Terraform execution environment. Terraform execution environment inherited from the selected ECS cluster.
- Default:
<< ref.input.execution_environment_id >>
string
required
Cluster ARN.
- Default:
<<ref.stack.output.cluster_arn>> - Immutable after creation
number
Cluster default log retention (days). Default CloudWatch Logs retention inherited from the selected ECS cluster. Override it per service in the Compliance section.
- Default:
<<ref.stack.output.log_retention_days>>
string
required
VPC ID.
- Default:
<<ref.input.vpc_id>> - Immutable after creation
string_array
required
Private subnet IDs. Private subnets available from the selected ECS cluster network.
- Default:
<<ref.input.private_subnet_ids>> - Immutable after creation
string_array
Public subnet IDs. Public subnets available from the selected ECS cluster network.
- Default:
<<ref.input.public_subnet_ids>> - Immutable after creation
string_array
Private subnet IDs. Legacy service subnet override. Leave blank to derive subnets from the public/private service setting.
- Default:
<<ref.input.private_subnet_ids>> - Immutable after creation
section
Cluster capacity providers.
string
Fargate capacity provider.
- Default:
<<ref.stack.output.fargate_capacity_provider_name>> - Immutable after creation
string
Fargate spot capacity provider.
- Default:
<<ref.stack.output.fargate_spot_capacity_provider_name>> - Immutable after creation
string
EC2 capacity provider. EC2 capacity provider name from the selected cluster.
- Default:
<<ref.stack.output.ec2_capacity_provider_name>> - Immutable after creation
section
Cluster load balancers.
string
Public ALB HTTP listener ARN.
- Default:
<<ref.stack.output.public_alb_http_listener_arn>> - Immutable after creation
string
Public ALB HTTPS listener ARN. HTTPS listener ARN from the selected public ALB. Ravion uses it when present, otherwise falls back to HTTP.
- Default:
<<ref.stack.output.public_alb_https_listener_arn>> - Immutable after creation
string
Public ALB security group ID.
- Default:
<<ref.stack.output.public_alb_security_group_id>> - Immutable after creation
string
Private ALB HTTP listener ARN.
- Default:
<<ref.stack.output.private_alb_http_listener_arn>> - Immutable after creation
string
Private ALB HTTPS listener ARN. HTTPS listener ARN from the selected private ALB. Ravion uses it when present, otherwise falls back to HTTP.
- Default:
<<ref.stack.output.private_alb_https_listener_arn>> - Immutable after creation
string
Private ALB security group ID.
- Default:
<<ref.stack.output.private_alb_security_group_id>> - Immutable after creation
boolean
Ravion-managed domains. On: Ravion manages service certificates and listener rules. Off: attach certificates on the cluster and configure listener rules here.
- Default:
<< ref.stack.output.ravion_managed_domains_enabled || false >>
string
Cluster domain. Base for the service’s Ravion address.
- Default:
<<ref.stack.output.ravion_cluster_domain_fqdn>>
string
Public ALB DNS name.
- Default:
<<ref.stack.output.public_alb_dns_name>> - Immutable after creation
string
Public ALB hosted zone ID.
- Default:
<<ref.stack.output.public_alb_zone_id>> - Immutable after creation
string
Private ALB DNS name.
- Default:
<<ref.stack.output.private_alb_dns_name>> - Immutable after creation
string
Private ALB hosted zone ID.
- Default:
<<ref.stack.output.private_alb_zone_id>> - Immutable after creation
string
Public ALB ARN suffix.
- Default:
<<ref.stack.output.public_alb_arn_suffix>> - Immutable after creation
string
Private ALB ARN suffix.
- Default:
<<ref.stack.output.private_alb_arn_suffix>> - Immutable after creation
Web service
string
required
Service name. Name for the ECS service and related resources.
- Default:
<<project.given_id>>-<<environment.given_id>>-<<module.given_id>> - Immutable after creation
- Pattern:
^[A-Za-z0-9][A-Za-z0-9_-]{0,254}$— Use 1-255 letters, numbers, underscores, or hyphens, starting with a letter or number.
boolean
Public web service. Expose this service through the public ALB. Turn off to use the private ALB.
- Default:
true
boolean
Run in private subnets. Recommended. Requires a NAT gateway or equivalent for internet access and a static IP.
- Default:
true
Domains
boolean
Default Ravion domain. Off requires at least one custom domain.
- Default:
true - Shown when:
{"ravion_managed_domains_enabled":true}
string
Subdomain.
- Default:
<< module.given_id >> - Pattern:
^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$— Use 1-63 lowercase letters, numbers, or hyphens, starting and ending with a letter or number. - Shown when:
{"ravion_domain_enabled":true,"ravion_managed_domains_enabled":true}
string_array
Custom domains. Served alongside the default Ravion domain when it is on. Ravion manages certificates and listener rules; add the provided DNS records at your DNS provider.
- Shown when:
{"ravion_managed_domains_enabled":true}
Build config
string
required
Build source.
- Default:
dockerfile - Allowed values:
dockerfile(Dockerfile),railpack(Railpack),image_registry(Pull from image registry),ecr(Managed ECR repository)
gitrepo
required
Git repository. Repository containing the application source for Dockerfile or Railpack builds.
- Shown when:
{"build_source":["dockerfile","railpack"]}
string
Source base path. Repository-relative source and build root.
- Default:
. - Shown when:
{"build_source":["dockerfile","railpack"]}
string
required
Image repository. Image repository without a tag or digest, such as
nginx, ghcr.io/org/app, or 123456789012.dkr.ecr.us-east-1.amazonaws.com/app.- Shown when:
{"build_source":"image_registry"}
string
Registry credentials secret ARN. Secrets Manager secret ARN for private registries such as GHCR or Docker Hub. The secret must use the ECS repository credentials JSON format. Not needed for public images or normal same-account ECR.
- Shown when:
{"build_source":"image_registry"}
string_array
Start command. Optional command arguments that override the image default command. For shell behavior, use
/bin/sh, -lc, and your command string as separate arguments.- Default:
[] - Shown when:
{"build_source":["image_registry","ecr"]}
Docker
string
Dockerfile path. Path to the Dockerfile to use for the build, relative to the repository root or configured source base path.
- Shown when:
{"build_source":"dockerfile"}
string
Docker build context path. Directory to use as the Docker build context, relative to the repository root or configured source base path.
- Shown when:
{"build_source":"dockerfile"}
Railpack
string
Railpack version. Optional Railpack version to use for the build. Leave blank to use the Ravion default.
- Pattern:
^(|latest|v?[0-9]+\.[0-9]+\.[0-9]+(?:[-+][0-9A-Za-z.-]+)?)$— Leave blank, use latest, a semantic version like 0.29.0, or a v-prefixed version like v0.29.0. - Shown when:
{"build_source":"railpack"}
string
Install command. Optional dependency installation command. Leave blank to use Railpack detection.
- Shown when:
{"build_source":"railpack"}
string
Build command. Optional application build command. Leave blank to use Railpack detection.
- Shown when:
{"build_source":"railpack"}
string
Start command.
- Shown when:
{"build_source":"railpack"}
Deployment
string
required
Deployment strategy. Choose how traffic moves from the current deployment to the new deployment.
- Default:
rolling - Allowed values:
rolling(Rolling),blue_green(Blue/green),linear(Linear),canary(Canary)
number
Bake time in minutes. Minutes to keep the current and new deployments running after production traffic has fully shifted, before the old deployment is removed.
- Default:
10 - Min:
0 - Max:
1440 - Shown when:
{"deployment_strategy":["blue_green","linear","canary"]}
number
Healthy tasks required for success (%). Percentage of desired tasks that must be running and healthy on the new revision. Must be at least Minimum healthy percent. ECS still requires one healthy task on nonzero services at 0%. Deployment rollback monitoring ends at success; remaining tasks scale in the background.
- Default:
100 - Min:
<< module.input.deployment_minimum_healthy_percent >> - Max:
100 - Shown when:
{"deployment_strategy":"rolling"}
boolean
Wait for old tasks to drain. Choose whether old tasks must finish draining before deployment success. Alarm bake time still applies in both modes.
- Default:
false - Shown when:
{"deployment_strategy":"rolling"}
number
Linear step percentage. Percentage of production traffic to move to the new deployment at each linear step.
- Default:
20 - Min:
1 - Max:
100 - Shown when:
{"deployment_strategy":"linear"}
number
Linear step bake time in minutes. Minutes to wait between linear traffic steps before shifting the next percentage.
- Default:
5 - Min:
0 - Max:
1440 - Shown when:
{"deployment_strategy":"linear"}
number
Canary percent. Percentage of production traffic to send to the new deployment during the canary phase.
- Default:
5 - Min:
1 - Max:
100 - Shown when:
{"deployment_strategy":"canary"}
number
Canary bake time in minutes. Minutes to hold canary traffic before shifting the remaining production traffic to the new deployment.
- Default:
10 - Min:
0 - Max:
1440 - Shown when:
{"deployment_strategy":"canary"}
object_array
Manual approval gates. Optional gates that pause the deployment at chosen lifecycle stages until you approve it. Applies only to the blue/green, linear, and canary strategies.
- Default:
[{"stage":"POST_TEST_TRAFFIC_SHIFT","timeout_action":"ROLLBACK","timeout_in_minutes":1440}] - Shown when:
{"deployment_strategy":["blue_green","linear","canary"]}
Health check
number
required
Container port. Port the web container listens on.
- Default:
80 - Min:
1 - Max:
65535 - Immutable after creation
string
required
Health check path. HTTP path the load balancer calls to verify the web server is healthy. Use a lightweight endpoint that does not require authentication.
- Default:
/
string
required
Success codes. HTTP status code matcher for successful health checks. Defaults to 200-399 so redirects and common successful responses are accepted.
- Default:
200-399
number
Interval (secs). Seconds between load balancer health checks. Lower values detect failures faster but send more health-check traffic.
- Default:
5 - Min:
5 - Max:
300
number
Timeout (secs). Seconds to wait for the health-check response before marking that check as failed. Must be lower than the interval.
- Default:
4 - Min:
2 - Max:
120
number
Healthy threshold. Number of consecutive successful checks required before an unhealthy target is considered healthy.
- Default:
2 - Min:
2 - Max:
10
number
Unhealthy threshold. Number of consecutive failed checks required before a target is considered unhealthy.
- Default:
2 - Min:
2 - Max:
10
number
Health check grace period (secs). Seconds ECS ignores failing load balancer health checks after a task starts. Increase this for apps with slow boot times.
- Default:
0 - Min:
0
number
Deregistration delay (secs). Seconds the load balancer allows in-flight requests to complete after a task starts deregistering.
- Default:
300 - Min:
0 - Max:
3600
number
Slow start duration (secs). Gradually ramps traffic to newly registered targets. Use 0 to disable.
- Default:
0 - Min:
0 - Max:
900
boolean
Sticky sessions. Enable load balancer cookie stickiness so repeat requests are routed to the same task when possible. When enabled, traffic-shift deployments also keep clients on the first production or alternate target group they reach.
- Default:
true
string
Stickiness type.
- Default:
lb_cookie - Allowed values:
lb_cookie(Load balancer cookie),app_cookie(Application cookie) - Shown when:
{"target_group_stickiness_enabled":true}
number
Stickiness cookie duration (secs).
- Default:
86400 - Min:
1 - Max:
604800 - Shown when:
{"target_group_stickiness_enabled":true}
string
Application cookie name.
- Shown when:
{"target_group_stickiness_type":"app_cookie"}
HTTP listener rules
string_array
Domain host rules. Hostnames that should route to this service, such as app.example.com or *.example.com. Leave empty to use path-based routing.
- Shown when:
{"ravion_managed_domains_enabled":false}
string_array
Path rules. Path patterns that should route to this service, such as /, /api/, or /app/. If both domain host rules and path rules are empty, the service routes all paths with /.
- Shown when:
{"ravion_managed_domains_enabled":false}
number
Listener rule priority. Optional ALB listener rule priority. Leave blank to let AWS assign the next available priority.
- Min:
1 - Max:
50000 - Shown when:
{"ravion_managed_domains_enabled":false}
Container resources
string
required
Capacity provider. Choose the primary capacity provider. Most services should use only one provider.
- Default:
fargate - Allowed values:
fargate(Fargate),fargate_spot(Fargate spot),ec2(EC2)
boolean
Also use Fargate. Add Fargate to the capacity provider strategy in addition to the primary provider.
- Default:
false - Shown when:
{"capacity_provider":{"not":"fargate"}}
boolean
Also use Fargate spot. Add lower-cost interruptible Fargate spot capacity in addition to the primary provider.
- Default:
false - Shown when:
{"capacity_provider":{"not":"fargate_spot"}}
boolean
Also use EC2. Add EC2 capacity from the selected cluster in addition to the primary provider.
- Default:
false - Shown when:
{"capacity_provider":{"not":"ec2"}}
compound
required
App size. CPU and memory for Fargate tasks. Prices are estimated from AWS Fargate pricing for the selected region, architecture, and capacity provider.
- Default:
{"memory_gb":4,"vcpu":2} - Shown when:
{"capacity_provider":["fargate","fargate_spot"]}
number
App ephemeral storage (GiB). Optional ephemeral storage size for each Fargate app task, from 21 to 200 GiB. Leave blank to use the AWS default of 20 GiB.
- Min:
21 - Max:
200 - Shown when:
{"capacity_provider":["fargate","fargate_spot"]}
string
required
App vCPU. vCPU reserved for each app task on EC2 capacity. Leave at least 0.25 vCPU unreserved on each EC2 instance for the ECS agent and system processes.
- Default:
1.5 - Pattern:
^(?:0|[1-9][0-9]*)(?:\.[0-9]+)?$— Enter a vCPU value, such as 0.5, 1, or 2. - Shown when:
{"capacity_provider":"ec2"}
string
required
App memory in GB. Memory reserved for each app task on EC2 capacity. Leave at least 0.5 GB unreserved on each EC2 instance for the ECS agent and system processes.
- Default:
3.5 - Pattern:
^(?:0|[1-9][0-9]*)(?:\.[0-9]+)?$— Enter a memory value in GB, such as 0.5, 1, or 4. - Shown when:
{"capacity_provider":"ec2"}
string
CPU architecture. Use x86_64 for broad compatibility; use ARM64 for lower cost when your image and dependencies support it.
- Default:
X86_64 - Allowed values:
X86_64(x86_64 - widest compatibility),ARM64(ARM64 - lower cost)
boolean
ECS exec. Enable ECS Exec for interactive debugging in running containers. Leave off by default for tighter access control; turn on when operators need shell/debug access through AWS Systems Manager.
- Default:
false
Autoscaling
boolean
Autoscaling.
- Default:
true
number
Minimum tasks. Recommend at least 2 for production.
- Default:
1 - Min:
0 - Shown when:
{"auto_scaling_enabled":true}
number
Maximum tasks.
- Default:
3 - Min:
1 - Shown when:
{"auto_scaling_enabled":true}
number
Desired tasks. Number of tasks to keep running when autoscaling is disabled.
- Default:
1 - Min:
1 - Shown when:
{"auto_scaling_enabled":false}
number
CPU target (%).
- Default:
70 - Min:
1 - Max:
100 - Shown when:
{"auto_scaling_enabled":true}
number
Memory target (%). Target average memory utilization for memory-based autoscaling. Leave blank to disable memory autoscaling.
- Default:
80 - Min:
1 - Max:
100 - Shown when:
{"auto_scaling_enabled":true}
number
Scale-in cooldown (secs). Time after a scale-in activity before another scale-in can happen. AWS defaults ECS target tracking cooldowns to 300 secs; start here for production and tune if needed.
- Default:
300 - Min:
0 - Shown when:
{"auto_scaling_enabled":true}
number
Scale-out cooldown (secs). Time after a scale-out activity before another scale-out can happen. AWS defaults ECS target tracking cooldowns to 300 secs; start here for production and tune if needed.
- Default:
300 - Min:
0 - Shown when:
{"auto_scaling_enabled":true}
boolean
Scale in. Allow autoscaling to reduce task count automatically.
- Default:
true - Shown when:
{"auto_scaling_enabled":true}
object_array
Scheduled scaling actions. Optional Application Auto Scaling scheduled actions for the ECS service desired tasks. Each action sets a recurring, one-time, or rate-based schedule and may update the minimum tasks, maximum tasks, or both.
- Default:
[] - Shown when:
{"auto_scaling_enabled":true}
object_array
Custom metric scaling policies. Additional target tracking scaling policies using custom CloudWatch metrics. Each policy must use a metric that changes proportionally with ECS service capacity.
- Default:
[] - Shown when:
{"auto_scaling_enabled":true}
number
Requests per task target. Target average number of load balancer requests per task per minute (ALBRequestCountPerTarget). Applies only with the Rolling deployment strategy, because blue/green, linear, and canary deployments move production traffic between target groups. Leave blank to disable request-count autoscaling.
- Min:
1 - Shown when:
{"auto_scaling_enabled":true}
Environment variables
object
Build environment variables. Only available during the build, not at runtime. Use environment variables or secrets for runtime values.
boolean
Inject environment variables in Dockerfile. Pass build environment variables into Dockerfile builds as build arguments.
- Default:
false - Shown when:
{"build_source":"dockerfile"}
array
Runtime environment variables. Runtime environment variables passed to the app container. PORT is added automatically from the container port setting.
array
Runtime secrets. Secrets injected into the ECS task at runtime, as an array of objects with
name and value_from keys (snake_case, not valueFrom). value_from is an SSM Parameter Store or Secrets Manager ARN.