This Terraform module creates ECS services with task definitions, ALB target groups, Service Connect integration, and auto-scaling.
Features#
- Task Definitions: Fargate-compatible task definitions with health checks
- ALB Integration: Target groups and listener rules for path/host routing
- Service Connect: Internal service mesh via AWS Cloud Map
- Auto-Scaling: CPU and memory-based target tracking policies
- Logging: CloudWatch log groups per service
- Secrets: Integration with Secrets Manager and SSM Parameter Store
- Circuit Breaker: Deployment protection with automatic rollback
Usage#
hcl
module "ecs_services" {
source = "../ecs-services"
environment = "production"
region = "us-east-1"
name_prefix = "oshun"
# From ECS cluster module
cluster_arn = module.ecs.cluster_arn
cluster_name = module.ecs.cluster_name
# From VPC module
vpc_id = module.vpc.vpc_id
private_subnet_ids = module.vpc.private_subnet_ids
security_group_ids = [module.ecs.security_group_id]
# From ALB module
alb_listener_arn = module.alb.https_listener_arn
alb_dns_name = module.alb.dns_name
# From ECS cluster module
service_discovery_namespace_id = module.ecs.service_discovery_namespace_id
service_discovery_namespace_name = module.ecs.service_discovery_namespace_name
# From ECS IAM module
task_execution_role_arn = module.ecs.task_execution_role_arn
task_role_arns = {
"isis-generation-api" = module.ecs_roles.service_task_role_arns["isis-generation-api"]
}
# ECR
ecr_registry_url = module.ecr.registry_url
# Service definitions
services = {
isis-generation-api = {
domain = "isis"
description = "Isis Generation API"
image_name = "isis/generation-api"
container_port = 3000
cpu = 512
memory = 1024
desired_count = 2
enable_load_balancer = true
alb_path_pattern = ["/api/isis/generation/*"]
alb_priority = 100
secrets = [
{
name = "DATABASE_URL"
valueFrom = "arn:aws:secretsmanager:..."
}
]
}
}
}
Service Configuration Options#
Basic Configuration#
hcl
services = {
my-service = {
# Required
domain = "isis"
description = "My service description"
image_name = "isis/my-service"
# Optional (with defaults)
enabled = true
image_tag = "latest"
container_port = 3000
protocol = "HTTP" # HTTP, HTTPS, or gRPC
}
}
Resource Allocation#
hcl
services = {
my-service = {
# CPU (256 = 0.25 vCPU, 512 = 0.5 vCPU, 1024 = 1 vCPU, etc.)
cpu = 512
memory = 1024 # MB
# Ephemeral storage (default 21 GB)
ephemeral_storage = 50 # GB, for services that need more scratch space
}
}
Scaling Configuration#
hcl
services = {
my-service = {
desired_count = 2
min_count = 1
max_count = 10
# Auto-scaling
enable_autoscaling = true
autoscaling_cpu_target = 70 # Scale when avg CPU > 70%
autoscaling_memory_target = 80 # Scale when avg memory > 80%
scale_in_cooldown = 300 # seconds
scale_out_cooldown = 60 # seconds
}
}
Capacity Provider Strategy#
hcl
services = {
my-service = {
# Custom capacity provider strategy (overrides default)
capacity_provider_strategy = [
{
capacity_provider = "FARGATE"
weight = 100
base = 1
}
]
}
}
For Spot instances:
hcl
services = {
batch-worker = {
capacity_provider_strategy = [
{
capacity_provider = "FARGATE_SPOT"
weight = 100
base = 0
}
]
}
}
Health Check Configuration#
hcl
services = {
my-service = {
health_check_path = "/health"
health_check_interval = 30 # seconds
health_check_timeout = 5 # seconds
health_check_retries = 3
}
}
Load Balancer Configuration#
hcl
services = {
my-service = {
enable_load_balancer = true
# Path-based routing
alb_path_pattern = ["/api/my-service/*"]
# Or host-based routing
alb_host_header = ["api.example.com"]
# Priority (lower = higher priority)
alb_priority = 100
# Sticky sessions
stickiness_enabled = true
stickiness_duration = 86400 # seconds
}
}
Service Connect (Internal Service Mesh)#
hcl
services = {
my-service = {
enable_service_connect = true
service_connect_port = 3000 # 0 = use container_port
# Service will be discoverable as:
# my-service.oshun.local:3000
}
}
Environment Variables and Secrets#
hcl
services = {
my-service = {
# Plain environment variables
environment = [
{
name = "LOG_LEVEL"
value = "info"
}
]
# Secrets from Secrets Manager
secrets = [
{
name = "DATABASE_URL"
valueFrom = "arn:aws:secretsmanager:...:secret:my-secret:connection_string::"
}
]
# Secrets from SSM Parameter Store
secrets = [
{
name = "API_KEY"
valueFrom = "arn:aws:ssm:...:parameter/my-param"
}
]
}
}
Deployment Configuration#
hcl
services = {
my-service = {
deployment_minimum_healthy_percent = 50 # Allow 50% to be unavailable during deploy
deployment_maximum_percent = 200 # Allow 2x tasks during deploy
enable_circuit_breaker = true # Auto-rollback on failures
enable_execute_command = true # Enable ECS Exec for debugging
}
}
Volume Mounts#
hcl
services = {
my-service = {
volumes = [
{
name = "data"
efs_config = {
file_system_id = "fs-12345678"
root_directory = "/data"
}
}
]
mount_points = [
{
source_volume = "data"
container_path = "/app/data"
read_only = false
}
]
}
}
Accessing Services#
Via ALB (External)#
Services with enable_load_balancer = true are accessible via the ALB:
text
https://alb-dns-name/api/isis/generation/...
Via Service Connect (Internal)#
Services with enable_service_connect = true are discoverable internally:
text
http://isis-generation-api.oshun.local:3000
ECS Exec (Debugging)#
For services with enable_execute_command = true:
bash
aws ecs execute-command \
--cluster oshun-production \
--task <task-id> \
--container isis-generation-api \
--interactive \
--command "/bin/sh"
Outputs#
| Name | Description |
|---|---|
| task_definition_arns | Map of service → task def ARN |
| service_names | Map of service → ECS service name |
| target_group_arns | Map of service → ALB target group |
| log_group_names | Map of service → CloudWatch log |
| service_connect_endpoints | Map of service → internal DNS |
| service_urls | Map of service → external/internal |
| services_summary | Summary of all deployed services |
Domain Configuration Files#
This module supports domain-specific configuration files:
isis.tf- Isis (Generative Factory) servicessophia.tf- Sophia (Research & Knowledge) serviceshathor.tf- Hathor (Worldbuilding) servicesbellona.tf- Bellona (Build Engine) servicesyemaya.tf- Yemaya (Creative Studio) serviceslilith.tf- Lilith (Consciousness) servicescommon.tf- Common services (API Gateway, Auth, etc.)
Each file defines domain-specific service configurations that get merged into the main services variable.
Best Practices#
- Resource Right-Sizing: Start with 256 CPU / 512 MB and scale up as needed
- Health Checks: Use specific health check endpoints that verify dependencies
- Secrets: Never put secrets in environment variables, use Secrets Manager
- Auto-Scaling: Set appropriate min/max based on expected traffic patterns
- Spot Instances: Use FARGATE_SPOT for batch workers, not APIs
- Service Connect: Enable for all services that need internal communication
- Circuit Breaker: Keep enabled for automatic rollback on failed deployments