Files

T

Jon Chery f3b7815120 docs(P27): update docs + README for RDS primitive + module examples

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

2026-07-22 20:24:36 +00:00

2.6 KiB

Raw Blame History

Contracts

A consumer declares intent in a contract — a small YAML file that references the central deploy pipeline, names a module, selects an environment, and supplies module-specific inputs. The platform validates, resolves, and deploys it.

The contract file

A consumer repo keeps its contract at .acdl/contract.yaml. A minimal example (the static-assets module):

uses: acdl/pipelines/deploy.yaml@v1.6
module: static-assets
environment: dev
inputs:
  bucket_name: my-static-site-assets
  region: us-east-1

A microservice example:

uses: acdl/pipelines/deploy.yaml@v1.6
module: microservice
environment: dev
inputs:
  image: my-registry/my-microservice:latest
  port: 8080
  env:
    LOG_LEVEL: info

Fields

Field	Type	Required	Description
`uses`	string	yes	Reference to the central deploy pipeline, versioned with a floating MAJOR+MINOR tag (e.g. `acdl/pipelines/deploy.yaml@v1.6`). Bare or `@main` references are discouraged. See Versioning.
`module`	string	yes	Module name from the registry — any primitive or module (e.g. `static-assets`, `microservice`, `s3`). See the module catalog.
`environment`	string	yes	The platform-managed environment to deploy to (e.g. `dev`). See Environments.
`inputs`	object	yes	Module-specific inputs (see the module's README).

Validation

The contract is validated against schemas/contract.schema.json. An invalid contract (missing field, unknown module, wrong type) fails at the validate-contract stage with a clear error.

Sample contracts

Two reference examples exist in contracts/:

contracts/static-assets.yaml — the static-assets module (uses @v1.6).
contracts/microservice.yaml — the microservice module (uses @v1.6).

Additionally, every module has a modules/<name>/examples/ directory with validated example contracts (simple.yaml + complex.yaml + variation files). See the module catalog for the full list.

Multiple contracts

A consumer repo may contain more than one contract (e.g. one per service or one per environment). Each contract is a separate deployment; each is referenced by a CI definition in .github/workflows/ that invokes the central reusable workflow with the contract path. See the Consumer Guide for the multi-contract pattern.

2.6 KiB Raw Blame History