CIAgent
2443909362
---ci--- project: nova-platform milestone: v1.0 status: complete requirements: covered: [REQ-01,REQ-02,REQ-03,REQ-04,REQ-05,REQ-06,REQ-07,REQ-08,REQ-09,REQ-10,REQ-11,REQ-12,REQ-13,REQ-14,REQ-15,REQ-16,REQ-17,REQ-18,REQ-19,REQ-20,REQ-21,REQ-22,REQ-23,REQ-24,REQ-25,REQ-26,REQ-27,REQ-28,REQ-29,REQ-30,REQ-31,REQ-32,REQ-33,REQ-34,REQ-35,REQ-36,REQ-37,REQ-38] partial: [] ---/ci--- v1.0 milestone complete: simplified infrastructure-delivery platform derived from Nova (acdl). 6 phases (P0-P5 + P6 final). 38 REQ-IDs. 38 decisions (D-001..D-038). 76 tests pass. Engine boundary holds. Happy paths green (check-only + CI). 13 L1 + 2 L2 modules. 5 terraform roots. Shell reproducibility. Zero OOS files. Tags: v0.1.0 (P0) → v0.1.1..v0.1.5 (P1..P5) → v0.1.6 (P6 = milestone release on v0.1 patch line).
127 lines
5.9 KiB
Markdown
127 lines
5.9 KiB
Markdown
# Nova Platform
|
|
|
|
> Nova Platform — infrastructure delivery, simplified. A consumer declares
|
|
> intent in a YAML contract; the platform resolves it to a stack, compiles
|
|
> it through the Terraform adapter, and applies it. Every deployment is
|
|
> reproducible from the shell, not just in CI.
|
|
|
|
Nova Platform is the **infrastructure-delivery core** of the Nova model.
|
|
The DevSecOps, identity, audit-ledger, and central CI-pipeline-contract
|
|
machinery of the reference are intentionally removed. What remains: a
|
|
consumer writes a small YAML contract that names one or more modules by
|
|
name + version, selects an environment, and supplies module-specific
|
|
inputs. The platform resolves the contract to a stack instance, compiles
|
|
it through the Terraform adapter, and applies it.
|
|
|
|
- **Consumer guide:** [`docs/consumer-guide.md`](docs/consumer-guide.md)
|
|
- **Contracts:** [`docs/contracts/`](docs/contracts/index.md)
|
|
- **Environments:** [`docs/environments/`](docs/environments/index.md)
|
|
- **Architecture:** [`docs/architecture.md`](docs/architecture.md)
|
|
- **Modules:** [`docs/modules/`](docs/modules/index.md)
|
|
|
|
## How to run
|
|
|
|
### Quick start (offline, no AWS required)
|
|
|
|
The fastest way to verify the platform works — no AWS credentials, no
|
|
bootstrap, no cost.
|
|
|
|
```bash
|
|
# Install test dependencies
|
|
pip install -r requirements-test.txt
|
|
|
|
# 1. Run the test suite (all offline)
|
|
python3 -m pytest tests/ -q
|
|
|
|
# 2. Run the platform in check-only mode (offline — contract -> resolve ->
|
|
# adapter -> structure validation). Uses the default sample contract.
|
|
bash scripts/run_platform.sh --check-only contracts/static-assets.yml
|
|
# Expected: "=== PLATFORM CHECK OK ==="
|
|
|
|
# 3. Reproduce the full CI pipeline locally (lint -> test -> check-only)
|
|
bash scripts/run_ci.sh
|
|
# Expected: "=== CI PIPELINE OK ==="
|
|
|
|
# Show all run_platform.sh flags:
|
|
bash scripts/run_platform.sh --help
|
|
```
|
|
|
|
### Run against live AWS (requires credentials + bootstrap)
|
|
|
|
> Prerequisites: a platform-managed environment (see
|
|
> [docs/environments/](docs/environments/index.md); `core/environments/dev.json`
|
|
> is the sample), AWS credentials for dev (in `.ciagent/.env.secrets`,
|
|
> gitignored; see [Credentials](#credentials)), `terraform` (pin `>= 1.9, < 1.10`),
|
|
> `python3` + `boto3` + `jsonschema` + `pyyaml`.
|
|
|
|
```bash
|
|
# 1. Bootstrap the AWS state backend + runner IAM user (one-time, idempotent)
|
|
# See terraform/bootstrap/README.md for the full runbook.
|
|
export NOVA_BOOTSTRAP_AWS_ACCESS_KEY_ID="<root key>"
|
|
export NOVA_BOOTSTRAP_AWS_SECRET_ACCESS_KEY="<root secret>"
|
|
export AWS_DEFAULT_REGION="us-east-1"
|
|
python3 terraform/bootstrap/create_state_backend.py
|
|
python3 terraform/bootstrap/create_iam_user.py # prints the initial key
|
|
bash scripts/rotate_spike_key.sh # writes .ciagent/.env.secrets
|
|
|
|
# 2. Run the full platform pipeline (contract -> environment check -> stack ->
|
|
# adapter -> terraform init/validate/plan -> apply).
|
|
bash scripts/run_platform.sh contracts/microservice.yml
|
|
# Expected: "=== PLATFORM APPLY OK ==="
|
|
|
|
# Or plan-only (contract -> stack -> adapter -> terraform plan; no apply):
|
|
bash scripts/run_platform.sh --plan-only contracts/static-assets.yml
|
|
|
|
# Add --quiet to suppress streaming (output to log files only):
|
|
bash scripts/run_platform.sh --quiet contracts/static-assets.yml
|
|
```
|
|
|
|
### run_platform.sh flags (D-031)
|
|
|
|
| Flag | Mode | AWS required | Description |
|
|
|------|------|--------------|-------------|
|
|
| `--check-only` | offline | no | contract → resolve → adapter → structure validation |
|
|
| `--plan-only` | AWS | yes | above + `terraform init`/`validate`/`plan` (no apply) |
|
|
| `--quiet` | any | — | suppress streaming output |
|
|
| `-h`, `--help` | — | — | show usage |
|
|
| *(none)* | apply | yes | full path: above + `terraform apply -auto-approve` |
|
|
|
|
## Repository layout
|
|
|
|
| Path | Purpose | Status |
|
|
|------|---------|--------|
|
|
| `core/` | Platform code: contract resolver, environment check, environments | active |
|
|
| `schemas/` | JSON Schemas (draft 2020-12): contract, stack, environment | active |
|
|
| `adapters/terraform/` | The Terraform adapter — the only engine-specific code | active |
|
|
| `terraform/` | State backend (S3 + DynamoDB) + bootstrap scripts + platform/onboarding/ci-vpc | active |
|
|
| `modules/` | L1 primitives (13) + L2 patterns (2) + `registry.json`. Each module has `interface.json` + `terraform/` | active |
|
|
| `contracts/` | Sample consumer contracts (`static-assets.yml`, `microservice.yml`) + per-env variants | active |
|
|
| `scripts/` | `run_platform.sh` (pipeline runner), `run_ci.sh` (local CI mirror), `rotate_spike_key.sh` | active |
|
|
| `tests/` | Pytest suite (all offline — resolver, adapter, schemas, engine boundary, environment check) | active |
|
|
| `docs/` | Documentation: consumer guide, contracts, environments, architecture, modules | active |
|
|
| `.ciagent/` | CIAgent config + locked decisions (`ARCHITECTURE.md`, `PROJECT.md`, `CLARIFY.md`) | active |
|
|
|
|
## Credentials
|
|
|
|
Nova Platform uses a **static AWS key** for dev/local operation. There is no
|
|
zero-trust federation layer in v1.0 — that is out of scope.
|
|
|
|
- The runner key is stored in **`.ciagent/.env.secrets`** (gitignored,
|
|
`chmod 600`) using the `NOVA_AWS_*` prefix (D-032):
|
|
`NOVA_AWS_ACCESS_KEY_ID`, `NOVA_AWS_SECRET_ACCESS_KEY`.
|
|
- `scripts/run_platform.sh` copies `NOVA_AWS_*` to the standard `AWS_*`
|
|
env vars before invoking Terraform, then unsets the `NOVA_*` copies.
|
|
- Bootstrap uses a one-shot root key via `NOVA_BOOTSTRAP_AWS_*` env vars
|
|
(never committed, never echoed). See
|
|
[`terraform/bootstrap/README.md`](terraform/bootstrap/README.md) for the
|
|
full bootstrap runbook (state backend + runner IAM user + key rotation).
|
|
- Onboarding creates a per-consumer IAM **role** (cross-account assume-role
|
|
pattern, D-025) — not a user, not federation. See
|
|
`terraform/onboarding/main.tf`.
|
|
|
|
## Consumer guide
|
|
|
|
A step-by-step guide for a consumer to create a repo, write a contract,
|
|
validate it offline, and run it against AWS is at
|
|
[`docs/consumer-guide.md`](docs/consumer-guide.md). The guide is generic
|
|
across all modules; `static-assets` is the worked example. |