Migrate from HashiCorp Vault to OpenBao

Moving from HashiCorp Vault to OpenBao depends on your Vault version, storage backend and integrations. This page sets out what moves cleanly, what needs rework and how to plan the cutover.

On this page

How to migrate from HashiCorp Vault to OpenBao without losing secrets

Your move to OpenBao is probably being driven by a renewal, the Business Source License change HashiCorp announced in August 2023, IBM's ownership since February 27, 2025, or a data residency requirement that a managed service cannot meet. OpenBao is an MPL 2.0 fork of Vault with a documented in-place upgrade path from Vault Community 1.14.1 on Raft storage, and almost everything else in your environment needs planning before you touch a node. The platform, security and identity teams usually own this work together: platform engineering runs the cluster and storage, security owns the unseal material and audit trail, and identity teams re-map auth mounts, roles and policies.

The short answer on effort and risk is that the in-place upgrade itself is the smaller part. The migration guide describes a node-by-node process, but OpenBao tested it only against Vault Community 1.14.1, so if you run a later Vault release or an Enterprise cluster, treat the upgrade path as unproven for your version and plan a staging rehearsal against a restored copy of production. The guide also states that mounts using plugins OpenBao does not ship are skipped, and new tokens use a shorter OpenBao format. Confirm both behaviors in your own environment before you schedule a cutover, because a skipped mount means a secret engine that stops working for a consumer.

Your inventory should therefore start with what Vault does for you, not with the binary. List every secrets engine, auth method, plugin, policy, Sentinel or Enterprise feature, and every consumer that reads from Vault, including Vault Agent, the Kubernetes injector and CI jobs that may store tokens. Ask the vendor or community to confirm the status of each item before cutover. Also confirm the exact upgrade source version on each node and the OpenBao migration guide steps for your storage backend, then rehearse the whole sequence with a rollback plan that includes a verified snapshot, since the process changes the server in place.

Which Vault features map to OpenBao and which need rework

This table maps the main Vault capabilities your team may depend on to OpenBao, marking each row as clean, needs rework or gap. Enterprise-only features are flagged for confirmation against the OpenBao docs for the exact version you plan to run. The main takeaway is that core KV, dynamic secrets and common auth methods are the usual starting point, while namespaces, HSM auto-unseal and secrets sync need an explicit check before cutover.

Vault featureStatus in OpenBaoWhat to check before migrating
KV secrets (v1 and v2)CleanConfirm secret paths, versions and metadata survive the in-place upgrade from Vault Community 1.14.1 and that clients read the same paths.
Dynamic secrets (databases and Kubernetes)Needs reworkRe-create or verify database and Kubernetes engine connections, roles and rotation settings, and confirm leases issued before the upgrade are handled as expected.
Encryption as a service (Transit)Needs reworkCheck key versions, key types and any application code that expects Vault-specific token or ciphertext behavior. Test decrypt on existing ciphertext before cutover.
Leasing and revocationCleanConfirm lease expiry and bulk revocation behave the same way in your version, and review any tooling that calls lease APIs.
Auth methods: AppRole, JWT/OIDC, Kubernetes, TLS, userpassNeeds reworkVerify auth mount configuration and role bindings. Plan for the new shorter token format wherever clients parse or store tokens.
Auth methods: LDAP and other plugin-based methodsGap until confirmedMounts using plugins OpenBao does not ship are skipped during upgrade. Inventory every mount and confirm each plugin is shipped in your target version.
PoliciesNeeds reworkReview policy files for paths and capabilities that depend on Enterprise-only features, and test each policy against a copy of the cluster.
Namespaces (Enterprise)Gap until confirmedNamespaces are documented for OpenBao, but mapping Vault Enterprise namespaces needs a separate review. Confirm the feature set in the OpenBao namespaces docs for your version.
Replication (Enterprise)Gap until confirmedConfirm which replication modes OpenBao supports in your target version and design your disaster recovery plan around the confirmed set.
HA with Raft or PostgreSQLNeeds reworkRaft and PostgreSQL are the supported HA backends. Plan the node-by-node upgrade order, storage backups and unseal procedure for your topology.
HSM auto-unseal and secrets sync (Enterprise)Gap until confirmedDo not assume Vault HSM seal or secrets sync configuration carries over. Confirm current support in the OpenBao docs and plan external processes if needed.

What changes depending on your Vault version and edition

Your starting point decides how much of this migration is a routine upgrade and how much is a project. The documented path is an in-place, node-by-node upgrade from HashiCorp Vault Community 1.14.1 on Raft storage with Shamir unseal. In that setup, each standby is replaced in turn, the active node is upgraded last, and the cluster keeps serving requests throughout. Confirm the exact steps in the OpenBao migration guide before you start, because the guide is the reference for sequencing, unseal handling and rollback.

Later Vault Community releases are a different case. The migration guide was tested only against 1.14.1, so do not assume that a cluster on a newer Community version follows the same path. Ask the OpenBao project directly whether your version is supported, and rehearse the upgrade on a copy of production data with the same storage backend, seal type and auth methods. Record the results, including any mounts that were skipped, before scheduling the production change.

Vault Enterprise and HCP Vault Dedicated clusters need the most inventory work. Enterprise features such as namespaces, replication, HSM or cloud KMS auto-unseal, and Enterprise-only secrets engines or plugins may not carry over, and the guide states that mounts using plugins OpenBao does not ship are skipped. List every mount, auth method, seal stanza and plugin in the cluster, then mark each one as supported, replaced or retired. A snapshot taken from an Enterprise cluster does not give you a safe exit path on its own, so plan the data movement separately.

Which data and integrations you have to move and rebuild

A Vault to OpenBao move has two halves: the secret data and configuration inside the cluster, and every client that reads from it. Raft snapshots only restore into the same cluster with the same unseal keys, so the data path runs through the API, while the auth, policy and client work has to be rebuilt and retested on the OpenBao side.

Secret data and KV versions

Secrets do not travel as a snapshot into a new cluster. You read them out through the Vault API, keep the KV path structure and version history where your process needs it, and write them into OpenBao. Ask who holds the export credentials, where the plaintext exists during transfer, and how you confirm each path matches after import. Treat the export as a sensitive operation with its own change record.

Auth method configuration

Auth methods such as AppRole, Kubernetes, JWT/OIDC, LDAP and TLS certificates hold their own roles, bindings and trust settings. The in-place upgrade carries them across, but any config that points at Vault-specific endpoints, certificates or service accounts must be checked against the new cluster. OpenBao recommends Userpass for developer machines and AppRole for servers, so review which methods your teams actually use.

Policies and namespaces

Policies are written in HCL and are attached to tokens and identities, so a policy that reads correctly in Vault still needs a test run in OpenBao before cutover. If you used Vault Enterprise namespaces, map each namespace to an OpenBao namespace or a path convention, because the tenant boundary and the policy paths both change. Confirm that deny rules and wildcards behave as before.

Dynamic secret roles and leases

Database, Kubernetes and other dynamic secret roles issue leases that expire and are revoked automatically. Mounts that use plugins OpenBao does not ship are skipped during migration, so every dynamic engine must be inventoried before the upgrade. Check that connection credentials for the database itself are rotated after cutover and that existing leases can be revoked cleanly if a rollback is needed.

Kubernetes auth bindings and the injector

Kubernetes auth roles bind service accounts and namespaces to Vault policies, and the Vault Agent Injector or CSI provider reads those bindings. Install the OpenBao Helm chart, which needs Helm 3.6 or later, then re-create or verify each role and the token review settings. Test a pod restart in a non-production namespace, since injected secrets only refresh when the workload reads them again.

Token format change and client re-authentication

New tokens use a shorter OpenBao format, so any code that parses, stores or matches the token string must be reviewed. Existing Vault tokens are not a reliable contract for the new cluster, so applications, Vault Agent, CI jobs and scripts need to re-authenticate through their auth method and receive new tokens. Update the VAULT_ADDR and client library settings, then confirm each consumer renews its lease and fails cleanly on expiry.

The migration sequence from inventory to decommission

This sequence moves a Vault deployment to OpenBao in controlled stages, so each change is tested before it reaches production and every step ends with a documented result. It works whether you upgrade in place or re-point clients to a new cluster.

  1. Inventory every Vault dependency

    Your platform or security team lists every secrets engine mount, plugin, auth method, policy, namespace, audit device and client that depends on the cluster. Record the Vault version, the storage backend (confirm it is Raft with Shamir unseal if you plan the documented in-place path), and any Enterprise features in use, such as namespaces, replication, HSM auto-unseal or secrets sync. Also list every application, agent and Kubernetes injector that reads from Vault. The step is complete when you have a signed-off inventory that marks each item as supported, skipped or needing a replacement.

  2. Run the pilot on a non-production cluster

    Restore a recent snapshot of your non-production Vault into a test environment and upgrade it to OpenBao using the migration guide. Check that every mount is present and that plugins OpenBao does not ship are reported as skipped, so you know what needs a replacement. Test each auth method, each policy and each dynamic secret path with real workloads. Expect that existing tokens will not carry over in the new format, so test client login and renewal flows. The pilot is done when every inventory item has a recorded test result and the owners have accepted any gaps in writing.

  3. Validate with a parallel run

    Keep production Vault as the source of truth and run OpenBao alongside it. Point a small set of non-critical clients at OpenBao, and where possible have clients read from both systems during validation to compare results. Monitor authentication failures, lease behavior, latency and audit log output in both systems. Confirm that the Kubernetes injectors, agents and CI jobs you changed behave the same as before. The parallel run is complete when a defined set of clients has run without errors for the validation window your team agreed on and the differences are explained.

  4. Cut over production clusters

    Choose the cutover path that fits your inventory. The documented route is a node-by-node in-place upgrade from Vault Community 1.14.1 on Raft, upgrading standby nodes first and the active node last, with a verified backup before each change. Other Vault versions or Enterprise clusters need the feature gap decisions from the inventory before you proceed. If you choose a new cluster instead, re-point clients in controlled batches. Track which clients now authenticate to OpenBao and confirm that reads and writes succeed after each batch. The step is complete when all production clients use OpenBao and the cluster reports healthy on every node.

  5. Decommission Vault and close out

    Once no client depends on Vault, revoke remaining Vault tokens and any leases that were not migrated, and disable access paths to the old endpoints. Retire the Vault unseal material and any HSM or cloud KMS references that only served the old cluster, after confirming your recovery procedure for OpenBao works. Archive Vault audit logs according to your retention policy so investigators can still read them. Update runbooks, the secrets inventory and your access reviews to name OpenBao as the system of record. The step is done when your security owner signs off on the archive, the revocation report and the updated runbooks.

What drives the cost and duration of the move

This table lists the factors that lengthen or shorten a Vault to OpenBao move and the cost component each one affects. Read it as a checklist: for each driver, note your current state, then use the reduction column to decide what to change before work is quoted. The main takeaway is that most effort comes from inventory, plugin and auth gaps, and change control, not from the binary swap itself.

DriverWhy it changes effort or costHow to keep it down
Secret engines and pluginsMounts using plugins OpenBao does not ship are skipped during the in-place upgrade, so each one needs a replacement or a separate export and import plan.Inventory every mount and plugin version first, then classify each as carried over, replaced or retired.
Enterprise feature useNamespaces, replication, HSM seals, secrets sync and automated snapshots depend on Vault Enterprise features that need separate design on OpenBao.List Enterprise features in use and confirm each one with the vendor or the OpenBao docs before scoping.
Number of clients, agents and workloadsEvery application, Vault Agent, script and CI job that reads secrets or uses a token format must be re-pointed and tested.Group clients by owner and auth method, then migrate in waves with a rollback path for each wave.
Kubernetes injector and Helm deploymentsInjectors, sidecars and Helm values reference Vault paths and images, and the OpenBao Helm chart requires Helm 3.6 or later.Confirm Helm version, pin chart values in version control and test injection in a non-production cluster.
Storage backend and HA designThe documented in-place path covers Vault Community 1.14.1 on Raft with Shamir unseal, so other storage or unseal designs need extra planning and testing.Record the storage backend, unseal method and node count before quoting, and treat any deviation as a separate work item.
Audit and compliance evidenceAssessors may expect records of the inventory, change approvals, test results and audit log continuity across the cutover.Agree the evidence list with your auditor before work starts, including audit device configuration and retention.
Internal change controlMaintenance windows, approvals and freeze periods set how many cutover rounds are possible and how long rollback must stay available.Book change windows early, pre-approve rollback steps and reserve staff for the cutover period.
Cost components (who is paid for what)Internal staff time and test environments are recurring project costs. A partner fee under a written scope covers planning, implementation and documentation. Infrastructure and support continue after cutover.When requesting a quote, ask for a written scope listing deliverables, assumptions, client responsibilities, support terms and separate line items for infrastructure and staff.

How the migration differs by starting point

If you run one Vault Community cluster on Raft with Shamir unseal, you are closest to the path OpenBao documents. The migration guide describes a node-by-node, in-place upgrade, and it was tested only against Vault Community 1.14.1, so your starting version matters more than anything else.

  • Version gap: confirm you run exactly 1.14.1 before following the in-place steps. Later Vault versions need their own rehearsal on a copy of your data.
  • Storage and unseal: Raft storage with Shamir unseal is the documented case. Auto-unseal through a cloud KMS or an HSM changes the steps.
  • Mounts: secrets engines and auth methods that use plugins OpenBao does not ship are skipped, so list every mount before you start.
  • Tokens: new tokens use a shorter OpenBao format, so check any code that parses token prefixes or length.

Before you schedule the upgrade, take a verified snapshot and confirm that you hold every unseal key and recovery credential.

What usually goes wrong and how to prevent it

Most failed Vault-to-OpenBao migrations do not fail during the binary swap. They fail in the details around it: mounts that were skipped, clients that still hold old tokens, and rollbacks nobody rehearsed. Each card below names one failure mode and the check that catches it before production traffic is affected.

Plugin mounts silently skipped

The OpenBao migration guide says mounts that use plugins OpenBao does not ship are skipped during the in-place upgrade. Any secrets engine or auth method your Vault cluster depends on may therefore be absent after cutover, and applications will fail on their next read. Before you start, list every mount with its plugin type and confirm each one against the plugins OpenBao documents. Treat any gap as a blocker or a planned rewrite.

Clients holding old tokens

New tokens issued by OpenBao use a shorter format, so tooling that parses, stores or validates token strings may break even when the token itself is accepted. Scan CI variables, agent sink files, application configuration and scripts for hardcoded token patterns and token length assumptions. Test one client end to end in staging, and plan a controlled re-authentication window rather than assuming existing leases will be rewritten.

Injectors and Helm values left on Vault

Kubernetes workloads often pick up the Vault address, image tag and CA bundle from Helm values, injector annotations or agent configuration that never change during a binary swap. The OpenBao Helm chart requires Helm 3.6 or later and is the recommended installation path, so render the chart and diff it against your current Vault release. Update the injector image, the service address and the TLS trust chain together, then confirm a test pod receives its secret.

Unseal keys mishandled mid-upgrade

An in-place upgrade on Shamir unseal depends on the existing unseal keys and the operators who hold them. If key shares are unavailable, stored in unclear locations or unknown to the people running the change, a node that restarts may stay sealed. Confirm the key holders, their availability and the location of each share before the first node is touched, and record who performs each unseal step during the node-by-node sequence.

Enterprise-only policies absent

If your Vault cluster uses Enterprise features such as namespaces, Sentinel policies or replication, the Community-based upgrade path does not carry those configurations forward. Access rules that depended on them can disappear without an error at cutover, which means a previously denied request may now succeed or a required one may fail. Export every policy and namespace definition, compare it with the OpenBao namespace and policy model, and test denial cases explicitly, not only successful reads.

Audit logging not verified

Audit devices are a separate configuration from the data itself, and a migration can leave one unconfigured, pointed at a missing path or writing to a volume that fills up. Without audit records you cannot show who read which secret during the change window, which matters for any compliance review. Enable a file audit device before cutover, confirm that a test read appears in the log, and check that log shipping and retention still work after the node restarts.

Rollback never rehearsed

A rollback plan that exists only on paper usually fails when it is needed. Once nodes run OpenBao, the path back to Vault is not something to assume, so take a verified storage backup before the first node is upgraded and restore it into a scratch cluster. Time the restore, confirm that the clients can reach the recovered cluster, and agree in writing on the trigger that starts a rollback.

What buyers and practitioners ask before moving from Vault to OpenBao

How much effort and cost does moving from Vault to OpenBao involve?

The cost is mostly labor and infrastructure, not a license fee. OpenBao is MPL 2.0 licensed, so the main line items are the project work (inventory, planning, cutover, testing), the infrastructure that runs the cluster, and ongoing operations. The effort rises with the number of clusters, auth methods, plugins, namespaces, pipelines and applications that read secrets. Your current Vault edition matters too: the documented in-place path starts from Vault Community 1.14.1 on Raft with Shamir unseal, so later versions or Enterprise features may need extra steps. Ask any provider for a written scope that lists each cluster, mount and integration, plus the deliverables and the testing and rollback plan, and request a quote from that scope. DeployOpen does not publish prices, so the quote follows from the written scope.

How long does a Vault to OpenBao migration take?

The duration depends on what the cluster does and how many systems depend on it. The main drivers are the number of Vault nodes and whether they run the Raft storage and Shamir unseal that the migration guide describes, the number of mounts that use plugins OpenBao does not ship, the count of applications, agents and Kubernetes injectors that must be re-pointed, and how many change windows your organization allows. Teams also need time for a non-production rehearsal and a rollback plan. No duration is given here because none has been researched for this page. Ask for a timeline in the written scope, with milestones for discovery, rehearsal, production cutover and post-cutover checks.

Can our internal team migrate Vault to OpenBao without outside help?

A capable platform team can do it, especially for a small, standard cluster that already matches the documented upgrade path. The work is most risky where the setup departs from that path. The OpenBao migration guide says it was tested only against Vault Community 1.14.1 on Raft with Shamir unseal, and it skips mounts that use plugins OpenBao does not ship. Before deciding, check whether your cluster is on that version, which storage and seal you use, and which auth methods and secrets engines you rely on. Teams often bring in an outside implementation partner for the inventory, the rehearsal and the cutover, while keeping day-to-day ownership in-house.

What skills and staff time does the migration need?

Plan for people who understand Vault policies, auth methods, token handling and high availability, and people who own each application that reads secrets. The platform side needs experience with Linux service management, TLS, storage backends and the Helm chart if you run on Kubernetes, which requires Helm 3.6 or later. Security and compliance staff should review access policies, audit logging and the seal and unseal process. Application owners must test their clients against OpenBao before cutover. Because new tokens use a shorter OpenBao format, anything that parses or stores token formats needs a check. Identify these owners early so they can commit time during the change windows.

Does OpenBao support the Vault features we use?

OpenBao covers the core: encrypted key/value storage, dynamic secrets for systems such as Kubernetes and SQL databases, encryption as a service, leasing with automatic revocation, and bulk revocation. Its documented auth methods include AppRole, JWT/OIDC, Kerberos, Kubernetes, LDAP, RADIUS, TLS certificates, tokens and username and password, plus login MFA. Namespaces, replication and other Enterprise features need separate checks. Build a feature inventory from your current configuration and compare each item against the OpenBao docs. Mounts that use plugins OpenBao does not ship will be skipped during the in-place upgrade, so each one needs a replacement or a decision to retire it. Confirm each gap with the vendor and your own test cluster before you rely on it.

Can we move secrets to OpenBao without the original Vault cluster?

Yes, but the route depends on what you move. The documented path is an in-place, node-by-node upgrade, which keeps the existing data and the cluster. Moving to a new cluster means reading secrets out through the API and rebuilding auth methods, policies and mounts, because a Raft snapshot only restores into the same cluster with the same unseal keys. Secret values, policies and auth configuration each need a separate export plan, and dynamic secret configurations need their own review. Ask your provider how they will verify that every secret and policy arrived intact, how the old and new systems will run side by side, and how the original cluster will be decommissioned once cutover is complete.

What is the token format change and how does it affect our clients?

New tokens issued by OpenBao use a shorter format than Vault tokens. Clients that treat tokens as opaque strings will usually keep working, but any code that parses, validates by length or pattern, or stores tokens in a fixed-size field needs review. Agents, sidecars and Kubernetes injectors also hold tokens and renew leases, so test their renewal and re-authentication paths in a rehearsal. Ask for an inventory of every client that handles tokens, and confirm the behavior of existing tokens across the upgrade in the OpenBao migration guide and your own test environment before production cutover.

What a fixed-scope migration engagement covers

A DeployOpen migration starts with a written scope, agreed before any work begins. For a move from Vault to OpenBao, that scope usually opens with an inventory: which Vault version and edition you run, whether storage is integrated Raft, which auth methods, policies, secrets engines and plugins are mounted, and which clients depend on them, including applications using the Vault API, Vault Agent, and Kubernetes injectors. The inventory matters because OpenBao's migration guide describes an in-place, node-by-node upgrade from Vault Community 1.14.1 on Raft with Shamir unseal, and it was tested only against that version. It also skips mounts that use plugins OpenBao does not ship. Ask for the inventory deliverable to list every mount that would be skipped, so the gap is known before cutover rather than discovered after it.

The remaining deliverables follow the same order. A pilot moves one non-critical path, such as a single KV mount and its AppRole or Kubernetes auth, to confirm that the new token format and client configuration work. A parallel run keeps Vault serving production while OpenBao handles the same reads in a test environment, so the team can compare results. Cutover is scheduled with a rollback plan that names who decides to revert and what state is preserved. Decommissioning covers revoking the old Vault tokens, removing stale policies, retiring unseal key holders and archiving evidence for your assessors. Each stage needs your staff to own the decisions on change windows, identity sources and the infrastructure that hosts the nodes. Confirm with DeployOpen which of these tasks falls to your team and which to the engagement.

Support after cutover can be arranged as a retainer for ongoing upgrades, patching of OpenBao releases such as the security fixes in the current releases page, and continuous testing. A retainer is separate from the fixed-scope migration and is quoted on its own terms. DeployOpen does not publish a price list. A quote follows from the written scope, so ask for line items for the inventory, each environment, the cutover window and any retainer, and ask how changes to scope during the project are priced and approved before they are made.

How DeployOpen runs a Vault to OpenBao migration

DeployOpen plans, implements, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure, so an OpenBao migration is scoped, built and handed over in writing before any cluster is touched. Engagements are fixed-scope, with the scope, deliverables and timeline agreed in advance.

How we scope

  • We confirm your exact Vault version, storage backend and whether you run Community or Enterprise before quoting.
  • We inventory secrets engines, auth methods, plugins and clients to identify which mounts OpenBao will skip.
  • We record the agreed scope, deliverables and timeline in writing, with ongoing support available as a retainer.

How we build

  • We rehearse the node-by-node in-place upgrade in a non-production copy of your cluster first.
  • We re-point Vault Agent, application clients and Kubernetes injectors and test the new token format in each one.
  • We harden the OpenBao deployment, including seal configuration, access policies and audit logging, before cutover.

How we hand over

  • We document the upgrade runbook, rollback steps, skipped plugin inventory and each client change.
  • We deliver test evidence and control documentation that your internal teams or independent auditors can review.
  • We train your operators on day-to-day administration, upgrades and backups of the OpenBao cluster.

How we support

  • We can provide upgrades and patch support for new OpenBao releases under a retainer agreed in writing.
  • We can run continuous security testing of the cluster and its integrations as an optional ongoing service.
  • We confirm with you which compliance evidence your assessors need, since DeployOpen prepares evidence but does not issue attestations.

Talk to our team.

Tell us what you're working on, whether it's a deployment, an audit, a security test or a cyber range. You'll speak with an engineer who can help you scope it.

  • 30-minute call: free, with no obligation.
  • NDA on request: we can sign before you share details.
  • Clear next steps: a scope and plan after the call.