2026-02-24 - Vault HA Phase 5 Overhaul

Summary

Phase 5 of Vault Enterprise Hardening roadmap was incomplete - it assumed Raft storage backend, but vault-01 uses file storage. Added complete file→raft migration procedure plus detailed VM deployment, TLS certificate issuance, cluster join, and failover verification steps.

Root Cause

Original Phase 5 documentation gap:

Assumption Reality

vault-01 uses storage "raft"

vault-01 uses storage "file"

Just add nodes and join

Must migrate storage backend first

2-node cluster is fine temporarily

2-node Raft is WORSE than 1-node (both must be up for quorum)

Changes

Added

  • 5.2 File to Raft Storage Migration - Complete 9-step migration procedure:

    • 5.2.1 Check current storage backend

    • 5.2.2 Backup current Vault data

    • 5.2.3 Create migration configuration

    • 5.2.4 Prepare Raft directory

    • 5.2.5 Run migration (vault operator migrate)

    • 5.2.6 Update vault.hcl for Raft

    • 5.2.7 Start Vault and unseal

    • 5.2.8 Verify migration

    • 5.2.9 Cleanup

  • 5.3 Deploy vault-02 and vault-03 - VM deployment options:

    • Storage location decision matrix (local SSD vs NAS)

    • cloud-init pattern reference to k3s-deployment

    • Vault installation loop

    • Per-node vault.hcl configuration

  • 5.4 TLS Certificates for New Nodes - Automated cert issuance loop using Vault PKI

  • 5.5 Join Cluster - Step-by-step cluster formation:

    • Start Vault on new nodes

    • Join to leader

    • Unseal new nodes

  • 5.6 Verify HA Cluster - Expected output examples

  • 5.7 DNS Load Balancing - Optional HAProxy/VIP guidance

  • 5.8 Verify Failover - Actual failover test procedure

Changed

  • 5.1 Prerequisites - Added file→raft migration to checklist

  • Updated section numbering (old 5.2→5.3, etc.)

Files Modified

File Type Description

roadmaps/vault-enterprise-hardening.adoc

Changed

Added ~400 lines to Phase 5 (file→raft migration, VM deployment, cluster join, verification)

changelog/2026-02-24-vault-ha-phase5-overhaul.adoc

Added

This file

Technical Details

Migration Command

vault operator migrate -config=/etc/vault.d/migrate.hcl

Key Configuration Change

Before (file storage)
storage "file" {
  path = "/opt/vault/data"
}
After (raft storage)
storage "raft" {
  path    = "/opt/vault/raft"
  node_id = "vault-01"

  retry_join {
    leader_api_addr = "https://vault-02.inside.domusdigitalis.dev:8200"
  }
  retry_join {
    leader_api_addr = "https://vault-03.inside.domusdigitalis.dev:8200"
  }
}

Validation

Not yet executed - documentation prepared for execution.

Related

Author

  • evanusmodestus

  • Date: 2026-02-24

  • Session: Vault HA preparation with Claude