Jon Chery
eb7634da28
v1.15-Nova rebrand doc verification (phase/05-final-review-ship) found stale ACDL references where the code/terraform already uses Nova names. Critical drift fixed (doc said old name; code uses new): - README.md: `.acdl/contract.yml` -> `.nova/contract.yml`; `acdl-spike-runner` -> `nova-spike-runner`; ABAC tag keys `acdl:owner|contract` -> `nova:owner|contract`. - docs/environments/index.md: `acdl-contract-ingestor` -> `nova-contract-ingestor`; `aws:PrincipalTag/acdl:owner` -> `nova:owner`; `acdl-contracts` -> `nova-contracts`. - docs/consumer-guide.md: `acdl-change-requests` -> `nova-change-requests`; state bucket example `acdl-qa-state` -> `nova-qa-state`. - docs/presentations/* (4 decks + 2 HTML + talking-points): `acdl:owner|contract| environment|cost-center` -> `nova:*`; `ACDL_LIFECYCLE_MODE` -> `NOVA_LIFECYCLE_MODE`. - pipelines/modules-lifecycle.yml comments: `ACDL_LIFECYCLE_MODE` -> `NOVA_LIFECYCLE_MODE` (workflows already use NOVA_; the contract comments were stale). - docs/NOVA_MIGRATION.md: status banner -> COMPLETE (P5 cutoff passed). - .ciagent/ARCHITECTURE.md: header `ACDL` -> `Nova`; NOVA_LIFECYCLE_MODE rename noted in the live lifecycle-mode section (v1.15 addendum already correct). - .ciagent/ROADMAP.md: v1.15 phase statuses P1-P4 pending -> complete (v1.15.1..v1.15.4); P5 -> in progress (phase/05-final-review-ship). Verification: - grep for `acdl:*` tag keys / `.acdl/contract` / `acdl-contract-ingestor` / `acdl-contracts` / `ACDL_LIFECYCLE_MODE` in README/docs/pipelines -> 0 hits (excluding explicitly-unchanged repo path `acdl/.github/...`, `continuous-intelligence/acdl`, and historical narrative). - core/output_publisher.py uses `/nova`; schemas/tagging-standard.json uses `nova:*`; terraform uses `nova-*` (0 `acdl-` in *.tf) — docs now match. - git tag v1.15.0..v1.15.4 exist. - pytest tests/test_lifecycle_mode_flag.py tests/test_pipeline_contract.py -> 111 passed. ---ci--- project: acdl
104 lines
4.4 KiB
Markdown
104 lines
4.4 KiB
Markdown
# 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:
|
|
|
|
```yaml
|
|
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** — `nova-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`](https://github.com/nova/nova/blob/main/terraform/platform/consumer_invoke_policy.json)
|
|
and is scoped via **ABAC**: the condition
|
|
`aws:PrincipalTag/nova: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 `nova-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`](https://github.com/nova/nova/blob/main/core/lambda/contract_ingestor.py)
|
|
and
|
|
[`terraform/platform/main.tf`](https://github.com/nova/nova/blob/main/terraform/platform/main.tf)
|
|
respectively.
|
|
|
|
## Onboarding scaffold (current state)
|
|
|
|
The platform repo ships a minimal onboarding scaffold:
|
|
|
|
- [`core/environments/`](https://github.com/nova/nova/blob/main/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](../). |