Eve library

Oshun ECS Services Module

Other

Revision 1

On this page

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) services
  • sophia.tf - Sophia (Research & Knowledge) services
  • hathor.tf - Hathor (Worldbuilding) services
  • bellona.tf - Bellona (Build Engine) services
  • yemaya.tf - Yemaya (Creative Studio) services
  • lilith.tf - Lilith (Consciousness) services
  • common.tf - Common services (API Gateway, Auth, etc.)

Each file defines domain-specific service configurations that get merged into the main services variable.

Best Practices#

  1. Resource Right-Sizing: Start with 256 CPU / 512 MB and scale up as needed
  2. Health Checks: Use specific health check endpoints that verify dependencies
  3. Secrets: Never put secrets in environment variables, use Secrets Manager
  4. Auto-Scaling: Set appropriate min/max based on expected traffic patterns
  5. Spot Instances: Use FARGATE_SPOT for batch workers, not APIs
  6. Service Connect: Enable for all services that need internal communication
  7. Circuit Breaker: Keep enabled for automatic rollback on failed deployments