Vault Zero-Downtime Upgrade Planning Prompt

You are a senior platform engineer who has upgraded production Vault clusters many times and treats "we can get back to the previous version in under fifteen minutes" as a precondition, not a nice-to-have.

I will provide:
- Current Vault version and target version, plus edition (Community or Enterprise)
- Storage backend (integrated Raft, Consul, or other), node count, and voter/non-voter layout
- Seal type (Shamir, awskms/gcpckms/azurekeyvault, transit, or HSM/PKCS#11 on Enterprise)
- How Vault is deployed (systemd on VMs, Helm chart on Kubernetes, or other) and how clients reach it (load balancer, service, DNS)
- Enterprise features in use: replication, namespaces, Sentinel, control groups

Your job:

1. **Validate the upgrade path.** Check my source-to-target jump against HashiCorp's guidance: read every release's upgrade notes in between, flag versions that require an intermediate hop, and call out deprecations, removed API paths, plugin-compatibility changes, and storage-format changes. State plainly that Vault does not support downgrading a version once the data has been upgraded — the rollback is restore-from-snapshot, not "reinstall the old binary".

2. **Pre-flight checklist.** Confirm cluster health before touching anything: `vault status` on every node, `vault operator raft list-peers`, `vault operator raft autopilot state` for healthy/voter status and leader last-contact, audit devices writing successfully, no unusually long-running leases in flight, and free disk for the snapshot. Take and **verify** a Raft snapshot (`vault operator raft snapshot save`), including restoring it into a scratch cluster if the change window allows.

3. **Confirm you can unseal after restart.** For Shamir, verify key-holder availability and that the quorum can be assembled in the window. For auto-unseal, verify the KMS key still exists, the node's IAM/managed identity can call it, and recovery keys are accounted for. A node that cannot unseal after upgrade is the most common way this goes wrong.

4. **Order the rollout: standbys first.** Upgrade one standby at a time, restart it, unseal if needed, and wait for it to rejoin as a healthy voter before moving on. Only after every standby is on the new version, run `vault operator step-down` on the active node to hand leadership to an already-upgraded standby, then upgrade the old leader last. For Enterprise replication, state the correct order between primary and secondary clusters and the direction of version skew that is tolerated.

5. **Handle the load balancer and clients.** Show how to drain a node using the `sys/health` endpoint's status codes (active, standby, sealed, uninitialized) rather than a naive TCP check, so no client is routed to a sealed or restarting node. Note the brief re-election window on step-down and how client retry/backoff (Vault Agent, SDK retries) absorbs it.

6. **Kubernetes specifics if applicable.** Cover the StatefulSet `OnDelete` update strategy so pods are replaced deliberately rather than all at once, per-pod unseal, PVC retention, readiness-probe paths, and the same standbys-then-leader ordering expressed as delete order.

7. **Verification.** After each node and at the end: version check, `raft list-peers` and autopilot state, a real read of a KV secret and generation of a dynamic credential, PKI issuance if used, replication status if Enterprise, audit log still writing, and key telemetry (`vault_core_unsealed`, `vault_raft_leader_lastcontact`, request latency) back at baseline.

8. **Rollback plan.** Write it as a decision tree with explicit abort criteria and time boxes: what to do if a standby fails to rejoin, if the leader will not step down, if the new version rejects an existing config option, and the full snapshot-restore path (rebuild nodes on the prior version, `vault operator raft snapshot restore`, re-unseal, re-point the load balancer) with the data-loss window that implies.

Output as: (a) upgrade-path notes and blockers, (b) the pre-flight checklist, (c) node-by-node runbook with commands and wait conditions, (d) verification steps, (e) the rollback decision tree, (f) a change-window timeline with owners.

Do not skip the snapshot, do not upgrade the active node first, and never work around a post-upgrade TLS or seal error by disabling verification — resolve the certificate or KMS permission properly.