Jon Chery
031887ec56
Contract surface redesign: - New top-level fields: id (3-6 char acronym → stack.name), name (full → stack.title), infrastructure (map keyed by module name, replaces module:) - Drop uses: field (dead reference; version pin lives in CI workflow uses: line) - Drop top-level module/inputs (now nested under infrastructure map) - Per-module optional version (defaults to latest published from registry) - Multi-module contracts: one file deploys N modules in one pipeline run, resource IDs namespaced with module name to avoid collisions - stack.schema.json: add optional title field for display name Rename: - pipelines/deploy.yaml → pipelines/contract.yml (declarative spec, not a pipeline) - pipelines/ci.yaml → pipelines/ci.yml - All 44 .yaml files → .yml repo-wide (contracts, module examples, kyverno policies) - .acdl/contract.yaml → .acdl/contract.yml Resolver (core/contract_resolver.py): - Rewrite resolve() to loop infrastructure map, default version to latest, merge module fragments into one stack with namespaced resource IDs - _latest_version() picks highest non-deprecated from registry - _namespace_resources() prefixes IDs + rewrites ref: expressions for multi-module - Single-module path: unprefixed IDs (backward compatible) Verification: - 494 tests pass (0 contract-shape failures) - Local E2E passes (contract → resolver → adapter → local ECS HTTP 200 → outbox) ---ci--- project: acdl phase: 57 milestone: v1.10.2 status: execute ---/ci---
119 lines
3.4 KiB
Markdown
119 lines
3.4 KiB
Markdown
# 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
|
|
environment: dev
|
|
id: msvc
|
|
infrastructure:
|
|
microservice:
|
|
inputs:
|
|
image: 581513795199.dkr.ecr.us-east-1.amazonaws.com/acdl-microservice:latest
|
|
port: 8080
|
|
region: us-east-1
|
|
version: 1.0.0
|
|
name: microservice
|
|
```
|
|
|
|
## Compliance extension points
|
|
|
|
The pattern can wire compliance resources across primitives when the
|
|
compliance milestone (GDPR, SOX, SOC2, 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.yml`](examples/simple.yml)
|
|
```yaml
|
|
environment: dev
|
|
id: msvc
|
|
infrastructure:
|
|
microservice:
|
|
inputs:
|
|
bucket_name: my-microservice-demo
|
|
image: public.ecr.aws/docker/library/nginx:latest
|
|
port: 80
|
|
region: us-east-1
|
|
version: 1.0.0
|
|
name: microservice
|
|
```
|
|
|
|
### Complex
|
|
|
|
A production deployment with optional inputs (ALB + env vars + health check):
|
|
|
|
[`examples/complex.yml`](examples/complex.yml)
|
|
```yaml
|
|
environment: dev
|
|
id: msvc
|
|
infrastructure:
|
|
microservice:
|
|
inputs:
|
|
bucket_name: my-production-microservice
|
|
env:
|
|
ENVIRONMENT: production
|
|
LOG_LEVEL: info
|
|
image: public.ecr.aws/docker/library/nginx:latest
|
|
port: 8080
|
|
region: us-east-1
|
|
version: 1.0.0
|
|
name: microservice
|
|
```
|
|
|
|
## 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. |