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---
70 lines
2.6 KiB
Markdown
70 lines
2.6 KiB
Markdown
# 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):
|
|
|
|
```yaml
|
|
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:
|
|
|
|
```yaml
|
|
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](../pipeline/versioning). |
|
|
| `module` | string | yes | Module name from the registry — any primitive or module (e.g. `static-assets`, `microservice`, `s3`). See the [module catalog](../modules/). |
|
|
| `environment` | string | yes | The platform-managed environment to deploy to (e.g. `dev`). See [Environments](../environments/). |
|
|
| `inputs` | object | yes | Module-specific inputs (see the module's README). |
|
|
|
|
## Validation
|
|
|
|
The contract is validated against
|
|
[`schemas/contract.schema.json`](https://github.com/acdl/acdl/blob/main/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`](https://github.com/acdl/acdl/blob/main/contracts/static-assets.yaml)
|
|
— the `static-assets` module (uses `@v1.6`).
|
|
- [`contracts/microservice.yaml`](https://github.com/acdl/acdl/blob/main/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](../modules/) 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](../consumer-guide/) for the multi-contract pattern. |