acdl/modules/l1/alb/README.md

alb — Application Load Balancer (load balancer + target group + listener)

Module kind: primitive | Version: 1.0.0

An Application Load Balancer with a target group and a listener. This is a multi-resource module: it creates a load balancer, a target group, and a listener that forwards traffic to the target group. The target group is what ecs-service registers its tasks with.

Resources

Resource	Type	Purpose
load_balancer	aws_lb	Application load balancer in the VPC subnets
target_group	aws_lb_target_group	Target group for the ECS service tasks
listener	aws_lb_listener	Listener forwarding the LB port to the target group

Inputs

Name	Type	Required	Default	Description
name	string	yes	—	Name tag for the load balancer and child resources
subnets	string	yes	—	Comma-separated subnet ids (from vpc)
security_group	string	yes	—	Security group id for the load balancer
port	number	no	80	Listener port
protocol	string	no	HTTP	Listener protocol
region	string	yes	—	AWS region the load balancer is created in

Outputs

Name	Type	Description
lb_arn	arn	The load balancer ARN
listener_arn	arn	The listener ARN
target_group_arn	arn	The target group ARN

Usage

{
  "id": "alb",
  "type": "aws:elbv2:loadbalancer",
  "module": "alb@1.0.0",
  "inputs": {
    "name": "acdl-microservice",
    "subnets": "ref:vpc.subnet_ids",
    "security_group": "ref:roles.role_arn",
    "port": 8080,
    "protocol": "HTTP",
    "region": "us-east-1"
  }
}

The target_group_arn output is referenced by ecs-service as its lb_target_group_arn input to wire the service to the ALB.

Compliance extension points

• TLS / HTTPS listener — add aws_acm_certificate + ssl_policy + certificate_arn for encryption in transit (SOC2 CC6.1, PCI-DSS 4.1, GDPR Art.32).
• Access logs — add access_logs { bucket = ..., prefix = ... } to the load balancer (SOX, SOC2 CC7.2, DORA ICT audit trail).
• Security group rules — add ingress/egress rules restricting traffic to known sources (SOC2 CC6.6, PCI-DSS 1.2).
• Health check — add a health_check block to the target group (SOC2 CC7.3 monitoring, DORA operational resilience).
• WAF — add aws_wafv2_web_acl_association for application-layer protection (SOC2 CC7.6, PCI-DSS 6.5, DORA ICT risk).
• Deregistration delay — add deregistration_delay for graceful draining (SOC2 CC9.1 resilience).

Examples

Validated example contracts are in examples/. The platform-test pipeline validates them against schemas/contract.schema.json.

Simple

A minimal deployment:

examples/simple.yaml

uses: acdl/pipelines/deploy.yaml@v1.6
module: alb
environment: dev
inputs:
  name: my-alb
  subnets: subnet-aaa,subnet-bbb
  security_group: sg-xxx
  port: 80
  protocol: HTTP
  region: us-east-1

Complex

A production deployment with optional inputs:

examples/complex.yaml

# Complex ALB with HTTPS + ACM cert (requires a consumer-supplied domain)
uses: acdl/pipelines/deploy.yaml@v1.6
module: alb
environment: dev
inputs:
  name: my-production-alb
  subnets: subnet-aaa,subnet-bbb
  security_group: sg-xxx
  port: 443
  protocol: HTTPS
  region: us-east-1

Versioning

1.0.0 — interface MAJOR, behavior MINOR, lifecycle PATCH. MAJOR bumps require a new registry entry (immutable publication); old entries enter a 12-month deprecation window.