Jon Chery
51c3edf458
SSM path /acdl/{env}/{contractId}/{output} → /nova/... across
core/output_publisher + contract resolver + consumer docs. New
scripts/migrate_ssm_paths.py (copy/verify/delete, dry-run default).
AWS tag keys acdl:owner|environment|contract|cost-center|ref → nova:*
across terraform tagging + ABAC session policies (iam:ResourceTag/acdl:*
→ iam:ResourceTag/nova:*). nova_tagging.py hard mode (D-109 warn→hard).
tagging-standard.json tag-key values → nova:*. New
scripts/untag_acdl_keys.py (remove old acdl:* tags, dry-run default).
Test fixtures updated; pytest + run_ci.sh PASS.
---ci---
project: acdl
phase: 3
milestone: v1.15
status: execute
---/ci---
176 lines
9.3 KiB
Markdown
176 lines
9.3 KiB
Markdown
# Nova Migration Guide — What Consumers Must Know
|
||
|
||
> **Nova** is the new product brand for the platform formerly known as
|
||
> **ACDL** (Agentic Cloud Delivery Platform). This guide announces the
|
||
> scheduled breaking changes coming in the rebrand rollout (Phases P2–P4)
|
||
> and tells you exactly what to do, when, and how long you have.
|
||
|
||
The product is being rebranded **A C D L → Nova**. The rebrand is staged
|
||
across phases so that **no consumer deployment breaks during the
|
||
transition**. Phases P2–P4 ship the breaking changes behind a **dual-read
|
||
/ parallel-write grace period**; Phase P5 removes the fallback and the old
|
||
names stop working. This document is the consumer-facing contract for that
|
||
rollout.
|
||
|
||
## What is NOT changing
|
||
|
||
- **The Gitea repository name** (`continuous-intelligence/acdl`) is **not**
|
||
changing. Only the product brand is changing. The `uses:` reference
|
||
(`acdl/.github/workflows/deploy.yml@vX.Y`) and the GitHub `acdl/acdl` repo
|
||
path are unchanged for the duration of the rebrand; the workflow
|
||
`uses:` reference will be migrated in a later, separately-announced step.
|
||
- **The platform behavior** is unchanged. Same pipeline stages, same
|
||
contract schema, same confidence model, same evidence stream, same
|
||
modules. Only the brand, the on-disk path, the env var names, the SSM
|
||
path, the AWS tag keys, and the AWS resource names are changing.
|
||
|
||
## The 5 breaking changes
|
||
|
||
Five things that consumers may reference are being renamed. Each is
|
||
scheduled into a phase, ships with a grace period, and has a cutoff.
|
||
|
||
### 1. Consumer contract path — Phase P2
|
||
|
||
- **Old:** `.acdl/contract.yml`
|
||
- **New:** `.nova/contract.yml`
|
||
- **Phase:** P2 (env vars + consumer path)
|
||
- **Grace period:** during P2–P4 the deploy workflow reads **both** paths
|
||
(`.nova/contract.yml` first, falling back to `.acdl/contract.yml` if the
|
||
new path is absent). Your existing contracts keep working until P5.
|
||
- **Cutoff:** P5 removes the `.acdl/` fallback. Move your contract file
|
||
before P5.
|
||
- **What you must do:** rename the directory in your consumer repo from
|
||
`.acdl/` to `.nova/` and update any `contract:` workflow input that
|
||
points at the old path. Nothing else changes in the contract content.
|
||
|
||
### 2. Environment variables — Phase P2
|
||
|
||
- **Old:** `ACDL_*` (e.g. `ACDL_LIFECYCLE_MODE`, `ACDL_AWS_ACCOUNT_ID`,
|
||
`ACDL_BOOTSTRAP_AWS_ACCESS_KEY_ID`, …)
|
||
- **New:** `NOVA_*` (e.g. `NOVA_LIFECYCLE_MODE`, `NOVA_AWS_ACCOUNT_ID`,
|
||
`NOVA_BOOTSTRAP_AWS_ACCESS_KEY_ID`, …)
|
||
- **Phase:** P2 (env vars + consumer path)
|
||
- **Grace period — dual-read fallback:** during P2–P4 the platform reads
|
||
**`NOVA_*` first, then falls back to `ACDL_*`** if the Nova variable is
|
||
unset. This means your CI secrets, workflow env blocks, and local
|
||
`.env.secrets` keep working unchanged through P4. You do not need to
|
||
rename everything in one shot — rename a variable and the dual-read picks
|
||
it up; leave one old and it still resolves.
|
||
- **Cutoff:** P5 removes the `ACDL_*` fallback. After P5, only `NOVA_*`
|
||
is read.
|
||
- **What you must do:** rename your `ACDL_*` CI secrets, workflow `env:`
|
||
blocks, and any local `.env.secrets` entries to `NOVA_*`. Because of the
|
||
dual-read, you can do this incrementally across P2–P4 — but it must be
|
||
complete before P5.
|
||
|
||
### 3. SSM parameter path — Phase P3 (DONE)
|
||
|
||
- **Old:** `/acdl/{env}/{contractId}/{output}`
|
||
- **New:** `/nova/{env}/{contractId}/{output}`
|
||
- **Phase:** P3 (SSM paths + tag keys) — **shipped in P3**
|
||
- **Grace period — parallel-write:** during P3–P4 the platform **writes
|
||
every output to both** the `/acdl/…` and `/nova/…` SSM paths, and reads
|
||
from `/nova/…` first (falling back to `/acdl/…`). Any hardcoded SSM path
|
||
reads in your application code keep resolving through P4. The P3
|
||
migration script (`scripts/migrate_ssm_paths.py`) copies existing
|
||
`/acdl/…` parameters to `/nova/…`, verifies the copy, and deletes the
|
||
old ones.
|
||
- **Cutoff:** P5 stops writing to `/acdl/…` and removes the read fallback.
|
||
After P5 only `/nova/…` exists.
|
||
- **What you must do:** if your application code or runbooks read deploy
|
||
outputs from SSM by hardcoded path, update the path prefix from `/acdl/`
|
||
to `/nova/`. If you consume outputs only via the PR-comment / GitHub
|
||
issue surface, you do nothing — the platform republishes under the new
|
||
path automatically.
|
||
|
||
### 4. AWS tag keys — Phase P3 (DONE)
|
||
|
||
- **Old:** `acdl:owner`, `acdl:environment`, `acdl:contract`,
|
||
`acdl:cost-center`, `acdl:ref`
|
||
- **New:** `nova:owner`, `nova:environment`, `nova:contract`,
|
||
`nova:cost-center`, `nova:ref`
|
||
- **Phase:** P3 (SSM paths + tag keys) — **shipped in P3**
|
||
- **Grace period — parallel-tag period:** during P3–P4 the platform
|
||
**tags every resource with both** the `acdl:*` and `nova:*` keys (same
|
||
values). The ABAC session policy matches on **either** key set, so your
|
||
existing scoped permissions keep working. The default cost-center value
|
||
moves from `acdl-default` to `nova-default` (both written during the
|
||
parallel-tag period). Terraform now emits `nova:*` keys; old `acdl:*`
|
||
tags on pre-P3 live resources are removed by the P4 runbook's
|
||
`scripts/untag_acdl_keys.py` step after the `nova:*` tags are applied
|
||
live.
|
||
- **Cutoff:** P5 stops writing the `acdl:*` keys and the ABAC policy matches
|
||
only on `nova:*`. After P5, resources created before P5 still carry the
|
||
old `acdl:*` tags (tags are not retroactively rewritten) but **new**
|
||
resources are tagged `nova:*` only, and the policy no longer grants
|
||
access via `acdl:*`.
|
||
- **What you must do:** if you have IAM policies, Cost Explorer filters,
|
||
or billing groupings that key off `acdl:*` tag keys, add a parallel
|
||
`nova:*` condition (or migrate to `nova:*`) before P5. The platform
|
||
handles the dual-tagging; you only need to update your own tag-key
|
||
references.
|
||
|
||
### 5. AWS resource names — Phase P4
|
||
|
||
- **Old:** `acdl-*` (DynamoDB tables `acdl-contracts`,
|
||
`acdl-change-requests`; Lambda `acdl-contract-ingestor`; SNS
|
||
`acdl-sod-halt`; security group `acdl-ecs-sg`; KMS alias
|
||
`alias/acdl-platform`; ECS services, ECR repos, IAM user
|
||
`acdl-spike-runner`, state bucket `acdl-tfstate-*`, ALB `acdl-alb`,
|
||
`acdl-deploy-*`)
|
||
- **New:** `nova-*` (the same resources, prefixed `nova-`)
|
||
- **Phase:** P4 (resource names) — **maintenance window**
|
||
- **Grace period:** P4 is a **planned maintenance window**. AWS resources
|
||
cannot be renamed in place, so P4 provisions the `nova-*` resources,
|
||
migrates data (DynamoDB tables, S3 state), repoints the platform, and
|
||
tears down the `acdl-*` resources. The platform team schedules and
|
||
announces the window; consumers do not provision or rename anything
|
||
themselves.
|
||
- **Cutoff:** the `acdl-*` resources are decommissioned at the end of the
|
||
P4 maintenance window. After P4, only `nova-*` resources exist.
|
||
- **What you must do:** nothing for the resource names themselves — the
|
||
platform owns the rename. If your application code or runbooks reference
|
||
a specific `acdl-*` resource by name (e.g. a hardcoded DynamoDB table
|
||
name or ECR URI), update it to the `nova-*` name during P4. The platform
|
||
publishes the exact old → new name mapping with the P4 announcement.
|
||
|
||
## Timeline at a glance
|
||
|
||
| Phase | What ships | Grace period | Cutoff |
|
||
|-------|------------|--------------|--------|
|
||
| **P1** (this phase) | Brand prose, docs, decks, schema `$id`, release titles | n/a (prose only) | n/a |
|
||
| **P2** | `.nova/` contract path + `NOVA_*` env vars | dual-read: `.nova/`→`.acdl/`, `NOVA_*`→`ACDL_*` | **P5** removes fallback |
|
||
| **P3** | `/nova/` SSM path + `nova:*` tag keys | parallel-write (SSM) + parallel-tag (ABAC matches either) | **P5** removes old path/tags |
|
||
| **P4** | `nova-*` AWS resource names | maintenance window (platform-owned migration) | end of P4 window |
|
||
| **P5** | Fallback removal | — | `ACDL_*` env vars, `.acdl/` path, `/acdl/` SSM, `acdl:*` tags stop working |
|
||
|
||
## What consumers must do (checklist)
|
||
|
||
1. **Before P5 — contract path:** move `.acdl/contract.yml` →
|
||
`.nova/contract.yml` in your consumer repo; update the `contract:`
|
||
workflow input. *(Can be done any time in P2–P4.)*
|
||
2. **Before P5 — env vars:** rename `ACDL_*` CI secrets / workflow `env:`
|
||
blocks / local `.env.secrets` to `NOVA_*`. *(Incremental during P2–P4;
|
||
dual-read keeps you green.)*
|
||
3. **Before P5 — SSM reads:** if you read deploy outputs from SSM by
|
||
hardcoded `/acdl/…` path, update to `/nova/…`. *(Skip if you consume
|
||
outputs via PR comments only.)*
|
||
4. **Before P5 — tag-key references:** if you have IAM policies, Cost
|
||
Explorer filters, or billing groupings keyed off `acdl:*`, add or
|
||
migrate to `nova:*`. *(Platform handles dual-tagging.)*
|
||
5. **During P4 — resource-name references:** if your code or runbooks
|
||
reference a specific `acdl-*` AWS resource by name, update to the
|
||
`nova-*` name per the P4 mapping announcement. *(Platform owns the
|
||
rename itself.)*
|
||
|
||
## Questions
|
||
|
||
If anything in this guide is unclear, or you are unsure whether your
|
||
consumer repo references a renamed value, open an issue on the platform
|
||
repo. The platform team will confirm what you need to change and when.
|
||
|
||
> **Note:** the real Gitea repository name (`continuous-intelligence/acdl`)
|
||
> is **not** changing — only the product brand. The `uses:` workflow
|
||
> reference and repo path are migrated in a separately-announced later step;
|
||
> until then, keep your `uses: acdl/.github/workflows/deploy.yml@vX.Y`
|
||
> reference as-is. |