nova-platform/docs/environments/index.md

Environments

A consumer does not provide an AWS account, a VPC, a subnet, or an S3 state bucket. 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 / AZs).
• A state backend (an S3 bucket + DynamoDB lock table for Terraform state).

A consumer selects an environment by name in their contract:

environment: dev

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

Environment definition shape (D-018)

Each environment is a JSON file in core/environments/. The field set is reduced from the reference — the IAM role, autonomy, and confidence threshold fields are out of scope for v1.0.

core/environments/dev.json (the sample):

{
  "name": "dev",
  "description": "Sample dev environment for offline/local testing. account_id placeholder (000000000000) for offline mode.",
  "account_id": "000000000000",
  "region": "us-east-1",
  "state_backend": {
    "bucket": "nova-tfstate-dev-us-east-1",
    "lock_table": "nova-tfstate-locks"
  },
  "network": {
    "vpc_cidr": "10.0.0.0/16",
    "azs": ["us-east-1a", "us-east-1b"]
  }
}

Fields

Field	Type	Required	Description
name	string	yes	The environment name (dev/qa/prod/dr).
description	string	no	Human-readable description.
account_id	string	yes	The AWS account id (placeholder 000000000000 for offline dev).
region	string	yes	The AWS region.
state_backend.bucket	string	yes	The S3 state bucket name.
state_backend.lock_table	string	yes	The DynamoDB lock table name (nova-tfstate-locks per D-022).
network.vpc_cidr	string	yes	The VPC CIDR block.
network.azs	array	yes	The availability zones.

Dropped from the reference (D-018)

• runner_role_arn — identity/authorization is out of scope.
• autonomy — human-in-the-loop gates are out of scope.
• confidence_threshold — the confidence signal is out of scope.

State backend (D-022)

The Terraform state backend uses a dedicated DynamoDB lock table named nova-tfstate-locks (NOT nova-outbox — the audit outbox is out of scope for v1.0). The S3 state bucket is named nova-tfstate-<account>-<region> with versioning enabled. See terraform/bootstrap/README.md for the bootstrap runbook that creates both.

Autonomy by environment

Environment	Autonomy	Operator action
dev	Fully autonomous	None — terraform apply -auto-approve runs automatically.
qa	Manual	An operator runs run_platform.sh against the qa contract.
prod	Manual	An operator runs run_platform.sh against the prod contract.
dr	Manual	An operator runs run_platform.sh against the dr contract.

dev is the only autonomous environment. Higher environments require a human operator to invoke the pipeline against the environment's contract variant. There are no automated gates or attestation steps — those are out of scope for v1.0. Staging does not exist.

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 environment name; raises EnvironmentNotFoundError when none is defined (D-019).
• scripts/run_platform.sh calls the check before contract validation.

The scaffold is minimal: provisioning a new environment is a platform-team action today (bootstrap the state backend + network). Self-service environment provisioning is a future milestone.