Jon Chery
41c3377b96
--- ci--- project: acdl phase: 67b milestone: v1.12 status: execute --- /ci--- The modules-lifecycle pipeline now defaults to plan-only (fast, no AWS mutation, no credentials, no cost) so it runs on every PR. A CI variable ACDL_LIFECYCLE_MODE (workflow_dispatch input 'lifecycle_mode', default 'plan') overrides to 'full' for the real apply->modify->destroy against live AWS. Scripts: run_lifecycle_test.sh / run_lifecycle_destroy.sh / run_l2_lifecycle_test.sh / run_l2_lifecycle_destroy.sh read the flag and dispatch to --plan-only (plan mode) or --apply/--destroy (full mode). Destroy is a no-op exit 0 in plan mode (nothing was applied). VPC-output injection is gated on full mode. Workflows: both .github + .gitea (byte-identical) expose lifecycle_mode as a workflow_dispatch input (choice: plan/full), pass it via env: ACDL_LIFECYCLE_MODE to every lifecycle step, skip ci-vpc-apply + ci-vpc-destroy + Read-CI-VPC-outputs in plan mode, and run the lifecycle + l2-lifecycle jobs with if: always() so they execute (plan-only) even when ci-vpc-apply is skipped. Contract + schema: pipelines/modules-lifecycle.yml gains default_mode: plan; the schema accepts default_mode (enum plan|full) and a richer workflow_dispatch inputs shape. Tests: 14 new tests in test_lifecycle_mode_flag.py (script dispatch) + 10 new tests in TestModulesLifecyclePipeline (workflow flag wiring, byte-identity, plan-mode skips). Updated test_platform_vpc_destroy to reflect the plan-mode skip. 516 tests pass; smoke-tested plan mode on the s3 module (--plan-only green, no AWS apply).
ACDL Schemas
Overview
ACDL uses JSON Schema draft 2020-12 for all declarative contracts. Schemas are the single source of truth for validation. Every contract, stack instance, pipeline, and policy result in the platform is validated against a schema in this directory before it is consumed by any downstream code path. The resolver, the pipeline runner, the CI workflows, and the test suite all load these schemas directly.
Existing Schemas
| Schema | File | Purpose | Where Validated |
|---|---|---|---|
| ACDL Consumer Contract | contract.schema.json |
Consumer contract validation (id, name, environment, infrastructure map with module versions + inputs) | core/contract_resolver.py, scripts/run_platform.sh Step 1, CI schema-validation job |
| ACDL Target Stack | stack.schema.json |
Target Stack instance validation (resources, relationships, composition tree, NFRs) | core/contract_resolver.py (post-resolution), tests/conftest.py |
| ACDL Central Pipeline Contract | pipeline.schema.json |
Central CI pipeline contract (stages, commands, triggers, runner) | tests/test_pipeline_contract.py |
| ACDL Central Deployment Pipeline Contract | deploy-pipeline.schema.json |
Central deploy pipeline contract (validate → resolve → plan → checkov → confidence → apply → publish → uptime → comment) | tests/test_pipeline_contract.py |
| ACDL PolicyCheckResult | policy_check_result.schema.json |
Normalized policy check result schema (the contract between policy engines and the confidence signal) | tests/conftest.py, all adapter tests |
| ACDL Tagging Standard | tagging-standard.json |
Required tag set for all taggable AWS resources | adapters/terraform/policy/custom_rules/acdl_tagging.py |
How to Write a Schema
- Use JSON Schema draft 2020-12:
"$schema": "https://json-schema.org/draft/2020-12/schema". - Set
$idtohttps://acdl.cloudinit.dev/schemas/<name>.schema.json. - Include
titleanddescriptionat the document root. - Set
type: objectat the document root. - Declare a
requiredarray listing the mandatory top-level property names. - Define
propertieswith explicittype,pattern,enum, anddescriptionfor every field. - Use
$defsfor reusable sub-schemas (e.g. resource definitions, input maps) and$refthem from the main document.
How to Wire a Schema into the Platform
- Contract validation — load the schema in
core/contract_resolver.pyand inscripts/run_platform.shStep 1 (validate-contract). - Stack validation — load the schema in
core/contract_resolver.pyafter the contract is resolved to a stack instance. - Pipeline validation — load the schema in
tests/test_pipeline_contract.py, which validatespipelines/ci.ymlandpipelines/contract.yml. - Module interface validation — structural checks in
.github/workflows/platform-test.yml(schema-validationjob) that validate each module'sinterface.json/composition.json. - Policy result validation — the schema is loaded as a fixture in
tests/conftest.pyand reused by every adapter test to validate emittedPolicyCheckResultrecords.
Dependencies
jsonschema(Python) — installed viarequirements-test.txt.pyyaml— for YAML contract loading (core/contract_resolver.py,scripts/run_platform.sh, tests).
How to Test Schemas in CI
tests/test_pipeline_contract.py— validates the pipeline schemas and asserts workflow conformance (byte-identical Gitea/GitHub workflows, same stages/commands/triggers).tests/conftest.py— providesstack_schemaandpolicy_check_result_schemafixtures for reuse across the test suite..github/workflows/platform-test.ymlschema-validationjob — self-validates every schema inschemas/(each schema is loaded and meta-validated), validates module interfaces, and validates example contracts.
Where to Write Tests
tests/test_<schema_name>.pyfor schema-specific tests (e.g.tests/test_contract_schema.py).- Extend
tests/test_pipeline_contract.pyfor pipeline-schema changes. - Module interface validation lives in the CI workflow (
.github/workflows/platform-test.yml).
Adding a New Schema
- Create
schemas/<name>.schema.jsonusing the draft 2020-12 conventions above. - Add it to the CI validation glob in
.github/workflows/platform-test.yml(schema-validationjob). - Write a test in
tests/test_<name>.pythat loads the schema and validates representative valid/invalid documents. - Wire it into the consuming code path (resolver, script, or test) so it is enforced at runtime.