OpenBao high availability guide

Why OpenBao high availability is harder than a single node

If your applications depend on OpenBao for secrets and encryption, a single server is a single point of failure you cannot accept. OpenBao high availability runs one active node that holds a lock in a supported data store, while standby nodes stay ready to take over. The two officially supported HA backends are integrated storage (Raft) and PostgreSQL, as the HA documentation states. Choosing between them is the first decision, and it shapes almost every operational task that follows.

The first difficulty is that every node has to be unsealed, and unsealing depends on key custody. OpenBao starts sealed, and each node must be unsealed before it can serve requests. A standby that restarts without a way to unseal itself will not rejoin the cluster on its own, so you need to decide how unseal keys or an auto-unseal mechanism reach every node, who holds the key shares, and how that process works at 2 a.m. Confirm with your own key management team where those keys will live before you count nodes. Also confirm the auto-unseal options your chosen OpenBao version supports in its current documentation.

The second difficulty is that backend operations differ. Raft is built into OpenBao, but adding, removing or recovering voting members is your responsibility, and a cluster that loses quorum needs a documented recovery path. PostgreSQL moves storage durability to a database you may already run, but it adds database failover, connection settings, backup coordination and its own patching cycle. The OpenBao storage documentation describes PostgreSQL as easier to operate safely than Raft, which is worth weighing against your team's database skills. Write down which team owns each failure mode.

The third difficulty is client failover. HA on the server side does not make applications fail over. Clients must be pointed at a load balancer, a virtual address or a list of nodes, and their retry behavior must handle a leader change without leaking errors into business logic. Test this with the real client libraries and agents your workloads use, not only with the CLI.

The fourth difficulty is read scaling, which depends on the version you run. Since OpenBao 2.5.0, Raft standbys can serve read-only operations, and v2.7.0 extended this to PostgreSQL. Do not assume standbys absorb read traffic on an older line. Confirm the exact version and its read behavior in the HA documentation, then test which request types actually route to standbys in your environment before you size the cluster.

The components an OpenBao HA cluster is built from

An OpenBao HA cluster is a set of nodes that share one data store and one active role. The cards below cover the pieces you configure and the decision each one drives. Each choice depends on the others, so settle the storage backend first, then addressing and unseal.

The active node and its lock

One node holds the active role at a time, and it does so by holding a lock in the data store that all nodes share. The lock prevents two nodes from acting as leader at once, so the backend you choose must support it. Check how your chosen backend releases the lock when the active node fails, since that timing shapes how quickly a new leader takes over. Confirm the lock behavior in the OpenBao HA documentation for your version.

Standby nodes forward or redirect

Standby nodes keep running and wait to take over the active role. A standby forwards or redirects requests that need the active node, so clients can reach any node without knowing which one is active. Since OpenBao 2.5.0, Raft standbys can serve read-only operations, and v2.7.0 extended this to PostgreSQL. Decide how many standbys you run and whether read traffic should reach them, then test read behavior in your own environment.

Integrated Raft or PostgreSQL storage

The storage backend holds the encrypted data and the HA lock, so it sets the availability and operating model of the whole cluster. OpenBao's officially supported HA backends are integrated storage (Raft) and PostgreSQL. The OpenBao storage documentation describes PostgreSQL as easier to operate safely than Raft, which should be weighed against your team's existing database skills. Confirm the switching path with OpenBao before you choose, because moving between backends later requires a planned migration.

Load balancer or DNS name

Clients should connect to one stable address that stays the same through node replacements and failovers. A load balancer or DNS record in front of the cluster lets you replace a node without changing client configuration. Confirm how OpenBao's cluster addressing settings must match the name clients use, and which health check endpoint your load balancer can rely on to route traffic to the active node. Test failover through the name clients use, and also directly against individual nodes.

Unseal on every node

Every node in the cluster must be unsealed before it can serve requests, including standbys that wait to take over. The unseal mechanism decides who holds the material needed to unseal and how unsealing happens after a restart. Choose between manual unseal and an automated approach, and document who can perform each step during an outage. Confirm the supported unseal options and their key custody requirements for your version in the OpenBao documentation.

Backends that are not HA

PebbleDB and in-memory storage are documented OpenBao storage backends, but they are not HA backends and should not be used for this design. Neither provides the shared lock and replicated data that a multi-node cluster needs to fail over. A single-node test on either is useful only for learning and should not become the production path. Check your storage choice in the first design review, and keep these backends out of production configuration templates.

Raft or PostgreSQL: which HA backend fits your operations

This table compares integrated storage (Raft) and PostgreSQL for OpenBao high availability across storage ownership, node footprint, standby reads, backup, skills and failover routing. Read the third column as the work your team takes on with each choice. The OpenBao docs describe PostgreSQL as easier to operate safely than Raft, which should weigh heavily if your team has no Raft experience.

Decision	What changes	What it costs the team to operate
Storage ownership	Raft: storage lives on the OpenBao nodes. PostgreSQL: storage sits in a database tier that you or a provider run.	Raft: the OpenBao team owns disks, patching and failure handling. PostgreSQL: a named database owner must agree access and patch duties in writing.
Node count and footprint	Raft: each node holds cluster data, so sizing and disk I/O are part of the OpenBao plan. PostgreSQL: OpenBao nodes hold no cluster data of their own.	Raft: capacity planning and disk monitoring stay with OpenBao operators. PostgreSQL: database sizing, replication and connection limits need a separate capacity plan.
Standby read scaling	Raft standbys serve read-only operations from OpenBao 2.5.0. PostgreSQL standbys do so from 2.7.0.	Confirm your running version before designing read paths. Clusters on earlier lines cannot count on standby reads for PostgreSQL.
Operational safety	The OpenBao docs describe PostgreSQL as an easier backend to operate safely than Raft.	Raft: more time goes to procedures, testing and staff training. PostgreSQL: the team still needs database operations skills, but fewer cluster-specific procedures.
Backup and restore	Raft: the team takes and restores snapshots with OpenBao procedures. PostgreSQL: backups follow the database team's standards.	Either way, test restores regularly. Confirm the runbook covers the OpenBao data and the unseal material kept outside storage.
Skills required	Raft: consensus behavior, peer management and snapshot handling. PostgreSQL: database administration, replication and secure connection setup.	Identify who can diagnose each failure mode before go-live. Skills gaps usually surface during the first failover test.
Load balancer or client-side failover	A load balancer gives clients one stable address. Client-side failover lists several node addresses and retries inside each client.	The load balancer is another component to secure, monitor and patch. Client-side failover moves address and retry logic into every application.
External database service	A managed PostgreSQL service can take replication, backups and maintenance off your team.	Review the provider's failover, maintenance windows, audit logs and access controls in the contract. Confirm which OpenBao versions the provider supports.

How to build the OpenBao HA cluster step by step

This sequence takes an OpenBao cluster from an approved release and prepared nodes to a tested highly available deployment with one active node, standby nodes and a stable client address. Each step closes with a check so the platform team can confirm progress before moving on. Ports, timeouts and node counts should come from the documentation for your chosen release.

Confirm the target version and release line
Open the OpenBao releases page on GitHub and choose the release line you will run, noting the latest patch in that line. Record the exact version in your change plan so every node, the storage backend and any client tooling match it. The step is done when the platform owner and the security team approve the version and its release notes. Confirm the upgrade path from your current installation before you deploy anything.
Provision nodes and network paths
The platform or infrastructure team creates the nodes in the cloud accounts, data center or air-gapped network you control, sized to your design. Open the traffic paths between nodes and confirm the cluster communication ports in the OpenBao documentation for your version, since this guide does not list defaults. Confirm that nodes can reach each other in both directions and that clients and load balancers can reach the API address. The step is done when a connectivity test passes between every pair of nodes.
Configure the storage backend on each node
For integrated storage, write the Raft configuration on each node with a unique node identity and the address of every peer, following the storage documentation for your version. For PostgreSQL, provision a database the nodes can reach with the HA lock support described in the HA documentation. The storage documentation describes PostgreSQL as easier to operate safely than Raft, which is worth weighing before you choose. The step is done when each node's configuration validates and reports its backend as reachable before any node starts.
Configure listeners and TLS
Set the API and cluster listeners on each node and install the certificates and keys issued by your internal certificate authority, with the names clients will use in the subject or alternative names. If the configuration came from Vault, remove disable_mlock, because OpenBao stopped using mlock in 2.0.0. Confirm the certificate chain with a TLS client from a machine other than the node you configured. The step is done when each node answers over HTTPS with a certificate your clients trust.
Initialize one node and unseal the rest
Initialize the first node once and record the recovery material and root token it returns. Store them under your key custody procedure and keep them out of the change ticket. Unseal the first node, then unseal each remaining node using the unseal method your design specifies. If you use auto-unseal, this flow changes, so confirm it in the documentation for your version. The step is done when the cluster reports as initialized and unsealed with exactly one active node.
Join standby nodes and confirm their status
Join each remaining node to the cluster using the leader address, then unseal it as in the previous step. Check the status output on each standby and confirm that it reports standby mode and points to the active node. Confirm that the Raft peer list or PostgreSQL membership shows every node before you continue. The step is done when every node reports as active or standby and the membership matches your planned node count.
Place a stable address in front of the cluster
Create a load balancer, DNS record or virtual address that clients will use, and point it at the API listeners on all nodes. Configure a health check based on the health endpoints in the documentation for your version, so that unhealthy nodes are removed from rotation. The HA documentation describes standbys forwarding or redirecting requests, so test how writes reach the active node through this address. The step is done when a client request through the stable address succeeds and the certificate validates against that name.
Test failover and standby read behavior
In a planned test window, stop the active node and watch the remaining nodes until one takes the active role. Record the time the switch takes, confirm that a client write through the stable address succeeds afterward, and review the logs for the leadership change. Then confirm standby read behavior for your version, since Raft standbys serve read-only operations from 2.5.0 and PostgreSQL standbys from 2.7.0. Test the read path your applications will use. The step is done when failover and standby reads pass in a documented test.

What drives the effort of an OpenBao HA rollout

This table lists the factors that most change the scope of an OpenBao high availability rollout and suggests how to keep each one manageable. Read each row as a question to answer in your scoping notes before asking for a quote. The main takeaway is that most of the effort comes from variation, so standardizing one reference topology and one failover test usually matters more than any single feature.

Driver	Why it changes effort	How to keep it down
Number of environments	Production, disaster recovery and non-production clusters each need their own build, failover testing and backup verification.	Use one reference topology and repeat it across environments with the same configuration templates.
Storage backend and existing PostgreSQL	Integrated storage (Raft) needs node-level sizing and snapshot handling. PostgreSQL adds a database service to build, patch and back up, unless one already exists.	Reuse a supported PostgreSQL service your database team already runs, or standardize on Raft if no database platform exists. Confirm the choice against the HA documentation.
Unseal and key custody model	Each node's unseal process, recovery material and custody owners must be designed before the first node starts. Mistakes here are hard to undo later.	Document one custody model with named owners, then script its use. Confirm the auto-unseal options that fit your key management service.
Network and load balancer constraints	Cluster traffic, client redirects and health checks depend on what your firewalls, load balancers and DNS allow between nodes and clients.	Request the required port and health check rules early and apply them through standard change control.
Client count and failover handling	Each application that caches addresses or holds long-lived sessions may need changes to handle a leader change. More clients mean more test cases.	Group clients by how they connect, then write the failover test once per group rather than once per application.
Standby reads	Serving reads from standbys adds load-balancing rules and a need to confirm which requests are safe to send to standbys. Not needed for every workload.	Start without standby reads unless measured read load requires them. Add the feature later as a scoped change.
Backup and restore testing scope	Snapshot or database backups need restore tests that prove a usable cluster can be rebuilt, which takes time in each environment.	Define one restore runbook and test it on a non-production cluster that matches production layout.
Compliance evidence	Assessors usually ask for configuration records, access controls, backup results and failover test records. Each item must be produced and kept.	Agree the evidence list up front and generate it from the same runbooks used for the build. DeployOpen prepares evidence but does not issue audit reports or certifications.

How the HA design changes by deployment model

With integrated storage, the OpenBao nodes hold the cluster data themselves, so the cluster is both the service and its storage. The build centers on node placement, peer communication and backup discipline, because no separate database team owns any part of the data path. Node count and voting membership should follow the current OpenBao HA documentation, and the team should decide how many voters can fail before quorum is lost.

Key build points:

Give each node its own data directory on disks that match the failure domains you plan for, such as separate hosts, hypervisors or racks.
Set up TLS between cluster peers and open the cluster port only between nodes and approved clients.
Confirm which client traffic reaches standbys, since Raft standbys can serve read-only operations from version 2.5.0 onward.
Schedule Raft snapshots, store them outside the cluster, and restore them into a test cluster on a fixed cadence.
Document the procedure for replacing a failed voter, including how the replacement joins and catches up.

Confirm the physical or virtual failure domains behind each node, the disk and snapshot retention you have approved, and whether your team has rehearsed a voter replacement at least once before production use.

Securing the HA cluster and its storage

An HA OpenBao cluster concentrates every secret in one replicated store, so its controls matter more than any single node. The cards below cover transport, storage credentials, unseal custody, membership, backups and network placement, each with the risk it addresses and the check to run before go-live.

TLS between nodes and clients

Standby nodes forward or redirect requests to the active node, and clients talk to whichever node answers. Both paths should use TLS with certificates issued from a CA your team controls. Check that every listener and every cluster address uses HTTPS, that clients verify the server certificate rather than skipping verification, and that certificate renewal is tested before the first expiry.

Protecting the Raft or PostgreSQL data

The storage backend holds the lock used for leader election and all encrypted secret values. For Raft, the data directory on each node is the data at rest. For PostgreSQL, the database role OpenBao uses has access to the data and its backups. Confirm that data directories and database roles have restricted file and login permissions, and that the OpenBao storage credentials are separate from application database credentials.

Unseal key custody and distribution

Unseal keys, or the recovery material used by auto-unseal, are what allows a restarted cluster to serve requests again. Keep key shares with different custodians and store them apart from the cluster, so losing one node or one custodian does not block recovery. Check which unseal method you use, who holds each share, where shares are stored, and that a recovery drill has been run from the documented procedure.

Restricting cluster membership changes

Adding or removing a Raft peer changes who can receive replicated data and vote on leadership. Limit the policies and operator accounts that can perform these operations, and require a documented change record for each join or removal. Review the membership list after every change and confirm that no unexpected node has joined, since a rogue peer would receive encrypted data it should never hold.

Protecting snapshots and backups

Snapshots contain the encrypted secret values and the material needed to read them, so they must be protected like the live cluster. Store them in an encrypted location with access limited to the backup operator, keep retention documented, and rotate any copies that leave the environment. Test a restore into an isolated cluster at intervals, because a backup that has never been restored is an assumption rather than a control.

Network isolation of cluster traffic

Cluster traffic between nodes and storage should travel on a dedicated network segment, with firewall rules that allow only the cluster ports and the client networks that need access. Health checks and load balancers should reach only the endpoints they require. Verify the rules from outside the segment with a port scan, and confirm that the storage backend is not reachable from application subnets.

Testing leader failover and restore before go-live

Before an OpenBao cluster carries real secrets, the team should prove two things in its own environment: that the cluster elects a new active node and keeps clients working when the current one stops, and that a backup can be restored into a separate environment with secrets and policies intact. Both tests should be written as a runbook with pass criteria agreed in advance, so the result is a recorded outcome rather than an impression. Start with a baseline. Confirm exactly one node reports itself as active and the remaining nodes report as standbys, using the status output from each node and, for Raft clusters, the peer list from the integrated storage operator commands. Record the leader and each peer's address and version. If the chosen OpenBao version supports read operations on standbys for your storage backend, confirm that setting explicitly and test which requests a standby answers and which it forwards or redirects. The documentation describes this behavior by version, so check the release notes for the exact version you deploy rather than assuming it applies. Next, stop the active node under controlled conditions, such as a planned service stop during a maintenance window with a test workload running. Measure how long the cluster takes to elect a new active node, and confirm that the client path behaves as expected. A client that talks to the load balancer or DNS name should reconnect without configuration changes. A client that holds a direct node address will not, so find those clients now. Record the observed election time and client error window. Do not treat any number from a vendor page as your expected result: your storage latency, network and node sizing decide it. The failure cases matter more than the happy path. Test losing a majority of Raft peers, which stops writes and leaves the cluster unable to elect a leader until quorum is restored. Test losing the PostgreSQL database, which removes the lock and storage the active node depends on. For each case, write down the recovery steps your team would take, who has authority to take them, and whether unsealing keys or recovery material are needed and available. Then perform a restore: take a snapshot or backup, restore it into a separate environment, unseal, and confirm that expected secrets can be read and that policies and auth configuration are present. Ask your storage and key custody owners to confirm the procedure before the test, not during an incident.

What to monitor, back up, upgrade and document after go-live

After go-live, an OpenBao HA cluster needs the same attention as any production service, with one difference: lost unseal material or a failed upgrade can lock every application out of its secrets. The five tasks below connect monitoring, backup, upgrades and documentation, and each one feeds the failover and restore runbooks the team will rely on under pressure.

Cluster health and leader status

Watch which node holds the active lock, whether each standby reports as healthy, and how often leadership changes. Frequent elections usually point to network instability, slow storage or resource pressure on a node, so alert on repeated changes within a short window. Confirm which health and metrics endpoints your OpenBao release exposes, and check that your monitoring stack can scrape them.

Storage capacity and peer health

On Raft, track each peer's membership, disk growth on every voting node and how long writes take to commit. On PostgreSQL, track disk space, connection use and replication lag between the primary and the replicas that serve standby reads. Set alerts that fire well before a volume fills, because a full disk stops the cluster from accepting writes. Confirm the exact metrics your chosen backend exposes.

Backups and unseal material

Schedule snapshots of the storage backend and copy them outside the cluster's failure domain. A backup only proves recovery once it has been restored, so run restore tests into an isolated environment on a fixed cadence. Store unseal keys or recovery keys, and the access path to any auto-unseal key, separately from the backups they protect, and document who may combine them and under which conditions.

Rolling upgrade planning

Plan upgrades one node at a time, standbys first and the active node last, and confirm that the cluster keeps quorum at every step. Before choosing a target, check the release notes for v2.7.0 and v2.7.1 against your current version, along with the v2.6.4 patch for the previous minor line. The sibling upgrades page covers the step-by-step procedure and rollback considerations.

Topology and ownership records

Document node placement, load balancer addresses, the storage backend and its version, the unseal method and the auth methods in use. Name an owner for each runbook covering failover, restore and key rotation, and review those records after every upgrade or topology change. Runbooks that have never been rehearsed are unproven, so schedule failover drills and record what happened in each one.

Questions teams ask before running OpenBao HA

How much does it cost to run an OpenBao HA cluster?

OpenBao is licensed under MPL-2.0, so there is no license fee to pay for the software. The recurring costs are the infrastructure for the nodes, the storage behind them (local disks for Raft or a PostgreSQL service), the custody of unseal material, and the people who respond when a node fails. The one-time costs are the design, implementation and testing work. Ask any quote to list these components separately, state who pays for each one (your team, your cloud provider, or a partner), and show which costs repeat each year.

How long does an OpenBao HA implementation take to complete?

The duration depends on the scope you agree. The main drivers are the number of environments (for example development, test and production), the storage backend, the unseal approach, and the integrations, such as your identity provider, monitoring, backup target and the applications that will connect. Failover and restore testing add time because each test needs a defined procedure and a named owner. We do not give a duration before the scope is written. Ask for a plan with milestones, the assumptions behind each one, and the points where your team must provide access or make a decision.

Can an internal team build an OpenBao HA cluster alone?

Yes, a capable internal team can build an OpenBao HA cluster using the official documentation and a runbook it has tested in a non-production environment. The harder part is operational ownership. Failover tests, backup restores and unseal procedures each need a named person who runs them on a schedule and records the results. Teams that skip these tests often find gaps during an outage. If your team has the people and time for this work, plan for the testing from the start. If not, a partner can build the cluster, write the runbook and run the first tests with your staff.

What does an OpenBao HA project need from our team?

Most of the input comes from your infrastructure, security and operations staff. The project needs access to the cloud accounts, data centers or air-gapped networks where the nodes will run, and network paths between the nodes, load balancers and clients. Your team must decide how unseal keys will be held and by whom, and it must provide a named owner who approves designs and signs off on tests. You also need a backup target with a defined retention period, a change window for cutover, and access to the monitoring and logging systems the cluster will report to.

Can we read secrets from standby nodes in OpenBao today?

It depends on your version. Since OpenBao 2.5.0, Raft standby nodes can serve read-only operations, and OpenBao 2.7.0 extended this to PostgreSQL-backed clusters, which gives you horizontal read scaling on that backend. Writes still go through the active node. Confirm the exact version you will run, check that your clients and applications only use read operations on standby addresses, and test how they behave during a leader change. Also check the release notes for any limits on which endpoints are served by standbys.

Should we choose Raft or PostgreSQL for OpenBao HA storage?

Both are officially supported HA backends. Integrated storage (Raft) keeps the data inside the OpenBao nodes, so you have no separate database to run. PostgreSQL uses an external database that your team may already operate, and the OpenBao storage documentation describes it as easier to operate safely than Raft. Your choice should follow the skills and tooling you already have, the backup approach you can support, and the read scaling you need. Confirm the version-specific behavior for standby reads on whichever backend you pick before you commit to the design.

Which parts of an OpenBao HA cluster fail most often in practice?

Teams tend to have trouble in a few areas: unseal keys that are not stored or assigned clearly, too few nodes to keep a quorum after one failure, TLS certificates that expire or are configured inconsistently across nodes, load balancers that send traffic to the wrong node, and backups that have never been restored. Each of these can be tested before go-live. Ask for a test plan that covers a leader failover, a node loss, a certificate rotation and a full restore into a clean environment, with a recorded result for each.

How DeployOpen scopes, builds and hands over OpenBao HA

DeployOpen plans, implements, hardens, documents and supports self-hosted OpenBao inside your own infrastructure, including HA clusters on integrated storage (Raft) or PostgreSQL. Engagements are fixed-scope, so the storage choice, failover tests and handover deliverables are agreed in writing before build work starts.

How we scope

Confirm the storage backend, Raft or PostgreSQL, against your operating skills and existing database platform.
Record node count, zones, load balancer design and the expected read traffic that standbys will serve.
Agree the unseal approach, backup targets and restore objectives in the written scope before any build begins.
Identify which auth methods, namespaces and applications move onto the cluster, and what is excluded.

How we build

Deploy the active and standby nodes into your accounts, data centers or air-gapped network with TLS in place.
Configure the storage backend and verify that exactly one active node holds the lock and standbys redirect or forward requests.
Enable standby read scaling where your chosen OpenBao release supports it, and test read behavior from each node.
Run scripted leader failover tests and record how clients reconnect, how long recovery takes, and what breaks.

How we hand over

Deliver the runbooks for node replacement, unseal procedures, backup and restore, and leader failover testing.
Provide restore test results from a separate environment, showing the backup set can rebuild the cluster.
Document configuration, versions, topology diagrams and the upgrade path your team will follow in production.
Walk your operators through the cluster and sign off the handover against the written deliverables list.

How we support

Offer ongoing support, upgrades and continuous testing as a retainer after handover, scoped separately in writing.
Plan rolling upgrades of Raft or PostgreSQL clusters, following the release lines you approve and retest each time.
Repeat failover and restore tests on a schedule you agree, and report changes against the original baseline.
Confirm with OpenBao release notes and your own environment before each change, since features vary by version.