Jon Chery
f3b7815120
- docs/modules/index.md: add rds primitive row + Examples section - docs/consumer-guide.md: reference examples/ directory + microservice sample - docs/contracts/index.md: reference both sample contracts + module examples - README.md: add rds to primitives list, note examples/ dirs, update contracts row ---ci--- project: acdl phase: 27 milestone: v1.7 status: execute ---/ci---
4.1 KiB
Modules
Reusable building blocks for cloud infrastructure. There are two kinds:
- Primitives — a single cloud resource or a small group of related
resources (e.g. a VPC with subnets and routing). Each primitive has an
interface.jsondeclaring its inputs and outputs. - Modules — a pattern that references multiple primitives to deploy a
complete stack (e.g. an ECS Fargate microservice). Each module has a
composition.jsondeclaring its children and wires.
The substrate adapter compiles a module instance to infrastructure. Each module's README documents which resources it creates.
Primitives
| Module | What it creates | Source |
|---|---|---|
s3 |
aws_s3_bucket — a single S3 bucket |
modules/l1/s3/README.md |
vpc |
aws_vpc + aws_subnet + aws_route_table + aws_internet_gateway — VPC with subnets and routing |
modules/l1/vpc/README.md |
ecs-cluster |
aws_ecs_cluster — ECS Fargate cluster |
modules/l1/ecs-cluster/README.md |
ecs-service |
aws_ecs_task_definition + aws_ecs_service — Fargate service with task definition |
modules/l1/ecs-service/README.md |
iam-role |
aws_iam_role — IAM role with assume-role policy |
modules/l1/iam-role/README.md |
alb |
aws_lb + aws_lb_target_group + aws_lb_listener — Application Load Balancer |
modules/l1/alb/README.md |
ecr |
aws_ecr_repository — ECR container image repository |
modules/l1/ecr/README.md |
cloudfront |
aws_cloudfront_distribution + aws_cloudfront_origin_access_control — CloudFront distribution with S3 origin via OAC |
modules/l1/cloudfront/README.md |
waf |
aws_wafv2_web_acl — WAFv2 Web ACL (CloudFront-scoped) |
modules/l1/waf/README.md |
rds |
aws_db_instance — RDS database instance (multi-engine: postgres, mysql, etc.) |
modules/l1/rds/README.md |
Modules
| Module | What it references | Source |
|---|---|---|
static-assets |
3 primitives (s3, cloudfront, waf) — a production static asset stack | modules/l2/static-assets/README.md |
microservice |
6 primitives (vpc, cluster, ecr, iam-role, alb, ecs-service) — an ECS Fargate microservice | modules/l2/microservice/README.md |
Registry
Module versions are tracked in
registry.json.
Both primitives and modules are registered.
Examples
Each module has a examples/ directory containing validated consumer
contract examples (simple.yaml + complex.yaml + variation files). The
platform-test pipeline validates them against
schemas/contract.schema.json.
See each module's ## Examples section for the excerpts.
Versioning
Primitives and modules use semver: interface → MAJOR, behavior → MINOR, lifecycle → PATCH. A MAJOR bump requires a new registry entry (immutable publication); the old entry enters a 12-month deprecation window. See Versioning for the deploy-pipeline versioning.
Module patterns (roadmap)
The current composition.json mechanism is a thin pattern layer. A future
redesign will let a consumer dynamically create a module directly from the
contract file (an agentic "composition" flow). That is on the roadmap, not
implemented today.