Skip to content

Infisical is the open-source platform for securing secrets, certificates, access, and AI Agents.

16.3 KB
Raw Blame
---
title: "Migrating from Vault to Infisical"
sidebarTitle: "Vault"
description: "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](/documentation/platform/identities/machine-identities) in Infisical)
- Kubernetes secrets engine roles (translated to [Dynamic Secrets](/documentation/platform/dynamic-secrets/kubernetes) in Infisical)
- Vault policies (translated to [Infisical project roles](/documentation/platform/access-controls/role-based-access-controls))

<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.
</Warning>

## 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.

<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 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 `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`.
    </Note>

  </Step>

  <Step title="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](/integrations/app-connections/hashicorp-vault) 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.
    </Note>

  </Step>
</Steps>

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

<Info>
  **First time?** You'll need to [create a
  project](/documentation/platform/project) first. A project in Infisical
  typically represents a single application or microservice.
</Info>

<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 `+`.
</Warning>

**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](/images/platform/external-migrations/vault-in-platform/import-vault-secrets-caret.png)

3. Select **"Add from HashiCorp Vault"**
   ![Add from HashiCorp Vault under More](/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.
   </Note>

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](/documentation/platform/folder), 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:

<Tabs>
  <Tab title="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](/images/platform/external-migrations/vault-in-platform/import-vault-secrets-flattened.png)

  </Tab>
  <Tab title="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](/images/platform/external-migrations/vault-in-platform/import-vault-secrets-preserve-structure.png)

  </Tab>
</Tabs>

### 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](/documentation/platform/identities/machine-identities). 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](/documentation/platform/identities/machine-identities) 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](/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](/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.
</Note>

**After importing:** You'll need to update your Kubernetes deployments to use the [Infisical Kubernetes Operator](/integrations/platforms/kubernetes/overview) or [Infisical 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 Infisical'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. 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](/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.
</Note>

<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.
</Tip>

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

### Migrating Vault policies

Infisical can translate your Vault HCL policies into [Infisical project roles](/documentation/platform/access-controls/role-based-access-controls). 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.
</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, select **"Add from HashiCorp Vault"**

   ![Import Vault Policy Button](/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](/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.
</Tip>

**Example translation:**

```hcl
# 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**.</Warning>

**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](/documentation/platform/gateways/overview) 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:

<CardGroup cols={2}>
  <Card title="Update Your Applications" icon="code" href="/sdks/overview">
    Replace Vault client libraries with Infisical SDKs in your application code
  </Card>
  <Card
    title="Set Up Kubernetes Integration"
    icon="settings"
    href="/integrations/platforms/kubernetes/overview"
  >
    Use the Infisical Kubernetes Operator to inject secrets into your pods
  </Card>
</CardGroup>