What a Vault to OpenBao migration involves
OpenBao is an open source, community-driven secrets manager and fork of Vault. Its repository is licensed under MPL-2.0 and is led by a community run under open-governance principles, with the project hosted as a Sandbox project of the Open Source Security Foundation under Linux Foundation stewardship. The documented migration path replaces the Vault server process on each node in place, with configuration, endpoints and URLs left unchanged. That means the work is a binary and service swap across the cluster, not a rebuild of secrets, policies or client integrations.
The guide was tested only against Vault 1.14.1 community edition. It was not tested against Vault Enterprise, and it does not cover newer Vault releases. If your cluster runs a different Vault version or an Enterprise edition, treat the guide as a starting point and run your own compatibility check on a copy of the cluster before planning a production window. Confirm the Vault version, edition, storage backend and any enabled features against the migration guide, and ask the OpenBao community or your own engineers which steps still apply.
Teams usually cite a few reasons for moving: a preference for MPL-2.0 licensing and open governance, a need for community-led software they can inspect and maintain, or a wish to exit a commercial dependency. Your own reasons decide which requirements matter most, so write them down before scoping. Where the cluster is small, uses the community edition and has few dependent applications, an internal platform team with Vault experience can often run the swap. Where the cluster is large, serves many applications and teams, or depends on features that need checking, a partner can take on compatibility testing, cutover planning and rollback rehearsal.
What the migration work includes
A partner plans and executes these work packages in order, and each one produces a named deliverable your team can review before the next step starts.
Estate inventory
The inventory records the Vault version, edition, storage backend, auth methods, secrets engines, namespaces, audit devices, policies and every client that reads from the cluster. It is the baseline for each later step. Any client missing from this list is one that could break at cutover, so application owners should confirm their entries.
Compatibility report and rekey check
The compatibility report maps each feature in use against OpenBao's migration guide, which describes in-place replacement of the Vault server process on all nodes with configuration, endpoints and URLs unchanged. That guide was tested only against Vault 1.14.1 community edition, so Enterprise clusters need their own assessment. Clusters bootstrapped before Vault 1.3 may also need a rekey first.
Configuration review and diff
Each server configuration file is reviewed line by line. The required change to note is removing disable_mlock, since OpenBao stopped using mlock in 2.0.0. The configuration diff lists every change, its reason and the person who approved it, so the old and new files can be audited side by side.
Rehearsal and cutover runbook
The migration is rehearsed in a non-production environment that matches the production topology, storage backend and auth configuration. The rehearsal produces the in-place cutover runbook, which sets the order of node replacement, the health checks at each step and the test evidence that shows the rehearsal met its success criteria.
Client cutover and rollback plan
Each client's switch to the upgraded endpoint is scheduled and tested, with an owner named for every application team. The documented rollback path states the trigger conditions, the steps to restore the previous Vault binary and configuration on every node, and who may approve a rollback. The production cutover should wait until that path has been rehearsed.
Post-migration verification and handover
After cutover, verification confirms that auth methods, secrets engines, policies, audit devices and client reads and writes behave as recorded in the inventory. The handover package contains the test evidence, the final configuration diff, the runbooks and the rollback path, and the operators who will run the cluster walk through them before the work closes.
What drives migration cost and duration
This table lists the factors that change how much work a Vault to OpenBao migration takes, why each one matters and how to keep it under control before you request a quote.
| Driver | Why it matters | How to keep it down |
|---|---|---|
| Vault version and edition | OpenBao's migration guide was tested only against Vault 1.14.1 community edition. Enterprise editions and newer Vault versions need separate verification and may add steps. | Confirm your exact Vault version and edition first. Stay on the tested path if your cluster allows it, and ask for a written verification scope for anything else. |
| Storage backend | The migration guide covers in-place replacement. Integrated storage (Raft), Consul and other backends carry different migration implications that must be checked against the guide before work starts. | Document your current backend and its version. Ask the partner to confirm the backend-specific steps in the migration guide for your environment. |
| Clusters and environments | Each cluster, including production, disaster recovery and non-production, needs its own cutover plan, validation and rollback path. | Inventory every cluster and rank them by criticality. Plan lower environments first and agree which clusters need separate change windows. |
| Consuming applications and clients | Every application, pipeline and agent that reads secrets or tokens must be identified and move to OpenBao at cutover. Missed clients cause outages. | Build a client inventory from audit logs and token activity. Group clients by owner and cutover pattern so that changes are batched. |
| Namespaces and policy volume | More namespaces, policies and secrets engine mounts mean more configuration to verify and more chances for drift during the move. | Export and review policies before migration. Remove unused policies, mounts and namespaces so that less configuration has to be validated. |
| Custom plugins | Custom or third-party plugins must be confirmed as compatible with OpenBao before cutover. Unverified plugins can block the move or require rework. | List every plugin with its version and source. Ask the partner to confirm compatibility for each one as a named item in the scope. |
| Auth methods in use | AppRole, Kubernetes, JWT/OIDC, LDAP, TLS certificates and other methods each need configuration checks and may require client-side changes. | Inventory enabled auth methods and the clients that use them. Confirm which methods need reconfiguration and which can be left unchanged. |
| Audit and logging pipelines | Audit devices and log shippers must keep receiving events after cutover. Gaps can break detection rules and forensic records. | Map each audit device to its consumer. Test that events arrive in the SIEM or log platform before and after the change. |
| Compliance evidence requirements | Assessors may ask for change records, validation results, access reviews and proof of key handling. Evidence collection can add effort that the technical work does not show. | Agree the evidence list with your auditors before work starts. Ask the quote to state which artifacts DeployOpen will produce. Auditors and certification bodies, not DeployOpen, issue any assessment outcome. |
Migration phases and outputs
The sequence moves a Vault 1.14.x community cluster to OpenBao in place, with each phase closing on a written output the client keeps.
Inventory the current Vault estate
We list every Vault node, storage backend, auth method, secrets engine, audit device, policy, namespace and client that calls Vault, and confirm the exact running version. The discovery inventory is the signed-off baseline that every later phase is measured against.
Assess compatibility and version fit
We check the cluster against OpenBao's migration guide, including whether it was bootstrapped before Vault 1.3 (which may require a rekey), whether disable_mlock appears in configuration, and whether the edition is community or Enterprise. The compatibility report records each finding and the decision it leads to.
Rehearse on a copy of production configuration
We build a non-production cluster from a copy of the production configuration and data, then run the in-place replacement of the server process there. The rehearsal log records each step, its timing, errors and fixes, and it becomes the script for the production change.
Map client dependencies and design cutover
We identify every application, pipeline and operator that depends on the Vault server process, binary path, service unit or endpoint behavior, and design the sequence, maintenance window and rollback trigger for each. The cutover plan and dependency map are approved by the client before production work starts.
Perform the production cutover across all nodes
We replace the Vault server process with OpenBao on every node in the agreed order, keeping configuration, endpoints and URLs unchanged, and we follow the unseal and health checks at each node. The completed cutover record lists each node, its version and its health status.
Verify secrets access, leases and audit output
We confirm that clients can read and write secrets, that existing leases renew and revoke as expected, and that audit devices keep writing well-formed entries after the change. The verification report shows the results of each check and any open items the client must accept or fix.
Hand over runbooks and rollback instructions
We deliver the runbooks for routine operation, unseal procedures, backup and restore, and the documented rollback path with its decision criteria. The handover is complete when the client's operators have performed a walkthrough and the signed runbook set is filed with the cluster records.
Which parts teams keep in-house and which they outsource
This table compares the migration tasks a internal team usually keeps with those a partner typically takes on, along with the skills each task needs, so you can decide where to draw the line.
| Responsibility | Usually kept in-house | Usually outsourced to a partner |
|---|---|---|
| Secret owners and business sign-off | Named owners confirm which secrets, paths and mounts matter to their systems and approve the cutover window. Skills: knowledge of the business services that depend on Vault. | Partner drafts the inventory template and lists which mounts, auth methods and policies were found, for owners to review. |
| Application client testing | Application owners test their own clients against the rehearsal cluster. Skills: application testing, client library configuration and TLS settings. | Partner supplies a test checklist and scripts for common client types, but cannot know each application's behavior. |
| Change approval and production access | Internal change board approves the plan and holds production credentials and break-glass access. Skills: change management and identity administration. | Partner prepares change requests, rollback steps and evidence packs for the internal board to approve. |
| Inventory and compatibility checks | Platform engineers confirm the current Vault version, storage backend, and whether Enterprise features are in use. Skills: Vault operations and storage administration. | Partner builds inventory tooling and reviews results against the documented migration path, including the Vault 1.14.1 community edition test scope. |
| Configuration and runbook drafting | Platform team reviews changes such as removing disable_mlock and updating service units. Skills: Linux service management and TLS. | Partner drafts configuration diffs and step-by-step runbooks tailored to each node's setup. |
| Rehearsal and cutover | Internal engineers run rehearsals on a copy of the cluster and perform the production steps on each node. Skills: Vault operations, Linux service management and on-call coverage. | Partner runs or supports rehearsals, leads the cutover plan and stands by during node restarts, especially for large or multi-node clusters. |
| Evidence collection | Internal teams keep the audit logs, change records and sign-offs that show what was done and by whom. | Partner assembles evidence packs and readiness documentation. Independent auditors and certification bodies, not DeployOpen, judge whether controls are sufficient. |
What goes wrong in Vault to OpenBao projects
Most failed migrations break on assumptions that were never tested, not on the server swap itself. Each card names a failure pattern and the check that prevents it.
Assuming the 1.14.1 path applies everywhere
OpenBao's migration guide was tested only against Vault 1.14.1 community edition, not Vault Enterprise. Before planning, confirm your exact Vault edition and version, and treat any newer or Enterprise cluster as unvalidated until a rehearsal on a copy of it succeeds.
Missing the rekey requirement
Clusters bootstrapped before Vault 1.3 may need a rekey before moving to OpenBao. Check the bootstrap history of each cluster early, because a rekey changes unseal material and must be scheduled, rehearsed and recorded before the cutover window opens.
Leaving disable_mlock in configuration
OpenBao stopped using mlock in version 2.0.0, so disable_mlock must be removed from every server configuration file after the move. Diff the configuration of each node against the target template so the setting does not survive in one file or on one host.
Cutting over only some nodes
The documented path replaces the Vault server process on all nodes, with configuration, endpoints and URLs unchanged. A mixed cluster of Vault and OpenBao nodes is not the tested state, so define the cutover as one change across the cluster with a stop point you can reverse.
Unnoticed client dependencies
Applications, CI jobs and automation may depend on specific endpoints, token behavior or plugin versions that differ after the move. Inventory every caller from audit logs and client configuration, and test each one against the rehearsal cluster before the change window.
Skipping a rehearsal on realistic data
A rehearsal on an empty or synthetic cluster misses storage size, policy count, lease volume and plugin mounts that shape the real outcome. Restore a recent backup of production data into an isolated environment, run the full replacement and verify secret reads and writes before deciding on a date.
Unverified unseal and recovery material
Unseal keys and recovery keys can be stale, misrecorded or held by people who have left. Before cutover, confirm that the required threshold of keys can unseal a test copy and that recovery material is stored under your custody controls, and record the result.
Auditing the cutover only by health status
A node reporting healthy does not prove audit devices are writing correctly. After cutover, confirm that each audit device produces entries for authentication and secret access, and that your log pipeline parses the output the same way it did under Vault.
No tested rollback path
A rollback plan written on paper often fails when storage has already been changed by the new version. Define the rollback trigger, the snapshot or backup to restore, and the exact steps, then rehearse the reversal on the same copy used for the forward rehearsal.
How the migration changes by starting point
The documented path covers in-place replacement of the Vault server process on every node, with configuration, endpoints and URLs unchanged. The migration guide's testing used Vault 1.14.1 community edition, so this starting point has the most published guidance.
- What changes: the server binary is replaced on each node, one node at a time, so the cluster stays available through the sequence.
- Remove disable_mlock: OpenBao stopped using mlock in 2.0.0, so this setting must be removed from configuration.
- Verify: your exact patch level against the tested version, and that clients still reach the same endpoints after each restart.
- Confirm with: your platform team, after a rehearsal on a copy of production configuration.
Vault community versions other than 1.14.x were not part of the guide's testing, so each needs a compatibility check before any change is scheduled. Clusters bootstrapped before Vault 1.3 are a separate concern within this group.
- Newer versions: compare the auth methods, secrets engines and storage features you use against OpenBao's documentation and release notes.
- Pre-1.3 clusters: determine early whether a rekey is required, because it changes the sequence and the people who must take part.
- Storage backend: confirm that your backend is documented for OpenBao with the high availability model you run.
- Confirm with: the team that owns Vault configuration, and the approver who signs off on the compatibility report.
The migration guide's testing does not cover Vault Enterprise, so the in-place path is not a validated route for that edition. Each Enterprise feature in use needs an individual review before the plan is approved.
- Feature inventory: list every Enterprise capability your cluster relies on, then check whether OpenBao documents an equivalent and how it behaves.
- Licensing: confirm with the vendor what your contract terms allow and what stops working after a move.
- Replication and recovery: document how any replicated clusters, and their disaster recovery procedures, are sequenced and tested.
- Confirm with: the vendor relationship owner, the security architect, and a reviewer independent of the migration team.
When Vault runs in Kubernetes, in-place replacement changes how pods and images are handled. The image reference changes in the workload definition, and the rollout must respect pod disruption behavior and storage attachments.
- Image and manifest changes: update the image reference in your StatefulSet or Helm values, and review any sidecars or init containers that depend on Vault.
- Rollout order: replace one pod at a time, and confirm it unseals and rejoins the cluster before continuing.
- Storage: confirm that persistent volumes and the storage backend stay attached through each restart.
- Confirm with: the platform engineering team that owns the cluster and its deployment pipeline.
In restricted networks, the rehearsal and artifact delivery need planning before the change window opens. Binaries, container images and any packages must reach the environment through an approved route.
- Artifact delivery: transfer and verify the OpenBao binary or image through your approved channel, and record checksums or signatures as your process requires.
- Rehearsal: build a staging environment with the same isolation as production, so the test covers the same network limits.
- Dependencies: list every external call the cluster makes, such as to identity providers or key management, and confirm each is reachable from the restricted zone.
- Confirm with: the network security team and the owner of the change approval process.
What you need to provide before work starts
The migration only moves as fast as the inputs you supply, so the list below should be collected before scope is agreed. The scope itself is written and agreed before any work starts, and it records which of these inputs DeployOpen relies on and who owns each one. Start with the facts about your current cluster: read access to the Vault configuration file and the status output from every node, the exact Vault version and edition, and the storage backend with its settings. The migration guide we follow was tested only against Vault 1.14.1 community edition, so confirm that your version and edition match before anything else is planned.
Provide an inventory or export of auth methods, secrets engines, namespaces and policies, plus a list of consuming applications with a named owner for each. Ask each owner which secret paths and auth roles they use, and whether any client pins a Vault client library version. Also provide change windows, freeze periods and the names of people who approve changes. Confirm whether disable_mlock appears in any configuration file, since it must be removed for OpenBao, and whether the cluster was bootstrapped before Vault 1.3, which may require a rekey.
Provide a non-production environment that mirrors production as closely as possible, including the same storage backend, TLS setup, auth methods and a representative sample of secrets. Without it, cutover rehearsal cannot show what will break. Name the custodians who hold unseal and recovery material, and confirm they can take part in rehearsals. DeployOpen does not hold unseal keys unless you explicitly arrange that in writing, so decide custody before the first rehearsal.
Identify where audit logs are sent today and where they must continue to go after cutover, including the destination, retention and the team that reads them. Finally, name one decision owner who gives the go or no-go at cutover and who can stop the change if a rehearsal fails. Agree in advance what evidence that person needs to see, such as successful health checks, application login tests and a confirmed rollback path.
Frequently asked questions
Is migrating from HashiCorp Vault to OpenBao an in-place replacement?
Yes, for the documented path. OpenBao's migration guide replaces the Vault server process on all nodes in place, with configuration, endpoints and URLs unchanged, so applications keep their current addresses. Because every node changes in the same window, plan it as one scheduled cluster cutover. Before the window opens, take a tested backup and name the person who will run the rollback steps. Confirm the exact steps against the guide for your version.
Does the migration path support Vault Enterprise and newer Vault versions?
The guide was tested only against Vault 1.14.1 community edition, so Vault Enterprise and newer Vault releases fall outside the tested path. Confirm compatibility for your exact version and edition with OpenBao maintainers before you commit to a plan. Clusters bootstrapped before Vault 1.3 may need a rekey first. Also remove disable_mlock from configuration, since OpenBao stopped using mlock in 2.0.0. An assessment of your current version, edition and configuration is the first step in scope.
How long does a Vault to OpenBao migration take?
The schedule is set in the written scope, and no fixed duration applies to every cluster. The main drivers are your Vault version and edition, the number of clusters and environments, whether a rekey is needed, how many applications and integrations depend on the server, and the change windows your organization allows. Ask for the planned phases, the test environment and the cutover window to appear in the scope document before work starts.
What does a migration cost, and what drives the quote?
DeployOpen does not publish prices, and a quote follows from the written scope. One-time costs usually cover assessment, migration planning, the cutover work, testing and documentation. Ongoing support, upgrades and testing retainers recur only if you choose them. Cost rises with the number of clusters, version and edition gaps, rekey work, integration count and the number of environments to test. Ask each quote for its line items, its exclusions and its acceptance criteria.
Can our internal team run the migration alone, and what must we provide?
Yes, an internal team can run it if it has Vault operations experience, familiarity with your storage backend and time for testing and cutover. The documented path is public, but the work still requires a tested backup, a rollback plan and verification that every dependent client works after the change. To start, provide the current Vault version and edition, server configuration files, storage details, lists of auth methods and secrets engines, access to test and production environments, and your change calendar.
What happens to existing secrets and leases during the move?
Because the path keeps configuration and endpoints unchanged, applications keep their current addresses, but the guide's steps and your storage state determine how secrets and leases carry over. Confirm in the guide how existing tokens and dynamic secret leases are handled for your version. Inventory leases before cutover, let short-lived leases expire where practical, and verify key/value and dynamic credential reads afterward. Rollback depends on the backup taken before cutover, so confirm the restore steps in the scope.
How DeployOpen runs OpenBao migrations
DeployOpen plans and carries out the move from HashiCorp Vault to OpenBao inside your own infrastructure, starting from a written scope that names your Vault version, edition and cluster layout. The work is run as a fixed-scope engagement with agreed deliverables before any server is touched.
How we scope
- Confirm the Vault version, edition and storage backend before agreeing any migration path.
- Record which clusters, nodes, auth methods and secrets engines are in the written scope.
- Identify configuration items to change, such as disable_mlock, and any rekey needs before cutover.
- Agree in writing which deliverables, test environments and cutover windows are included.
How we build
- Rehearse the in-place replacement of the Vault server process in a staging copy of your cluster.
- Verify that configuration, endpoints and client URLs behave as documented after each step.
- Test application reads, writes, leases and token renewals against the migrated environment.
- Prepare a rollback plan and record the backup state needed to restore the original cluster.
How we hand over
- Document the cutover runbook, node-by-node steps, checks performed and observed results.
- Deliver configuration, policy and integration notes in your repositories or documentation system.
- Walk your operators through monitoring, backups, audit logs and day-two procedures.
- Confirm which gaps remain, such as Enterprise-only features or untested cluster variants.
How we support
- Offer ongoing support, upgrades and testing as a retainer after the engagement closes.
- Plan follow-up work for OpenBao minor releases and security patches within the retainer scope.
- Review changes to auth methods, storage or HA settings before they reach production.
- Ask your team which service levels and response expectations any retainer must cover.
