# microservice — ECS Fargate microservice

> **Module kind:** module pattern  |  **Version:** 1.0.0

A pattern that references multiple primitives to deploy an ECS
Fargate microservice end-to-end (VPC, cluster, ECR, IAM role, ALB,
ECS service).

## Resources

The pattern references these primitives:

| Primitive | Purpose | README |
|-----------|---------|--------|
| `vpc` | VPC, subnets, routing | [README](../l1/vpc/README.md) |
| `ecs-cluster` | ECS Fargate cluster | [README](../l1/ecs-cluster/README.md) |
| `ecr` | ECR image repository | [README](../l1/ecr/README.md) |
| `iam-role` | IAM task execution role | [README](../l1/iam-role/README.md) |
| `alb` | Application Load Balancer | [README](../l1/alb/README.md) |
| `ecs-service` | ECS task definition + service | [README](../l1/ecs-service/README.md) |

## Inputs

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `image` | string | yes | ECR image URL for the task container |
| `port` | number | yes | Container port the service listens on |
| `region` | string | yes | AWS region |
| `cidr` | string | no | VPC CIDR block (default 10.0.0.0/16) |
| `azs` | string | no | Comma-separated availability zones |

## Outputs

| Name | Type | Description |
|------|------|-------------|
| `lb_arn` | arn | The load balancer ARN |
| `service_arn` | arn | The ECS service ARN |

## Usage

Define a contract referencing this module:

```yaml
uses: acdl/pipelines/deploy.yaml@v1.6
module: microservice
environment: dev
inputs:
  image: 581513795199.dkr.ecr.us-east-1.amazonaws.com/acdl-microservice:latest
  port: 8080
  region: us-east-1
```

## Compliance extension points

The pattern can wire compliance resources across primitives when the
compliance milestone (GDPR, SOX, SOC2, HIPAA, DORA) lands:

- **KMS key** — shared encryption key referenced by S3, ECR, CloudWatch Logs, and Secrets Manager.
- **CloudTrail** — management-plane audit trail for the entire stack.
- **VPC Flow Logs** — network audit trail.
- **Security groups** — proper network segmentation between ALB, service, and data tiers.
- **Private subnets** — ECS tasks in private subnets with NAT egress.

See each primitive's README for per-module compliance extension points.

## Examples

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

### Simple

A minimal deployment (minimal Fargate, no ALB):

[`examples/simple.yaml`](examples/simple.yaml)
```yaml
# Simple microservice deployment (minimal Fargate, no ALB)
uses: acdl/pipelines/deploy.yaml@v1.6
module: microservice
environment: dev
inputs:
  bucket_name: my-microservice-demo
  region: us-east-1
  image: public.ecr.aws/docker/library/nginx:latest
  port: 80
```

### Complex

A production deployment with optional inputs (ALB + env vars + health check):

[`examples/complex.yaml`](examples/complex.yaml)
```yaml
# Complex microservice with ALB + env vars + health check
uses: acdl/pipelines/deploy.yaml@v1.6
module: microservice
environment: dev
inputs:
  bucket_name: my-production-microservice
  region: us-east-1
  image: public.ecr.aws/docker/library/nginx:latest
  port: 8080
  env:
    LOG_LEVEL: info
    ENVIRONMENT: production
```

## 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.