Skip to content

Import

vkv import tries to determine the path from the input, if that is not possible you can specify on using --path|--engine-path.

vkv import accepts vkvs YAML or JSON output (vkv export -f=yaml|json) either by invoking vkv import - (for STDIN) or by specifying a file (--file). Both the current flat format and the legacy nested format are supported.

vkv will create the specified path if the engine does not exist yet and will error if it does, unless --force is specified.

See the CLI Reference for more details on the supported flags and env vars.

Warning

Vault allows / in the name of KV engine. This makes it difficult for vkv to distinguish between directories and the KV engine name..

If your KV engine name/mount contains a / you have to specify it using --engine-path|-e, otherwise vkv will output the secrets wrong.

This also applies for any vkv import ... operations.

Info

vkv handles 3 different path arguments, specified using -e|-p

  1. root path: any normal KV mount. Use -p.
  2. engine-path: in case your KV mount contains a /. Use -e.
  3. sub path: the path to the corresponding directory within a KV mount. When using -p this is everything after the first /: e.g: kv/prod/db/; root path=kv, subpath=prod/db. In conjunction with a -e you can specify a sub-path by using -p: -e=kv/prod -p=db.

Example Usage

> vkv export -p secret -f=yaml > secret_export.yaml
> vkv import -p copy --file=secret_export.yaml
reading secrets from secret_export.yaml
parsing secrets from YAML
writing secret "copy/admin"
writing secret "copy/demo"
writing secret "copy/sub/demo"
writing secret "copy/sub/sub2/demo"
successfully imported all secrets

result:

copy/ [type=kv2]
├── admin [v=1] (created 5 seconds ago)
│   └── sub=********
├── demo [v=1] (created 5 seconds ago)
│   └── foo=***
└── sub
    ├── demo [v=1] (created 5 seconds ago)
    │   ├── demo=***********
    │   ├── password=*******
    │   └── user=*****
    └── sub2
        └── demo [v=1] (created 5 seconds ago)
            ├── foo=***
            ├── password=********
            └── user=****

Note

vkv import writes secret data only — it does not restore secret versions or custom metadata. To capture the full version history, use vkv export --all-versions or snapshots.

Reading secrets from STDIN

The - in vkv import -, tells vkv do read data via STDIN. The idea of vkv import - is, in order to copy/mirror KV-v2 secrets or complete engines across different Vault Servers or Namespaces, you can simply pipe vkvs output into the vkv import command:

# yaml/json always export real (unmasked) values, so the secrets are copied intact.
vkv export -p <source> -f=yaml | vkv import - -p <destination>

A few notes:

  • <source> and <destination> don't have to be the root path of a secret engine, you also specify sub paths and copy them another secret engine.
  • vkv will error if the secret engine already exists, you can use --force to overwrite the destination engine, if the destination path contains a subpath (root/sub), vkv will then insert the secrets to that specific directory

⚠️ vkv import can overwrite important secrets, always double check the command by using the dry-run mode (--dry-run) first