Secrets import

Distributing sensitive information across multiple external systems creates several challenges, including:

• Increased operational overhead.
• Increased exposure risk from data sprawl.
• Increased risk of outdated and out-of-sync information.

Using Vault as a single source of truth (SSOT) for sensitive data increases security and reduces management overhead, but migrating data from multiple and varied sources can be complex and costly.

The secrets import process helps you automate and streamline your data migration with codified import plans as HCL files. Import plans tell Vault which data to read from a given source and where to store the data in the KVv2 secrets engine:

• The source block provides credentials for connecting to the source system.
• The destination block defines target mounts in KVv2.
• The mapping block define how Vault should transform the imported data before writing the information to KVv2.

Data migration destinations

Vault stores imported secrets in a Vault KVv2 secrets engine mount. Destination blocks start with destination_vault and define the desired KVv2 mount path and an optional namespace. The combination of a path and namespace represent the exact location in your Vault instance you want the information stored.

HCL syntax

destination_vault {
  name      = "my-dest-1"
  namespace = "ns-1"
  mount     = "mount-1"
}

• name (string: <required>) - A unique name for the destination block that can be referenced in subsequent mapping blocks.

• mount (string: <required>) - The mount path for the target KVv2 instance.

• address (string) - Optional network address of the Vault server with the KVv2 secrets engine enabled. By default, the Vault client's address will be used.

• token (string) - Optional authentication token for the Vault server at the specified address. By default, the Vault client's token will be used.

• namespace (string) - Optional namespace path containing the specified KVv2 mount. By default, Vault looks for the KVv2 mount under the root namespace.

Data migration sources

Vault can import secrets from the following sources:

• GCP Secret Manager

To pull data from a source during import, Vault needs read credentials for the external system. You can provide credentials directly as part of the import plan, or use Vault to generate dynamic credentials for the importer if you already have dynamic credentials configured for the corresponding secrets engine.

HCL syntax

Source blocks start with source_<external_system> and include any connection information required by the target system or engine. For example:

source_gcp {
  name        = "my-gcp-source-1"
  credentials = "@/path/to/service-account-key.json"
}

• name (string: <required>) - A unique name for the source block that can be referenced in subsequent mapping blocks.

• credentials (string: <required>) - Path to a credential file or token with read permissions for the target system.

Depending on the source system, additional information may be required. Refer to the connection documentation for your source system to determine the full set of required fields for that system type.

Data migration mappings

Mappings glue the source and destination together and filter the migrated data to control what is imported and what is ignored. Vault currently supports the following mapping methods:

• mapping_passthrough
• mapping_metadata
• mapping_regex

HCL syntax

Mapping blocks start with mapping_<filter_type> and include a source name, destination name, and any transformations or filters that apply. For example:

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

• name (string: <required>) - A unique name for the mapping block.

• source (string: <required>) - The name of a previously-defined source block from which the data should be read.

• destination (string: <required>) - The name of a previously defined destination block to which the data should be written.

• priority (integer: <required>) - The order in which Vault should apply the mapping block during the import process. The lower the number, the higher the priority. For example, a mapping with priority 1 executes before a mapping with priority 2.

Depending on the filter type, additional fields may be required/possible. Refer to the filter documentation for the different mappings for a list of mapping-specific fields.