Migrating from Vault to Hanzo KMS

This guide helps you migrate from HashiCorp Vault to Hanzo KMS. Whether you're moving a single application or your entire secrets infrastructure, Hanzo KMS provides tooling to make the transition smooth.

Our in-platform migration tooling lets you set up a connection to your Vault instance once, then import specific resources as needed throughout Hanzo KMS. Think of it as creating a "bridge" between Vault and Hanzo KMS that you can use repeatedly.

What you can migrate:

KV v1 and KV v2 secrets

Kubernetes auth method configurations (become Machine Identities in Hanzo KMS)

Kubernetes secrets engine roles (become Dynamic Secrets in Hanzo KMS)

Vault policies (translated to Hanzo KMS project roles)

Organization Admin Access Required: All in-platform migration features (importing secrets, Kubernetes configurations, and policies from Vault) are only accessible to organization admins.

Set Up Your Vault Connection

Before importing anything, you need to establish a secure connection between Hanzo KMS and your Vault instance. This is a one-time setup.

In your Vault instance, create a policy that allows Hanzo KMS to read your secrets, policies, and authentication configurations. This policy grants read-only access and doesn't allow Hanzo KMS to modify or create resources within your Vault instance.

# System endpoints - for listing namespaces, policies, mounts, and auth methods
path "sys/namespaces" {
  capabilities = ["list"]
}

path "sys/policy" {
  capabilities = ["read", "list"]
}

path "sys/policy/*" {
  capabilities = ["read"]
}

path "sys/mounts" {
  capabilities = ["read"]
}

path "sys/auth" {
  capabilities = ["read"]
}

# KV v2 secrets - for listing and reading secrets
# Replace '+' with your actual KV v2 mount paths (e.g., "secret", "kv")
path "+/metadata/*" {
  capabilities = ["list", "read"]
}

path "+/data/*" {
  capabilities = ["read"]
}

# KV v1 secrets - for listing and reading secrets
# Replace '+' with your actual KV v1 mount paths (e.g., "secret", "kv-v1")
# WARNING: This is broad - ideally specify exact mount names
path "+/*" {
  capabilities = ["list", "read"]
}

# Kubernetes auth - for reading auth configuration and roles
path "auth/+/config" {
  capabilities = ["read"]
}

path "auth/+/role" {
  capabilities = ["list"]
}

path "auth/+/role/*" {
  capabilities = ["read"]
}

# Kubernetes secrets engine - for reading secrets engine configuration and roles
path "+/config" {
  capabilities = ["read"]
}

path "+/roles" {
  capabilities = ["list"]
}

path "+/roles/*" {
  capabilities = ["read"]
}

Save this policy in Vault with the name kms-in-platform-migration.

In Hanzo KMS, navigate to Organization Settings > App Connections and create a new HashiCorp Vault connection.

Follow the HashiCorp Vault App Connection documentation for detailed setup instructions. When configuring authentication (Token or AppRole), make sure it uses the kms-in-platform-migration policy you created.

Navigate to Organization Settings > External Migrations in Hanzo KMS.

Under the "In-Platform Migration Tooling" section for HashiCorp Vault, click "+ Add Namespace".

In-Platform Migration Tooling

Configure your namespace:

Namespace Configuration

Namespace: Enter your Vault namespace path (e.g., admin/namespace1). If you intend to use the root namespace, set the namespace value to "root".
Connection: Select the App Connection you created in the previous step.

You can add multiple namespaces with different connections if you have multiple Vault instances or namespaces to migrate from.

Migrate Your Resources

Once your Vault connection is configured, you'll see import options throughout Hanzo KMS wherever relevant. The sections below cover each type of resource you can migrate.

Migration Strategy: We recommend migrating one application at a time. Start with a non-critical application to familiarize yourself with the process, then proceed to more important services.

Migrating KV Secrets

KV secrets are imported into a specific environment (e.g., Development, Staging, Production) within a project. If you're coming from Vault, think of a project as similar to a KV secret engine dedicated to one application.

First time? You'll need to create a project first. A project in Hanzo KMS typically represents a single application or microservice.

To import secrets from Vault:

Navigate to your project and select a specific environment (e.g., Development, Production)

In the secrets view, click the dropdown icon (caret) next to the "+ Add Secret" button Add Secret Dropdown

Select "Add from HashiCorp Vault" Add Secret Dropdown

Choose your Vault namespace and the secret path you want to import (e.g., secret/app/prod)

Click "Import Secrets" Import Vault Secrets

The secrets will be imported into your current environment and folder path. If your Vault path has nested paths, you can create folders in Hanzo KMS to maintain a similar structure.

Migrating Kubernetes Auth Method

If you're using Vault's Kubernetes auth method to authenticate your pods, you can migrate this configuration to Hanzo KMS's Machine Identities. In Vault, you define Kubernetes roles that specify which service accounts can authenticate. In Hanzo KMS, this maps to a Machine Identity with Kubernetes authentication enabled.

To import Kubernetes auth configuration:

First, create a Machine Identity in Hanzo KMS

Navigate to Access Control > Machine Identities and select the identity

Click "Add Authentication Method" and choose Kubernetes Auth

In the configuration modal, click "Load from Vault" Load Kubernetes Auth from Vault

Select your Vault namespace and the Kubernetes role

Click "Load" Kubernetes Auth Form Populated

The authentication settings (allowed service accounts, namespaces, TTL, etc.) will be automatically populated from your Vault configuration.

Sensitive values like service account JWTs cannot be retrieved from Vault and must be manually provided in the form after importing the configuration.

After importing: You'll need to update your Kubernetes deployments to use the Hanzo KMS Kubernetes Operator or Hanzo KMS SDK instead of the Vault agent/sidecar.

Migrating Kubernetes Secrets Engine Roles

If you're using Vault's Kubernetes secrets engine to generate short-lived Kubernetes credentials, you can migrate these roles to Hanzo KMS's Dynamic Secrets. Both platforms support generating temporary Kubernetes service account tokens or creating temporary service accounts, so the configuration is similar.

To import a Kubernetes dynamic secret configuration:

Navigate to your project and select an environment

Click "+ Add Secret" dropdown and choose "Dynamic Secret"

Select Kubernetes as the provider

Click "Load from Vault" at the top of the form Load Kubernetes Dynamic Secret from Vault

Select your Vault namespace, Kubernetes secrets engine mount, and role

Click "Load Configuration"

The form will be automatically populated with the role's configuration including:

Cluster URL and CA certificate

Credential type (Static or Dynamic)

Service account name or Kubernetes role settings

Allowed namespaces

Token TTL values

Token audiences

Sensitive values like cluster tokens cannot be retrieved from Vault and must be manually provided in the form after loading the configuration.

Learn more about how Dynamic Secrets work in Hanzo KMS in the Dynamic Secrets documentation.

Migrating Vault Policies

Hanzo KMS can translate your Vault HCL policies into Hanzo KMS project roles. The table below shows how Vault capabilities map to Hanzo KMS permissions:

Vault Capability	Hanzo KMS Permission
`read`	Read secrets
`list`	Read secrets (list is implicit with read)
`create`	Create secrets
`update`	Edit secrets
`delete`	Delete secrets

Policy translation is best-effort and provides a starting point based on your Vault configuration. The translated permissions should be reviewed and adjusted as needed since Vault and Hanzo KMS have different access control models.

To import and translate a policy:

Navigate to your project, then go to Access Control > Roles and create or edit a role

In the policy configuration, click "Add from HashiCorp Vault" Import Vault Policy Button

Select your Vault namespace

Either choose an existing policy from the dropdown or paste your own HCL policy Translate Vault Policy Modal

Review the automatically translated Hanzo KMS permissions

Make any adjustments and save

How policy translation works:

Vault path patterns are analyzed to identify KV secret engines and environments
Vault capabilities (read, list, create, etc.) are mapped to Hanzo KMS permissions
Wildcards in paths are converted to glob patterns
Secret paths are preserved for granular access control

Example translation:

# Vault policy
path "secret/data/app/*" {
  capabilities = ["read", "list"]
}

Becomes an Hanzo KMS role with read permission on secrets in the corresponding environment/folder path.

Next Steps After Migration

Once you've imported your secrets and configurations, here's how to start using them in your applications:

Replace Vault client libraries with Hanzo KMS SDKs in your application code

Use the Hanzo KMS Kubernetes Operator to inject secrets into your pods