150 lines
6.9 KiB
Markdown
150 lines
6.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.
|
|
|
|
**TL;DR** — Nova Platform turns a small YAML contract into AWS
|
|
infrastructure: declare modules and inputs, and the platform resolves the
|
|
contract, compiles Terraform, and applies it. The last tagged release
|
|
(v0.1.6) predates CoreCI adoption; nothing has shipped under CoreCI yet.
|
|
|
|
**What** —
|
|
- One contract file per deployment: module names and versions,
|
|
environment, and module-specific inputs.
|
|
- The platform resolves the contract to a stack, compiles it through the
|
|
Terraform adapter, and applies it.
|
|
- Offline checks ship in the repo: `bash scripts/run_ci.sh` runs lint,
|
|
tests, and a check-only pass — no AWS required.
|
|
|
|
**Why** — Contract-driven deploys are reproducible and auditable; a
|
|
consumer never writes infrastructure code.
|
|
|
|
**Action** — No action — FYI. Consumers start at
|
|
[`docs/consumer-guide.md`](docs/consumer-guide.md); the product owner is
|
|
coreci-nova-po.
|
|
|
|
**Details** — Design: [`docs/architecture.md`](docs/architecture.md);
|
|
runbook: "How to run" below.
|
|
|
|
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. |