Secrets Import documentation

website/content/docs/commands/operator/import.mdx

@@ -0,0 +1,87 @@
+---
+layout: docs
+page_title: operator import - Command
+description: >-
+  The "operator import" command imports secrets from external systems
+  in to Vault.
+---
+
+# operator import
+
+The `operator import` command imports secrets from external systems in to Vault.
+Secrets with the same name at the same storage path will be overwritten upon import.
+
+~> **NOTE:** This has the potential to be a long-running process. Import plans can be
+written to read from as many sources as desired and each source may migrate as many
+secrets as requested based on filters. 
+
+## Examples
+
+Execute an import config file named import.hcl to generate an import plan:
+
+```shell-session
+$ vault operator import -config import.hcl plan
+```
+
+Output:
+
+<CodeBlockConfig hideClipboard>
+
+	-----------
+	Import plan
+	-----------
+	The following namespaces are missing:
+	* ns-1/
+
+	The following mounts are missing:
+	* ns-1/mount-1
+
+	Secrets to be imported from the source "my-dest-1":
+	* secret-1
+	* secret-2
+
+</CodeBlockConfig>
+
+## Configuration
+
+The `operator import` command uses a dedicated configuration file to specify the source,
+destination, and mapping rules.
+
+```hcl
+source_gcp {
+  name = "my-gcp-source-1"
+  credentials = "@/path/to/service-account-key.json"
+}
+
+destination_vault {
+  name = "my-dest-1"
+  address = "http://127.0.0.1:8200/"
+  token = "root"
+  namespace = "ns-1"
+  mount = "mount-1"
+}
+
+mapping_passthrough {
+  name = "my-map-1"
+  source = "my-gcp-1"
+  destination = "my-dest-1"
+  priority = 1
+}
+```
+
+## Usage
+
+The following flags are available for the `operator import` command.
+
+- `-config` `(string: "<import.hcl>")` - Path to the import configuration HCL file. If unspecified,
+a file named import.hcl will be automatically looked for.
+
+- `auto-approve` `(bool: <false>)` - Automatically skips the user-input requirement of "yes" when
+  running the "apply" command.
+
+- `auto-create` `(bool: <false>)` - Automatically creates any missing namespaces and mounts when
+  "running the "apply" command.
+
+- `-log-level` ((#\_log_level)) `(string: "info")` - Log verbosity level. Supported values (in
+  order of descending detail) are `trace`, `debug`, `info`, `warn`, and `error`. This can
+  also be specified via the `VAULT_LOG_LEVEL` environment variable.

website/content/docs/commands/operator/index.mdx

@@ -54,6 +54,7 @@ Usage: vault operator <subcommand> [options] [args]
 
 Subcommands:
     generate-root    Generates a new root token
+    import           Import secrets from external systems into Vault
     init             Initializes a server
     key-status       Provides information about the active encryption key
     rekey            Generates new unseal keys

website/content/docs/import/gcpsm.mdx

@@ -0,0 +1,41 @@
+---
+layout: docs
+page_title: Google Cloud Platform Secret Manager - Secrets Import Source
+description: The Google Cloud Platform Secret Manager source imports secrets from GCP to Vault.
+---
+
+# GCP import source
+
+The GCP source enables users to import secret data from GCP Secret Manager into their Vault instance. To be able
+to import secret data from here into your Vault destination, the following permissions are required:
+
+```shell-session
+"secretmanager.secrets.list",
+"secretmanager.versions.access",
+```
+
+## Argument reference
+
+* `name` - (Required) The name of the source block used to internally reference this source inside of a mapping.
+
+* `credentials` - (Optional) The path to the service account key credentials file for the service account with the ncessary
+permissions. If `credentials` is set, then `vault_mount_path` and `vault_role_name` must be unset.
+
+* `vault_mount_path` - (Optional) The Vault mount path to a preconfigured GCP secrets engine that is used to generate a
+dynamic credential for the importer to use. If `vault_mount_path` or `vault_role_name` are set, then `credentials` must be unset.
+
+* `vault_role_name` - (Optional) The Vault role's name that exists in the preconfigured GCP secrets engine mount that is
+used to generate a dynamic credential for the importer to use. If `vault_role_name` or `vault_mount_path` are set, then
+`credentials` must be unset.
+
+## Example
+
+In this example, a GCP source is defined and configured to use 
+
+```hcl
+source_gcp {
+  name = "my-gcp-source-1"
+  secrets_engine_mount = "gcp"
+  secrets_engine_role = "my-gcp-role-1"
+}
+```

website/content/docs/import/index.mdx

@@ -0,0 +1,122 @@
+---
+layout: docs
+page_title: Secrets import
+description: Secrets import allows you to safely onboard secrets from external sources into Vault KV for management.
+---
+
+
+# Secrets import
+
+<EnterpriseAlert product="vault" />
+
+@include 'alerts/beta.mdx'
+
+Having collections of secrets across various external systems can present several challenges to an organization, such as
+increased operational overhead, a greater risk of secrets sprawl, and more. Vault can offer a single source of truth (SSOT)
+solution to managing these secrets, providing increased security and reducing that overhead, yet the effort required
+to migrate all your secrets from multiple external sources into Vault can be steep. To aid in this onboarding process,
+secrets import provides a mechanism to automate it. 
+
+A secret that is imported from an external system is stored in Vault's KVv2 Secrets Engine. The import process is defined 
+an import plan, which is an HCL file. Using HCL enables users to declaratively configure which of their secrets will be read
+from an external source and where exactly they will be stored in Vault.
+
+There are three main types of HCL blocks used to configure a secrets import plan. They are source blocks, the Vault destination
+block, and mapping blocks.
+
+## Vault destinations
+
+Secrets that get imported are stored into a Vault KVv2 Secrets Engine mount. The destination will accept the mount path of
+the desired KVv2 mount and optionally a namespace. This specifies the exact location to store the secrets in. A destination
+is defined by an HCL block in the format of `destination_vault`.
+
+### HCL syntax
+
+#### Argument reference
+
+The following arguments are supported:
+
+* `name` - (Required) The name of the Vault destination block used to internally reference this destination inside of a mapping.
+
+* `address` - (Optional) The address of the Vault server with the KVv2 Secrets Engine for which the secrets will be imported into.
+
+* `token` - (Optional) A token for authentication to the Vault server located at the specified address.
+
+* `namespace` - (Optional) The name of the Vault namespace containing the specified KVv2 mount.
+
+* `mount` - (Optional) The name of the KVv2 mount in Vault for which the secrets will be imported into.
+
+#### Example
+
+An example `destination_vault` block may look like the following:
+
+```hcl
+destination_vault {
+  name = "my-dest-1"
+  address = "http://127.0.0.1:8200/"
+  token = "root"
+  namespace = "ns-1"
+  mount = "mount-1"
+}
+```
+
+## Sources
+
+Secrets can be imported from various external systems, called sources. The supported destinations are:
+* [GCP Secret Manager](/vault/docs/import/gcpsm)
+
+A source requires the credentials necessary to read the external system's secrets and their values so that it may import
+them into Vault. Either credentials to the system can be directly provided, or you can leverage Vault's capabilities to
+geneerate a dynamic secret for the importer to use if you have the corresponding secrets engine configured. A source is
+defined by an HCL block in the format of `source_<external_system>`. For example, `source_gcp` defines a source block
+for GCP Secret Manager.
+
+### HCL syntax
+
+Refer to a [specific source's documentation](#sources) for details on how to define all remaining arguments of a source
+block for that external system type.
+
+#### Example
+
+A `source_<external_system>` block may look like the following, using GCP as an example:
+
+```hcl
+source_gcp {
+  name = "my-gcp-source-1"
+  credentials = "@/path/to/service-account-key.json"
+}
+```
+
+## Mappings
+
+Mappings blocks are what glue together a source block to a destination block. The supported mapping types are:
+* [mapping_passthrough](/vault/docs/import/mappings#passthrough)
+* [mapping_metadata](/vault/docs/import/mappings#metadata)
+* [mapping_regex](/vault/docs/import/mappings#regex)
+
+A mapping is where filtering logic is defined to control which secrets in the external system will be imported and which will
+be ignored. The definition of the rule depends on the type of mapping block that is being configured. Mapping blocks are
+applied in order of their given priority.
+
+Once a secret being imported matches a single mapping's rule, it cannot match to another mapping again. A mapping is defined
+by an HCL block in the format of `mapping_<filter_type>`. For example, `mapping_regex` defines a mapping block to pass
+all secrets through whose secret name passes the given regular expression.
+
+### HCL syntax
+
+See the [mapping documentation](/vault/docs/import/mappings) to see more info regarding specific mapping types and
+their arguments.
+
+#### Example
+
+A `mapping_<filter_type>` block may look like the following, using regex as an example:
+
+```hcl
+mapping_regex {
+  name = "my-map-1"
+  source = "my-gcp-source-1"
+  destination = "my-dest-1"
+  priority = 1
+  expression = "^database/.*$"
+}
+```

website/content/docs/import/mappings.mdx

@@ -0,0 +1,119 @@
+---
+layout: docs
+page_title: Secrets import mappings
+description: Mappings lets users apply various filtering methods to secrets being imported in to Vault.
+---
+
+# Import mappings
+
+There are multiple types of mapping blocks that can be defined in the import plan. Each type enables a
+different mechanism for filtering out secrets from an external system during the execution of an import.
+
+## Argument reference
+
+All types of mapping blocks, no matter the type, have four shared arguments:
+
+* `name` - (Required) The name of the mapping block used internally to track secrets imported from a source to a destination.
+
+* `source` - (Required) The name of the source block for which this mapping's filter logic will be applied to.
+
+* `destination` - (Required) The name of the Vault destination block for which this mapping will place the matching secrets into.
+
+* `priority` - (Required) Controls the order in which multiple mapping blocks will be applied to the secrets being imported. The
+lower the value specified, the higher the priority will be during filtering.
+
+## Passthrough
+
+Passthrough mapping blocks `mapping_passthrough` allow all secrets through from the specified source to the
+specified destination. For example, one use case is using 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 bucket.
+
+### 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` is reads 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
+
+Metadata mapping blocks `mapping_metadata` allow 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
+manageement 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` - (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. A key with an empty value, i.e. `""`,
+must also match an empty value from the external system.
+
+### Example
+
+In this example, there 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 to be imported. The second, `my-map-2`, has a
+priority of 2. Even though all the secrets in the first map would also qualify for the second map's filtering rule,
+those secrets will only be imported into `my-dest-1` because of the lower priority set in the second mapping. 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"
+  }
+}
+```
+
+## Regex
+
+Regex mapping blocks `mapping_regex` allow secrets through from the specified source to the specified
+destination if their secret name passes a regular expression check.
+
+### Additional arguments
+
+* `expression` - (Required) A regular expression to match secrets names from the external system. All of
+the specified keys must be found on a secret and all of the values must be exact matches. A key with an empty
+value, e.g. `""`, must also match an empty value 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/.*$"
+}
+```