mirror of
https://github.com/hanzoai/kms.git
synced 2026-10-17 11:18:16 +00:00
zeekay
0ebffbd529
- Fix 381 files where branding script corrupted variable names (e.g. isHanzo KMSTemplate -> isKmsTemplate) - Rebrand from "Hanzo KMS" to just "KMS" for white-label support (allows Lux KMS, Hanzo KMS, etc. via configuration) - 856 files, purely string replacements, no logic changes
288 lines
12 KiB
Plaintext
288 lines
12 KiB
Plaintext
---
|
|
title: "Migrating from Vault to KMS"
|
|
sidebarTitle: "Vault"
|
|
description: "Learn how to migrate resources from Vault to KMS."
|
|
---
|
|
|
|
This guide helps you migrate from HashiCorp Vault to KMS. Whether you're moving a single application or your entire secrets infrastructure, 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 KMS. Think of it as creating a "bridge" between Vault and KMS that you can use repeatedly.
|
|
|
|
**What you can migrate:**
|
|
- KV v1 and KV v2 secrets
|
|
- Kubernetes auth method configurations (become [Machine Identities](/documentation/platform/identities/machine-identities) in KMS)
|
|
- Kubernetes secrets engine roles (become [Dynamic Secrets](/documentation/platform/dynamic-secrets/kubernetes) in KMS)
|
|
- Vault policies (translated to [KMS project roles](/documentation/platform/access-controls/role-based-access-controls))
|
|
|
|
<Warning>
|
|
**Organization Admin Access Required:** All in-platform migration features
|
|
(importing secrets, Kubernetes configurations, and policies from Vault) are
|
|
only accessible to organization admins.
|
|
</Warning>
|
|
|
|
## Set Up Your Vault Connection
|
|
|
|
Before importing anything, you need to establish a secure connection between KMS and your Vault instance. This is a one-time setup.
|
|
|
|
<Steps>
|
|
<Step title="Create a Vault policy">
|
|
In your Vault instance, create a policy that allows KMS to read your secrets, policies, and authentication configurations. This policy grants read-only access and doesn't allow KMS to modify or create resources within your Vault instance.
|
|
|
|
<Accordion title="View the complete policy">
|
|
```hcl
|
|
# 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"]
|
|
}
|
|
```
|
|
</Accordion>
|
|
|
|
Save this policy in Vault with the name `kms-in-platform-migration`.
|
|
|
|
</Step>
|
|
|
|
<Step title="Create an App Connection in KMS">
|
|
In KMS, navigate to **Organization Settings > App Connections** and create a new HashiCorp Vault connection.
|
|
|
|
Follow the [HashiCorp Vault App Connection documentation](/integrations/app-connections/hashicorp-vault) for detailed setup instructions. When configuring authentication (Token or AppRole), make sure it uses the `kms-in-platform-migration` policy you created.
|
|
|
|
</Step>
|
|
|
|
<Step title="Add Vault Namespaces for Migration">
|
|
Navigate to **Organization Settings > External Migrations** in KMS.
|
|
|
|
Under the "In-Platform Migration Tooling" section for HashiCorp Vault, click **"+ Add Namespace"**.
|
|
|
|
|
|
|
|
Configure your namespace:
|
|
|
|
|
|
|
|
- **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.
|
|
|
|
<Note>
|
|
You can add multiple namespaces with different connections if you have multiple Vault instances or namespaces to migrate from.
|
|
</Note>
|
|
|
|
</Step>
|
|
</Steps>
|
|
|
|
## Migrate Your Resources
|
|
|
|
Once your Vault connection is configured, you'll see import options throughout KMS wherever relevant. The sections below cover each type of resource you can migrate.
|
|
|
|
<Tip>
|
|
**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.
|
|
</Tip>
|
|
|
|
### 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.
|
|
|
|
<Info>
|
|
**First time?** You'll need to [create a project](/documentation/platform/project) first. A project in KMS typically represents a single application or microservice.
|
|
</Info>
|
|
|
|
**To import secrets from Vault:**
|
|
|
|
1. Navigate to your project and select a specific environment (e.g., Development, Production)
|
|
2. In the secrets view, click the dropdown icon (caret) next to the **"+ Add Secret"** button
|
|
|
|
|
|
|
|
3. Select **"Add from HashiCorp Vault"**
|
|
|
|
|
|
|
|
4. Choose your Vault namespace and the secret path you want to import (e.g., `secret/app/prod`)
|
|
5. Click **"Import Secrets"**
|
|
|
|
|
|
|
|
The secrets will be imported into your current environment and folder path. If your Vault path has nested paths, you can create [folders](/documentation/platform/folder) in 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 KMS's [Machine Identities](/documentation/platform/identities/machine-identities). In Vault, you define Kubernetes roles that specify which service accounts can authenticate. In KMS, this maps to a Machine Identity with Kubernetes authentication enabled.
|
|
|
|
**To import Kubernetes auth configuration:**
|
|
|
|
1. First, [create a Machine Identity](/documentation/platform/identities/machine-identities) in KMS
|
|
2. Navigate to **Access Control > Machine Identities** and select the identity
|
|
3. Click **"Add Authentication Method"** and choose **Kubernetes Auth**
|
|
4. In the configuration modal, click **"Load from Vault"**
|
|
|
|
|
|
|
|
5. Select your Vault namespace and the Kubernetes role
|
|
6. Click **"Load"**
|
|
|
|
|
|
|
|
The authentication settings (allowed service accounts, namespaces, TTL, etc.) will be automatically populated from your Vault configuration.
|
|
|
|
<Note>
|
|
Sensitive values like service account JWTs cannot be retrieved from Vault and
|
|
must be manually provided in the form after importing the configuration.
|
|
</Note>
|
|
|
|
**After importing:** You'll need to update your Kubernetes deployments to use the [KMS Operator](/integrations/platforms/kubernetes/overview) or [KMS SDK](/sdks/overview) 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 KMS's [Dynamic Secrets](/documentation/platform/dynamic-secrets/kubernetes). 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:**
|
|
|
|
1. Navigate to your project and select an environment
|
|
2. Click **"+ Add Secret"** dropdown and choose **"Dynamic Secret"**
|
|
3. Select **Kubernetes** as the provider
|
|
4. Click **"Load from Vault"** at the top of the form
|
|
|
|
|
|
|
|
5. Select your Vault namespace, Kubernetes secrets engine mount, and role
|
|
6. 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
|
|
|
|
<Note>
|
|
Sensitive values like cluster tokens cannot be retrieved from Vault and must
|
|
be manually provided in the form after loading the configuration.
|
|
</Note>
|
|
|
|
Learn more about how Dynamic Secrets work in KMS in the [Dynamic Secrets documentation](/documentation/platform/dynamic-secrets/overview).
|
|
|
|
### Migrating Vault Policies
|
|
|
|
KMS can translate your Vault HCL policies into [KMS project roles](/documentation/platform/access-controls/role-based-access-controls). The table below shows how Vault capabilities map to KMS permissions:
|
|
|
|
| Vault Capability | KMS Permission |
|
|
|-----------------|---------------------|
|
|
| `read` | Read secrets |
|
|
| `list` | Read secrets (list is implicit with read) |
|
|
| `create` | Create secrets |
|
|
| `update` | Edit secrets |
|
|
| `delete` | Delete secrets |
|
|
|
|
<Note>
|
|
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 KMS have different access control
|
|
models.
|
|
</Note>
|
|
|
|
**To import and translate a policy:**
|
|
|
|
1. Navigate to your project, then go to **Access Control > Roles** and create or edit a role
|
|
2. In the policy configuration, click **"Add from HashiCorp Vault"**
|
|
|
|
|
|
|
|
3. Select your Vault namespace
|
|
4. Either choose an existing policy from the dropdown or paste your own HCL policy
|
|
|
|
|
|
|
|
5. Review the automatically translated KMS permissions
|
|
6. Make any adjustments and save
|
|
|
|
<Tip>
|
|
**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 KMS permissions
|
|
- Wildcards in paths are converted to glob patterns
|
|
- Secret paths are preserved for granular access control
|
|
|
|
**Example translation:**
|
|
```hcl
|
|
# Vault policy
|
|
path "secret/data/app/*" {
|
|
capabilities = ["read", "list"]
|
|
}
|
|
```
|
|
|
|
Becomes an KMS role with **read** permission on secrets in the corresponding environment/folder path.
|
|
</Tip>
|
|
|
|
## Next Steps After Migration
|
|
|
|
Once you've imported your secrets and configurations, here's how to start using them in your applications:
|
|
|
|
<CardGroup cols={2}>
|
|
<Card title="Update Your Applications" icon="code" href="/sdks/overview">
|
|
Replace Vault client libraries with KMS SDKs in your application code
|
|
</Card>
|
|
<Card title="Set Up Kubernetes Integration" icon="dharmachakra" href="/integrations/platforms/kubernetes/overview">
|
|
Use the KMS Operator to inject secrets into your pods
|
|
</Card>
|
|
</CardGroup>
|