Deployment

This page covers what a contributor needs to know about how Vault is built, packaged, and released. It is not a how-to-run-Vault-in-prod guide; for that, see the Vault deployment docs.

What's in the box

A Vault release includes:

• A single statically linked Go binary (vault).
• An embedded Ember.js UI (in builds with static-dist).
• Per-platform installers / packages built outside this repository.

The binary is what ships; everything else is downstream packaging.

Build artifacts

Makefile produces a development binary; scripts/build.sh produces release-style binaries with full version metadata. CI builds artifacts via .github/workflows/build.yml (37 KB, the largest workflow) and build-artifacts-ce.yml for Community Edition or build-artifacts-ent.yml for Enterprise.

Versioning lives in version/:

• version_base.go — major.minor.patch.
• version_metadata.go — git SHA, build date.
• version.go — combines them at link time.

The release pipeline tags v<major>.<minor>.<patch> on main (or a release/x.y branch) and triggers the build workflow.

CE vs Enterprise

Enterprise is a separate fork built from the same source plus closed-source files. The OSS tree carries _ce.go / _oss.go stubs; Enterprise builds replace them at link time.

Distribution channels:

• Community: HashiCorp downloads, GitHub releases, official Docker images at hashicorp/vault.
• Enterprise: customer downloads, hashicorp/vault-enterprise Docker, HCP Vault.

build-hcp-image.yml builds the HCP Vault image; the rest of HCP plumbing is in vault-hcp-lib.

Cluster topologies

graph TD
    subgraph "Single-node dev"
        D[vault server -dev]
    end
    subgraph "Standalone"
        S[Single Vault + storage backend like Postgres]
    end
    subgraph "Integrated Raft cluster"
        N1[Active] -- raft replication --> N2[Standby]
        N1 -- raft replication --> N3[Standby]
    end
    subgraph "External-storage HA"
        VA[Active] --- Consul[(Consul cluster)]
        VB[Standby] --- Consul
    end
    subgraph "Multi-cluster (Enterprise)"
        Primary --> DR[DR secondary]
        Primary --> Perf[Performance secondary]
    end

The recommended new-deployment topology is integrated Raft (3 or 5 nodes). See Raft and HA.

Process supervision

Production deployments run Vault under a supervisor (systemd, Kubernetes, Nomad). Notes:

• mlock is enabled by default on Linux to prevent the master key from being paged out. Either give Vault CAP_IPC_LOCK or set disable_mlock=true in config.
• Vault writes a PID file with pid_file= if configured.
• SIGHUP reloads TLS certs, audit destinations, and telemetry. SIGTERM performs graceful shutdown. SIGUSR2 writes a stack dump.

Configuration files

/etc/vault.d/vault.hcl is the conventional location. Vault accepts both HCL and JSON. Configuration parsing lives in command/server/config.go and the block parsers under internalshared/configutil/. See Reference / configuration for the full grammar.

TLS

The recommended setup uses a TLS-enabled tcp listener. For production:

• Certificates from an internal PKI or ACME provider (often Vault's own pki engine!).
• Non-default ports: 8200/tcp for clients, 8201/tcp for cluster traffic. Both must be reachable between nodes.
• Reload TLS on rotation by SIGHUP.

Storage choice

Constraint	Pick
New deployment, prefer fewest moving parts	Integrated Raft
Already running Consul	Consul
Cloud-native, OK with single-node	DynamoDB / Cosmos DB / Spanner / GCS / S3
Postgres-only operational stack	postgresql

physical/<name>/ contains every implementation; see Storage backends.

Service registration

Independently of storage, configure service_registration so something downstream knows where Vault is and which node is active:

• consul: registers a Consul service entry per node with a vault.active health check.
• kubernetes: writes labels to the Vault Pod marking it as active or standby.

Source: serviceregistration/.

Monitoring and metrics

Default telemetry is exposed at:

• /v1/sys/metrics?format=prometheus — Prometheus scrape.
• StatsD / Circonus / Datadog sinks via telemetry config.
• pprof endpoints under /v1/sys/pprof/... (gated by enable_debug_endpoints).

Backup and restore

For Raft: vault operator raft snapshot save backup.snap. Restore via restore to a new cluster or restore -force to the same cluster (last resort).

For external storage backends, back up the underlying storage system (Consul snapshots, RDS snapshots, etc.). The barrier ciphertext travels with the storage; the keyring travels with the seal config.

Upgrades

Vault supports rolling upgrades within a major version. The general procedure:

1. Stop a standby node.
2. Replace the binary.
3. Restart; let it rejoin and catch up.
4. Repeat for every standby.
5. Step down the active node (vault operator step-down); a freshly-upgraded standby takes over.
6. Upgrade the previously-active node.

Major-version upgrades may require additional steps documented in CHANGELOG.md.