Jon Chery
2a84c0047b
---ci--- project: acdl phase: 20 milestone: v1.5 status: verify ---/ci--- REQ-46: README rewritten — platform-source vs consumer-repo distinction up front; platform flow converted to mermaid flowchart TD; L3A/L3B + spike nomenclature scrubbed from prose (code paths kept verbatim); prereqs pointer to consumer guide added. REQ-47: docs/CONSUMER_GUIDE.md (generic, all L2 modules) replaces docs/consumer-guide-static-asset.md — mermaid diagrams (model LR + pipeline TD), versioned uses: (@v1.4 floating MAJOR+MINOR, bare/@main discouraged), consumer-scoped prerequisites (no Terraform/Checkov/boto3/runner-key), run- time platform fetch via reusable workflow (consumers never invoke scripts/run_platform.sh locally for the happy path), optional local validation note. REQ-48: Credentials section rewritten — zero-trust OIDC + ABAC default (repo-identity + resource-tag scoping, blast-radius containment); static-key override in GitHub Secrets or .env.secrets with platform-managed daily rotation; consumer rotates out of band when using .env.secrets locally. REQ-49: byte-identical .gitea/workflows/deploy.yml + .github/workflows/ deploy.yml — reusable (on: workflow_call), checks out consumer repo + ACDL platform repo, installs deps, runs run_platform.sh, uploads artifacts; OIDC default (permissions: id-token: write) + static-key override via secrets. REQ-50: contracts/static-asset.yaml uses: @v1.4 (MAJOR+MINOR). REQ-51: tests/test_pipeline_contract.py extended — TestDeployPipelineSchema, TestDeployPipelineContract, TestDeployWorkflowConformance (byte-identical, reusable, contract/mode inputs, run_platform invocation, platform-repo checkout, OIDC permissions), TestSampleContractVersioning. 154 tests pass (19 new); run_ci.sh green. Fixes: modules/l2/static-asset/README.md dangling link retargeted to docs/CONSUMER_GUIDE.md.
ACDL Modules
Reusable building blocks for cloud infrastructure. Each module is
self-documented with a README.md following the
template.
How the modules work
There are two kinds of module:
- L1 primitives — a single cloud resource or a small group of
related resources (e.g. a VPC with subnets and routing). Each L1 has
an
interface.jsondeclaring its inputs and outputs, and aREADME.mdin plain language. - L2 compositions — a composition that references multiple L1s to deploy a complete stack (e.g. an ECS Fargate microservice). The L2 composition layer is being redesigned. The previous implementation has been removed; a new mechanism will be designed in a later phase.
The Terraform adapter (adapters/terraform/adapter.py) compiles a
module instance to Terraform. Each module's README documents which
Terraform resources it creates.
L1 primitives
| Module | What it creates | README |
|---|---|---|
l1-s3 |
aws_s3_bucket — a single S3 bucket |
README |
l1-vpc |
aws_vpc + aws_subnet + aws_route_table + aws_internet_gateway — VPC with subnets and routing |
README |
l1-ecs-cluster |
aws_ecs_cluster — ECS Fargate cluster |
README |
l1-ecs-service |
aws_ecs_task_definition + aws_ecs_service — Fargate service with task definition |
README |
l1-iam-role |
aws_iam_role — IAM role with assume-role policy |
README |
l1-alb |
aws_lb + aws_lb_target_group + aws_lb_listener — Application Load Balancer |
README |
l1-ecr |
aws_ecr_repository — ECR container image repository |
README |
L2 compositions
| Module | What it references | README |
|---|---|---|
l2-microservice |
6 L1s (vpc, cluster, ecr, iam-role, alb, ecs-service) — under redesign | README |
l2-static-asset |
1 L1 (s3) — under redesign | README |
Registry
Module versions are tracked in registry.json. Only L1 entries are
active; L2 entries have been pruned pending the composition redesign.
Template
New modules should use README-TEMPLATE.md as their starting point.