mirror of
https://github.com/awatertrevi/infisical.git
synced 2026-09-22 13:39:35 +00:00
363 lines
13 KiB
Plaintext
363 lines
13 KiB
Plaintext
---
|
|
title: "Migrating from Vault to Infisical"
|
|
sidebarTitle: "Vault"
|
|
description: "Learn how to migrate resources from Vault to Infisical."
|
|
---
|
|
|
|
Infisical provides two approaches for migrating from HashiCorp Vault.
|
|
|
|
### Which approach should I use?
|
|
|
|
**Choose In-Platform Migration Tooling if you want to:**
|
|
|
|
- Migrate specific secrets, not everything at once
|
|
- Import secrets into existing Infisical projects
|
|
- Translate Vault policies to Infisical access controls
|
|
- Import Kubernetes authentication configurations
|
|
- Have more control over the migration process
|
|
|
|
**Choose Bulk Data Import if you want to:**
|
|
|
|
- Migrate all secrets from Vault in one go
|
|
- Automatically create new Infisical projects from your Vault structure
|
|
- Perform a one-time migration when moving entirely from Vault to Infisical
|
|
|
|
## In-Platform Migration Tooling
|
|
|
|
This migration approach lets you set up a connection to your Vault instance once, then import specific resources as needed throughout Infisical.
|
|
|
|
<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>
|
|
|
|
### Step 1: Set Up Your Vault Connection
|
|
|
|
<Steps>
|
|
<Step title="Create a Vault policy">
|
|
In your Vault instance, create a policy that allows Infisical to read your secrets, policies, and authentication configurations. This policy grants read-only access and doesn't allow Infisical to modify anything in Vault.
|
|
|
|
<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 `infisical-in-platform-migration`.
|
|
|
|
</Step>
|
|
|
|
<Step title="Create an App Connection in Infisical">
|
|
In Infisical, 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 `infisical-in-platform-migration` policy you created.
|
|
|
|
</Step>
|
|
|
|
<Step title="Add Vault Namespaces for Migration">
|
|
Navigate to **Organization Settings > External Migrations** in Infisical.
|
|
|
|
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>
|
|
|
|
### Step 2: Import Your Resources
|
|
|
|
Once your Vault connection is configured, you'll see import options throughout Infisical wherever relevant. Here's what you can import:
|
|
|
|
#### Import Secrets into a Project
|
|
|
|
You can import secrets from Vault directly into a specific environment and secret path:
|
|
|
|
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
|
|
5. Click **"Import Secrets"**
|
|
|
|
The secrets will be imported into your current environment and folder path.
|
|
|
|
#### Import Kubernetes Authentication Configurations
|
|
|
|
When setting up Kubernetes authentication for a machine identity, you can import the configuration from Vault:
|
|
|
|
1. Navigate to **Access Control > Machine Identities** and select an identity
|
|
2. Click **"Add Authentication Method"** and choose **Kubernetes Auth**
|
|
3. In the configuration modal, click **"Load from Vault"**
|
|
|
|
|
|
|
|
4. Select your Vault namespace and the Kubernetes role
|
|
5. Click **"Load"**
|
|
|
|
|
|
|
|
The authentication settings (service accounts, TTL, policies, 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>
|
|
|
|
#### Import Kubernetes Dynamic Secret Configurations
|
|
|
|
When creating a Kubernetes dynamic secret, you can import the configuration from a Vault Kubernetes secrets engine role:
|
|
|
|
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>
|
|
|
|
#### Import and Translate Access Control Policies
|
|
|
|
When configuring project role-based access control, you can import Vault HCL policies and automatically translate them to Infisical permissions.
|
|
|
|
<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 Infisical have different access control
|
|
models. Infisical will analyze path patterns and capabilities to suggest
|
|
equivalent permissions.
|
|
</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 Infisical 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 Infisical permissions
|
|
- Wildcards in paths are converted to glob patterns
|
|
- Secret paths are preserved for granular access control
|
|
|
|
Always review the translated permissions carefully, as Vault's capability-based model may not map 1:1 with Infisical's permission structure.
|
|
</Tip>
|
|
|
|
---
|
|
|
|
## Bulk Data Import
|
|
|
|
This migration approach imports all secrets from your Vault instance in one operation and automatically creates new Infisical projects based on your Vault structure.
|
|
|
|
### Understanding Project Mapping
|
|
|
|
Before starting the bulk import, you need to decide how your Vault structure will map to Infisical projects:
|
|
|
|
<Accordion title="Namespace Mapping (One Project Per Namespace)">
|
|
Each Vault namespace becomes a single Infisical project, with each KV secret engine becoming an environment within that project.
|
|
|
|
**Example:** If you have a namespace with 3 KV secret engines (`dev-secrets`, `staging-secrets`, `prod-secrets`):
|
|
|
|
- Creates: 1 Infisical project
|
|
- Environments: 3 (`dev-secrets`, `staging-secrets`, `prod-secrets`)
|
|
</Accordion>
|
|
|
|
<Accordion title="Key Vault Mapping (One Project Per KV Engine)">
|
|
Each KV secret engine becomes its own Infisical project with a single `Production` environment.
|
|
|
|
**Example:** If you have 3 KV secret engines (`dev-secrets`, `staging-secrets`, `prod-secrets`):
|
|
|
|
- Creates: 3 Infisical projects (`dev-secrets`, `staging-secrets`, `prod-secrets`)
|
|
- Each project has: 1 environment (`Production`)
|
|
</Accordion>
|
|
|
|
### How to Perform a Bulk Import
|
|
|
|
<Steps>
|
|
<Step title="Create a Vault policy for bulk import">
|
|
In your Vault instance, create a policy that allows Infisical to read all secrets and metadata. This policy grants read-only access.
|
|
|
|
<Accordion title="View the bulk import policy">
|
|
```hcl
|
|
# Allow listing secret engines/mounts
|
|
path "sys/mounts" {
|
|
capabilities = ["read", "list"]
|
|
}
|
|
|
|
# For KV v2 engines - access to both data and metadata
|
|
path "*/data/*" {
|
|
capabilities = ["read", "list"]
|
|
}
|
|
|
|
path "*/metadata/*" {
|
|
capabilities = ["read", "list"]
|
|
}
|
|
|
|
# If using Vault Enterprise - allow listing namespaces
|
|
path "sys/namespaces" {
|
|
capabilities = ["list", "read"]
|
|
}
|
|
|
|
# Cross-namespace access (Enterprise only)
|
|
path "+/*" {
|
|
capabilities = ["read", "list"]
|
|
}
|
|
|
|
path "+/sys/mounts" {
|
|
capabilities = ["read", "list"]
|
|
}
|
|
```
|
|
</Accordion>
|
|
|
|
Save this policy in Vault with the name `infisical-bulk-migration`.
|
|
|
|
</Step>
|
|
|
|
<Step title="Generate an access token">
|
|
Use the Vault CLI to generate an access token:
|
|
|
|
```bash
|
|
vault token create --policy="infisical-bulk-migration"
|
|
```
|
|
|
|
Copy the `token` value from the output - you'll need it in the next step.
|
|
|
|
</Step>
|
|
|
|
<Step title="Start the import in Infisical">
|
|
In Infisical, navigate to **Organization Settings > External Migrations**.
|
|
|
|
|
|
|
|
Under the "Bulk Data Import" section, click **"+ Import"**.
|
|
|
|
</Step>
|
|
|
|
<Step title="Select Vault as the source">
|
|
Select **HashiCorp Vault** as the migration source and click **Next**.
|
|
|
|
|
|
|
|
</Step>
|
|
|
|
<Step title="Configure and start the migration">
|
|
Fill in your Vault connection details:
|
|
|
|
|
|
|
|
- **Vault URL**: Your Vault instance URL (e.g., `https://vault.example.com`)
|
|
- **Vault Namespace**: Optional - only needed if using Vault Enterprise namespaces
|
|
- **Vault Access Token**: The token you generated in step 2
|
|
- **Project Mapping**: Choose how to structure your Infisical projects (see [Understanding Project Mapping](#understanding-project-mapping))
|
|
|
|
Click **"Import Data"** to start the migration.
|
|
|
|
<Note>
|
|
The import runs in the background and may take several minutes. You'll receive an email when it completes.
|
|
</Note>
|
|
|
|
</Step>
|
|
</Steps>
|