> ## Documentation Index
> Fetch the complete documentation index at: https://infisical.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrating from Vault to Infisical

> Learn how to migrate resources from Vault to Infisical.

This guide helps you migrate from HashiCorp Vault to Infisical. Whether you're moving a single application or your entire secrets infrastructure, Infisical 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 Infisical. Think of it as creating a "bridge" between Vault and Infisical that you can use repeatedly.

**What you can migrate:**

* KV v1 and KV v2 secrets
* Kubernetes auth method configurations (translated to [Machine Identities](https://infisical.com/docs/documentation/platform/identities/machine-identities.md) in Infisical)
* Kubernetes secrets engine roles (translated to [Dynamic Secrets](https://infisical.com/docs/documentation/platform/dynamic-secrets/kubernetes.md) in Infisical)
* Vault policies (translated to [Infisical project roles](https://infisical.com/docs/documentation/platform/access-controls/role-based-access-controls.md))

> [!WARNING]
>
> Importing from Vault requires the `Connect` action on `App Connections` and
> the `Create` action on the relevant subjects. For example, the `Create` action
> on the `Secrets` subject at the target environment and folder path for KV
> imports, or the equivalent permission for Machine Identities, Dynamic Secrets,
> and Roles.

## Set up your Vault connection

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

**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 or create resources within your Vault instance.

> [accordion] View the complete policy
>
> ```hcl theme={"dark"}
> # 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`.

> [!NOTE]
>
> If you're running an open-source (OSS) version of Vault, you still need to define a rule for the namespace path. OSS Vault doesn't support custom namespaces, but it still has a single default namespace, `root`.

**2. Create a HashiCorp Vault App Connection in Infisical**

In Infisical, create a new App Connection of type **HashiCorp Vault** in one of two places:

* **Project > Integrations > App Connections** — the connection is only visible inside that project.
* **Integrations > App Connections** — the connection is visible across every project in the organization.

Follow the [HashiCorp Vault App Connection documentation](https://infisical.com/docs/integrations/app-connections/hashicorp-vault.md) for detailed setup instructions. When configuring authentication (Token or AppRole), make sure the credential uses the `infisical-in-platform-migration` policy you created in the previous step.

> [!NOTE]
>
> You can create more than one connection if you need to migrate from several Vault instances. The Vault namespace is not part of the connection; you pick it inline each time you import a resource.

## Migrate your resources

Once your Vault connection is configured, you'll see import options throughout Infisical 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.

### 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 secrets engine dedicated to one application.

> [!NOTE]
>
> **First time?** You'll need to [create a
> project](https://infisical.com/docs/documentation/platform/project.md) first. A project in Infisical
> typically represents a single application or microservice.

> [!WARNING]
>
> If your Vault token is restricted and can't list a mount from its root,
> Infisical discovers the available secret paths from the token's resultant ACL
> (`sys/internal/ui/resultant-acl`). Any path that contains a `+` wildcard
> (Vault's single-segment wildcard, e.g. `secret/+/db`) can't be expanded and is
> **skipped**, i.e., those secrets won't be imported. To migrate them, grant the
> token access to the explicit KV paths instead of relying on `+`.

**To import secrets from Vault:**

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

2. In the secrets view, select **Add New**, then hover over **More**

   ![Add New menu](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/platform/external-migrations/vault-in-platform/import-vault-secrets-caret.png)

3. Select **"Add from HashiCorp Vault"**

   ![Add from HashiCorp Vault under More](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/platform/external-migrations/vault-in-platform/import-vault-secrets-option.png)

4. Pick the **App Connection**, then the **Namespace**, then the **Secrets Engine** that holds the paths you want, and finally one or more entries under **Vault Secret Path**. Keys are copied using their names from Vault.

5. (Optional) Select **Preserve folder structure** to recreate each Vault path as a folder in Infisical. Leave it unchecked to copy every key from every selected path into the folder you're currently viewing.

   > [!NOTE]
   >
   > Importing without preserving the structure aborts if the same key name
   > exists in more than one selected path, and no secrets are saved. Preserving
   > the structure resolves the conflict, because each Vault path gets its own
   > folder.

6. Check the **Preview** to confirm where every secret will land, then select **"Import Secrets"**

The secrets are imported into the environment and folder path you're currently viewing. You can select up to 25 Vault paths per import.

#### Preserving your Vault folder structure

With **"Preserve folder structure"** enabled, each Vault path becomes its own [folder](https://infisical.com/docs/documentation/platform/folder.md), nested under your current path. Otherwise, all selected secrets are imported into the current folder.

The preview reflects the choice, so you can compare both before importing:

> [tab] Flattened
>
> Every key lands directly in the folder you're viewing. This import runs from
> the project root, so all six secrets collapse into `/` and the Vault path each
> one came from is shown only for reference.
>
> ![Vault import preview without preserving the folder structure](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/platform/external-migrations/vault-in-platform/import-vault-secrets-flattened.png)

> [tab] Structure preserved
>
> Each Vault path becomes a folder. This import runs from `/newww`, so
> `team-a/service-1`, `team-a/service-2`, and `team-b` are recreated beneath it,
> each holding the secrets from its own Vault path.
>
> ![Vault import preview with the folder structure preserved](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/platform/external-migrations/vault-in-platform/import-vault-secrets-preserve-structure.png)

### Migrating Kubernetes auth method

If you're using Vault's Kubernetes auth method to authenticate your pods, you can migrate this configuration to Infisical's [Machine Identities](https://infisical.com/docs/documentation/platform/identities/machine-identities.md). In Vault, you define Kubernetes roles that specify which service accounts can authenticate. In Infisical, this maps to a Machine Identity with Kubernetes authentication enabled.

**To import Kubernetes auth configuration:**

1. First, [create a Machine Identity](https://infisical.com/docs/documentation/platform/identities/machine-identities.md) in Infisical

2. Navigate to **Access Control > Machine Identities** and select the identity

3. Select **"Add Authentication Method"** and choose **Kubernetes Auth**

4. In the configuration modal, select **"Load from Vault"**

   ![Load Kubernetes Auth from Vault](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/platform/external-migrations/vault-in-platform/import-vault-kubernetes-auth-modal.png)

5. In the load modal, pick the **App Connection**, the **Vault namespace**, and the Kubernetes role

6. Select **"Load"**

   ![Kubernetes Auth Form Populated](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/platform/external-migrations/vault-in-platform/import-vault-kubernetes-auth-modal-form.png)

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

> [!NOTE]
>
> Sensitive values like service account JWTs can't 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 [Infisical Kubernetes Operator](https://infisical.com/docs/integrations/platforms/kubernetes/overview) or [Infisical SDK](https://infisical.com/docs/sdks/overview.md) 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 Infisical's [Dynamic Secrets](https://infisical.com/docs/documentation/platform/dynamic-secrets/kubernetes.md). 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. Select **Add New** and choose **Add Dynamic Secret**

3. Select **Kubernetes** as the provider

4. Select **"Load from Vault"** at the top of the form

   ![Load Kubernetes Dynamic Secret from Vault](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/platform/external-migrations/vault-in-platform/import-vault-dynamic-secret.png)

5. In the load modal, pick the **App Connection**, the **Vault namespace**, the Kubernetes secrets engine mount, and the role

6. Select **"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 can't be retrieved from Vault and must be
> manually provided in the form after loading the configuration.

> [!TIP]
>
> The same **Load from Vault** flow is also available on **Cassandra**,
> **LDAP**, and **SQL Database** dynamic secrets. Pick the App Connection, Vault
> namespace, mount, and role to pre-fill the form.

Learn more about how Dynamic Secrets work in Infisical in the [Dynamic Secrets documentation](https://infisical.com/docs/documentation/platform/dynamic-secrets/overview).

### Migrating Vault policies

Infisical can translate your Vault HCL policies into [Infisical project roles](https://infisical.com/docs/documentation/platform/access-controls/role-based-access-controls.md). The table below shows how Vault capabilities map to Infisical permissions:

| Vault Capability | Infisical 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 Infisical have different access control
> models.

**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, select **"Add from HashiCorp Vault"**

   ![Import Vault Policy Button](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/platform/external-migrations/vault-in-platform/translate-vault-policy-toggle.png)

3. In the modal, pick the **App Connection** and the **Vault namespace**

4. Either choose an existing policy from the dropdown or paste your own HCL policy

   ![Translate Vault Policy Modal](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/platform/external-migrations/vault-in-platform/translate-vault-policy-modal.png)

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.

**Example translation:**

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

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

## One-time bulk import from Vault

If you want to move an entire Vault organization into Infisical in a single shot (rather than importing resources piecemeal from inside each project) use the **Bulk Data Import** flow. It doesn't require an App Connection and is intended for initial migrations only. KV Secret Engine is the only supported resource type for bulk import; other resource types (Kubernetes auth, dynamic secrets, policies) must use the per-resource flows described above.

> [!WARNING]
>
> Bulk Data Import is restricted to **organization admins**.

**To run a bulk import:**

1. Navigate to **Integrations** and select the tab **External Migrations**
2. Select **Import** and choose **HCP Vault**
3. Fill in the import form:
   * **Gateway** (optional) — route the import through a [gateway](https://infisical.com/docs/documentation/platform/gateways/overview.md) if your Vault instance is private
   * **Vault URL** — your Vault address (e.g. `https://vault.example.com`)
   * **Vault Namespace** (optional) — leave blank for the root namespace
   * **Vault Access Token** — a token with read access to the KV mounts you want to import
   * **Project Mapping** — how Vault resources map onto Infisical projects:
     * **Key Vaults** — each KV mount becomes an Infisical project. A default `Production` environment is created per project; secret paths become folders.
     * **Namespaces** — each Vault namespace becomes a project; each KV mount inside it becomes an environment; secret paths become folders.
     * **Custom Migration** — available on request; [contact sales](https://infisical.com/talk-to-us) to discuss tailored mappings.
4. Submit the form. Infisical will run the import asynchronously and email you when it finishes (or if it fails). This may take up to 10 minutes.

## Next steps after migration

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

> [card] [Update Your Applications](https://infisical.com/docs/sdks/overview.md)
>
> Replace Vault client libraries with Infisical SDKs in your application code

> [card] [Set Up Kubernetes Integration](https://infisical.com/docs/integrations/platforms/kubernetes/overview)
>
> Use the Infisical Kubernetes Operator to inject secrets into your pods


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.