acdl/docs/environments/index.md

Environments

A consumer does not provide an AWS account, a VPC, a subnet, an S3 state bucket, or a runner key. The platform manages environments.

What an environment is

A named environment is a platform-owned bundle of:

• An AWS account (or a scoped partition of one).
• A network (VPC + subnets).
• A state backend (an S3 bucket + DynamoDB lock table for infrastructure state).
• An IAM role surfaced to the consumer via attribute-based authorization (ABAC), scoped to the consumer's repository identity and resource tags.

A consumer selects an environment by name in their contract:

environment: dev

The platform resolves the name to the underlying account/network/state/role at run time. The consumer never sees the raw credentials.

First-run onboarding

When a consumer pipeline runs for the first time and no environment is defined for the consumer's repo, the platform detects this and emits a user-friendly onboarding prompt instead of failing opaquely. The prompt tells the consumer:

1. That no environment is bound to their repo yet.
2. What the platform will provision on their behalf (account/network/state/ role).
3. The expected turnaround for the platform team to grant the environment.
4. How to request an environment (contact the platform team).

The pipeline then exits without attempting a deployment. Once the platform team binds an environment to the repo, the next pipeline run proceeds normally.

Autonomy by environment

Environment	Autonomy	Gate
dev	Full autonomy	Confidence ≥ 0.50
qa	Held for attestation	QA attestation + confidence ≥ 0.75
prod	Held for attestation	SRE attestation + confidence ≥ 0.90
dr	Held for attestation	SRE attestation + confidence ≥ 0.95 + dr-drill

dev is the only autonomous environment. Higher environments require human attestation (a platform-runner deployment approval) and a higher confidence threshold. Staging does not exist.

Cross-account contract ingestion grant (D-051)

Onboarding now also grants the consumer repo's deploy role permission to invoke the platform Lambda — acdl-contract-ingestor — across accounts. The Lambda is invoked via a Function URL with IAM auth, so the grant is an inline IAM policy applied to the consumer's deploy role. The policy template lives at terraform/platform/consumer_invoke_policy.json and is scoped via ABAC: the condition aws:PrincipalTag/acdl:owner == ${consumerRepo} ensures a repo can only invoke the Lambda when its principal tag matches its claimed identity.

The consumer's deploy workflow signs the Function URL request with SigV4 using its deploy-role credentials; the platform Lambda validates the signature and the ABAC condition before accepting the payload.

This is a one-way channel — the consumer pushes contracts to the platform; the platform never reaches back into the consumer account. It is used for two purposes:

1. Contract ingestion — the consumer submits its resolved deployment contract (action: "submit_contract") so the platform has a durable record in the acdl-contracts DynamoDB table (PK consumerRepo, SK contractId#submittedAt).
2. Error reporting (D-055) — the consumer reports a deployment error (action: "report_error") which the platform turns into a GitHub issue on the platform repo (wired in Phase 25; the Lambda returns a prepared-status stub until then).

The Lambda handler and the Terraform that deploys it live in core/lambda/contract_ingestor.py and terraform/platform/main.tf respectively.

Onboarding scaffold (current state)

The platform repo ships a minimal onboarding scaffold:

• core/environments/ — environment definitions (a sample dev.json).
• core/environment_check.py — checks whether an environment is defined for a given contract's repo + environment name; prints the friendly onboarding prompt when none is defined.
• scripts/run_platform.sh calls the check before contract validation.

The scaffold is minimal: the actual provisioning of a new environment is a platform-team action today. Self-service environment provisioning is on the roadmap.