---
layout: docs
page_title: Secrets import mappings
description: Mappings lets users apply various filtering methods to secrets being imported in to Vault.
---

# Import mappings

Vault supports multiple filter types for mapping blocks. Each of the types provides a different mechanism
used to filter the scanned secrets and determine which will be imported in to Vault.


## Argument reference

Refer to the [HCL syntax](/vault/docs/import#hcl-syntax-2) for arguments common to all mapping types.

## Passthrough mapping filters

The passthrough mapping block `mapping_passthrough` allows all secrets through from the specified source to the
specified destination. For example, one use case is setting it as a base-case for imported secrets. By assigning
it the lowest priority in the import plan, all other mapping blocks will be applied first. Secrets that fail
to match any of the previous mappings will fall through to the passthrough block and be collected in a single
KVv2 location.

### Additional arguments

There are no extra arguments to specify in a `mapping_passthrough` block.

### Example

In this example, every single secret that `my-gcp-source-1` scans from GCP Secret Manager will be imported
to the KVv2 secrets engine mount defined in `my-dest-1`.

```hcl
mapping_passthrough {
  name        = "my-map-1"
  source      = "my-gcp-source-1"
  destination = "my-dest-1"
  priority    = 1
}
```

## Metadata

The metadata mapping block `mapping_metadata` allows secrets through from the specified source to the specified
destination if they contain matching metadata key-value pairs. Metadata is not supported in all external secret
management systems, and ones that do may use different terminology for metadata. For example, AWS allows tags
on secrets while [GCP](/vault/docs/import/gcpsm) allows labels.

### Additional arguments

* `tags` `(string: <required>)` - A set of key-value pairs to match on secrets from the external system. All of the specified
keys must be found on a secret and all of the values must be exact matches. Specifying a key in this mapping with
an empty value, i.e. `""`, acts as a wildcard match to the external system's key's value.

### Example

In this example, `my-map-1` will only import the secrets into the destination `my-dest-1` that contain a tag with
a key named `importable` and its value set to `true`. 

```hcl
mapping_metadata {
  name        = "my-map-1"
  source      = "my-gcp-source-1"
  destination = "my-dest-1"
  priority    = 1

  tags = {
    "importable" = "true"
  }
}
```

## Regex

The regex mapping block `mapping_regex` allows secrets through from the specified source to the specified
destination if their secret name passes a regular expression check.

### Additional arguments

* `expression` `(string: <required>)` - The regular expression used to match secrets' names from the external system.

### Example

In this example, any secret in the GCP source whose name begins with `database/` will be imported into Vault.

```hcl
mapping_regex {
  name        = "my-map-1"
  source      = "my-gcp-source-1"
  destination = "my-dest-1"
  priority    = 1
  expression  = "^database/.*$"
}
```

## Priority

Priority works in a "first match" fashion where lower values are higher priority. To explain in more detail,
consider the above metadata example with a second additional mapping.

Below are two metadata mappings. The first, `my-map-1`, has a priority of 1. This will only import the secrets
into the destination `my-dest-1` that contain both tag keys `database` and `importable`. Each of these keys' values
must also match to `users` and `true` respectively. The second, `my-map-2`, has a priority of 2. Even though all
the secrets in the first mapping would also qualify for the second mapping's filtering rule, those secrets will only
be imported into `my-dest-1` because of `my-map-2`'s lower priority. All remaining secrets that have the tag
`importable` with a value of `true` will be imported into `my-dest-2`. 

```hcl
mapping_metadata {
  name        = "my-map-1"
  source      = "my-gcp-source-1"
  destination = "my-dest-1"
  priority    = 1

  tags = {
    "database"   = "users"
    "importable" = "true"
  }
}

mapping_metadata {
  name        = "my-map-2"
  source      = "my-gcp-source-1"
  destination = "my-dest-2"
  priority    = 2

  tags = {
    "importable" = "true"
  }
}
```