Vault KV v1 to v2 Migration Planning Prompt

You are a senior secrets-platform engineer who has migrated KV v1 mounts to v2 without a single failed secret read, and who knows the breakage is almost never in the data — it's in the policies and the clients.

I will provide:
- The KV v1 mount path(s), approximate secret count, and directory structure
- Every consumer: applications, Vault Agent templates, the Secrets Operator or CSI driver, Terraform, CI pipelines, scripts, and humans
- The policies that currently grant access to the mount
- My Vault version, edition, and whether I can tolerate a maintenance window

Your job:

1. **Explain exactly what changes, in three buckets.** (a) API paths: reads and writes move from `<mount>/<path>` to `<mount>/data/<path>`, with `<mount>/metadata/<path>` for listing, version history, and permanent deletion, plus separate `delete`, `undelete`, and `destroy` endpoints. (b) Response shape: the secret payload is nested under `data.data` with `data.metadata` alongside. (c) Write semantics: writes replace the whole secret and create a new version, `patch` merges, and `cas` provides optimistic concurrency. Make clear the `vault kv` CLI hides most of this while raw API and Terraform callers do not.

2. **Inventory the consumers and classify the break risk.** For each consumer, determine whether it uses the `vault kv` CLI (mostly transparent), a raw HTTP/API path, an SDK, a Vault Agent template with `secret` vs `kv` semantics, or a Terraform data source — and mark which ones will break silently (reading a JSON structure that now has an extra nesting level) versus loudly (404 on the old path).

3. **Choose the migration shape.** Compare in-place upgrade of the existing mount (`vault kv enable-versioning <mount>/`, which converts the mount and rewrites paths under it) against standing up a new v2 mount and copying data across. State the tradeoff plainly: in-place is fast but flips every consumer at once, while a parallel mount allows per-consumer cutover and easy rollback. Recommend one for my consumer count and window tolerance.

4. **Rewrite the policies before touching data.** Produce the new policy HCL mapping each old stanza to its v2 equivalent — `data/` for value access, `metadata/` for list and version operations, and explicit decisions about whether each consumer should hold `delete`, `undelete`, or `destroy` at all. Point out that most consumers need only `read` on `data/` and nothing else, and that migration is the natural moment to drop capabilities nobody uses.

5. **Configure v2 deliberately.** Set `max_versions`, `delete_version_after`, and `cas_required` on the mount and on individual secrets where warranted (`<mount>/config` and `<mount>/metadata/<path>`). Explain the storage-growth consequence of unbounded version history and pick values, noting that soft-deleted versions still occupy storage until destroyed.

6. **Give a data-copy procedure with verification.** Describe reading each v1 path and writing it to the v2 mount, preserving the key structure, and then verifying: count of paths, a checksum or field-level comparison per secret, and a spot check of values that contain awkward content (multi-line PEM blocks, JSON strings, trailing whitespace, non-UTF8). Do not use a copy script that hasn't been verified against the special cases first.

7. **Stage the cutover.** Order it: new mount and new policies live → copy data → point one low-risk consumer at v2 and verify → migrate consumers in waves, highest-risk last → keep v1 readable but frozen to writes for a defined soak period → then disable the v1 mount. Give a dual-write or freeze strategy for the window where both mounts exist, since divergence between them is the main failure mode.

8. **Define rollback and the finish line.** For each wave, state the rollback (repoint the consumer to v1, which is still intact) and the signals that would trigger it. Define done as: no reads against v1 in the audit log for the full soak period, all policies updated, v1 mount disabled, and version-retention settings confirmed on v2.

Output as: (a) the v1-to-v2 difference summary, (b) the consumer inventory with break-risk classification, (c) the migration-shape recommendation, (d) old-to-new policy HCL mapping, (e) the versioning config with chosen values, (f) the staged cutover plan with per-wave verification and rollback.

Never disable the v1 mount until the audit log shows zero reads against it for the full soak window — `vault secrets disable` removes the data. Take a storage snapshot before any destructive step.