HashiCorp Vault — Upgrade Strategies

2 minute read

Upgrading Vault requires careful planning to avoid downtime and data loss — especially in production HA clusters.

Upgrade Rules

  1. Always read the release notes — check for breaking changes
  2. Never skip major versions — upgrade incrementally (1.14 → 1.15 → 1.16)
  3. Backup before upgrading — take a Raft snapshot
  4. Test in staging first — mirror your production setup
  5. Upgrade standby nodes first — then the leader

Pre-Upgrade Checklist

# 1. Check current version
vault version

# 2. Read upgrade notes
# https://developer.hashicorp.com/vault/docs/upgrading

# 3. Take a backup
vault operator raft snapshot save pre-upgrade-$(date +%Y%m%d).snap

# 4. Verify cluster health
vault status
vault operator raft list-peers

# 5. Check for deprecations
vault operator diagnose

Single-Server Upgrade

# 1. Stop Vault
sudo systemctl stop vault

# 2. Replace binary
sudo cp vault /usr/local/bin/vault
sudo chmod +x /usr/local/bin/vault

# 3. Verify new version
vault version

# 4. Start Vault
sudo systemctl start vault

# 5. Unseal (if not using auto-unseal)
vault operator unseal

# 6. Verify
vault status

HA Cluster Rolling Upgrade

Step 1: Identify the Leader

# Check who is the leader
vault operator raft list-peers
# Note: upgrade standbys FIRST

Step 2: Upgrade Standby Nodes

For each standby node:

# On standby node:

# Stop Vault
sudo systemctl stop vault

# Replace binary
sudo cp vault-new /usr/local/bin/vault
sudo chmod +x /usr/local/bin/vault

# Start Vault (auto-unseals and rejoins the cluster)
sudo systemctl start vault

# Verify
vault status
vault operator raft list-peers

Step 3: Step Down the Leader

# On the leader node:
vault operator step-down
# A standby (already upgraded) becomes the new leader

Step 4: Upgrade the Former Leader

# Now upgrade the old leader (now a standby)
sudo systemctl stop vault
sudo cp vault-new /usr/local/bin/vault
sudo systemctl start vault

# Verify full cluster
vault operator raft list-peers

Kubernetes Helm Upgrade

# Update Helm repo
helm repo update hashicorp

# Check available versions
helm search repo hashicorp/vault --versions

# Dry run
helm upgrade vault hashicorp/vault \
    --namespace vault \
    --values values.yaml \
    --dry-run

# Upgrade (Helm handles rolling update)
helm upgrade vault hashicorp/vault \
    --namespace vault \
    --values values.yaml

# Monitor rollout
kubectl rollout status statefulset vault -n vault

Rollback Plan

If the upgrade fails:

# 1. Stop the upgraded node
sudo systemctl stop vault

# 2. Restore the old binary
sudo cp vault-old /usr/local/bin/vault

# 3. If data migration occurred, restore snapshot
vault operator raft snapshot restore pre-upgrade-20240115.snap

# 4. Start with old version
sudo systemctl start vault

Version Compatibility

Scenario Compatible?
Mixed versions in HA cluster (during upgrade) ✅ (briefly)
Newer leader, older standby ✅
Older leader, newer standby ✅
Skip major versions (1.14 → 1.16) ❌
Downgrade after data migration ❌

Upgrade Timeline

Phase Duration Action
Prep 1–2 days Read notes, test in staging
Backup 5 min Raft snapshot
Standbys 5–10 min each Rolling restart
Leader step-down 1 min Seamless failover
Old leader 5–10 min Upgrade last node
Verify 15 min Health checks, smoke tests

Next: Security Model

You may also enjoy