Skip to main content
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.
Organization Admin Access Required: All in-platform migration features (importing secrets, Kubernetes configurations, and policies from Vault) are only accessible to organization admins.

​
Step 1: Set Up Your Vault Connection

1

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.
# 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 infisical-in-platform-migration.
2

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 for detailed setup instructions. When configuring authentication (Token or AppRole), make sure it uses the infisical-in-platform-migration policy you created.
3

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”.In-Platform Migration ToolingConfigure 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.

​
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” Import Vault Secrets
  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” Load Kubernetes Auth from Vault
  4. Select your Vault namespace and the Kubernetes role
  5. Click “Load” Kubernetes Auth Form Populated
The authentication settings (service accounts, TTL, policies, 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.

​
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 Load Kubernetes Dynamic Secret from Vault
  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
Sensitive values like cluster tokens cannot be retrieved from Vault and must be manually provided in the form after loading the configuration.

​
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.
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.
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” Import Vault Policy Button
  3. Select your Vault namespace
  4. Either choose an existing policy from the dropdown or paste your own HCL policy Translate Vault Policy Modal
  5. Review the automatically translated Infisical permissions
  6. 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 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.

​
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:
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)
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)

​
How to Perform a Bulk Import

1

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.
# 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"]
}
Save this policy in Vault with the name infisical-bulk-migration.
2

Generate an access token

Use the Vault CLI to generate an access token:
vault token create --policy="infisical-bulk-migration"
Copy the token value from the output - you’ll need it in the next step.
3

Start the import in Infisical

In Infisical, navigate to Organization Settings > External Migrations.Infisical Organization settingsUnder the “Bulk Data Import” section, click ”+ Import”.
4

Select Vault as the source

Select HashiCorp Vault as the migration source and click Next.Select Vault platform
5

Configure and start the migration

Fill in your Vault connection details:Configure Vault migration
  • 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)
Click “Import Data” to start the migration.
The import runs in the background and may take several minutes. You’ll receive an email when it completes.