Skip to contents

Key-Value Store (Version 2)

Source: R/vault_client_kv2.R
vault_client_kv2.Rd

Key-Value Store (Version 2)

Key-Value Store (Version 2)

Details

Interact with vault's version 2 key-value store. This is useful for storing simple key-value data that can be versioned and for storing metadata alongside the secrets (see vault_client_kv1 for a simpler key-value store, and see https://developer.hashicorp.com/vault/docs/secrets/kv/kv-v2 for detailed information about this secret store.

A kv2 store can be mounted anywhere, so all methods accept a mount argument. This is different to the CLI which lets you try and read values from any vault path, but similar to other secret and auth backends which accept arguments like -mount-point. So if the kv2 store is mounted at /project-secrets for example, with a vault client vault one could write

vault$secrets$kv2$get("/project-secrets/mysecret",
                      mount = "project-secrets")

or

kv2 <- vault$secrets$kv2$custom_mount("project-secrets")
kv2$get("mysecret")

If the leading part of of a path to secret within a kv2 store does not match the mount point, vaultr will throw an error. This approach results in more predictable error messages, though it is a little more typing than for the CLI vault client.

Super class

vaultr::vault_client_object -> vault_client_kv2

Methods

Public methods

Inherited methods

Method new()

Create a vault_client_kv2 object. Not typically called by users.

Usage

vault_client_kv2$new(api_client, mount)

Arguments

api_client

A vault_api_client object

mount

Mount point for the backend

Method config()

Fetch the configuration for this kv2 store. Returns a named list of values, the contents of which will depend on the vault version.

Usage

vault_client_kv2$config(mount = NULL)

Arguments

mount

Custom mount path to use for this store (see Details).

Method custom_mount()

Set up a vault_client_kv2 object at a custom mount. For example, suppose you mounted another copy of the kv2 secret backend at /secret2 you might use kv <- vault$secrets$kv2$custom_mount("/secret2") - this pattern is repeated for other secret and authentication backends.

Usage

vault_client_kv2$custom_mount(mount)

Arguments

mount

String, indicating the path that the engine is mounted at.

Method delete()

Delete a secret from the vault. This marks the version as deleted and will stop it from being returned from reads, but the underlying data will not be removed. A delete can be undone using the undelete method.

Usage

vault_client_kv2$delete(path, version = NULL, mount = NULL)

Arguments

path

Path to delete

version

Optional version to delete. If NULL (the default) then the latest version of the secret is deleted. Otherwise, version can be a vector of integer versions to delete.

mount

Custom mount path to use for this store (see Details).

Method destroy()

Delete a secret entirely. Unlike delete this operation is irreversible and is more like the delete operation on vault_client_kv1 stores.

Usage

vault_client_kv2$destroy(path, version, mount = NULL)

Arguments

path

Path to delete

version

Version numbers to delete, as a vector of integers (this is required)

mount

Custom mount path to use for this store (see Details).

Method get()

Read a secret from the vault

Usage

vault_client_kv2$get(
  path,
  version = NULL,
  field = NULL,
  metadata = FALSE,
  mount = NULL
)

Arguments

path

Path of the secret to read

version

Optional version of the secret to read. If NULL (the default) then the most recent version is read. Otherwise this must be a scalar integer.

field

Optional field to read from the secret. Each secret is stored as a key/value set (represented in R as a named list) and this is equivalent to using [[field]] on the return value. The default, NULL, returns the full set of values.

metadata

Logical, indicating if we should return metadata for this secret (lease information etc) as an attribute along with the values itself. Ignored if field is specified.

mount

Custom mount path to use for this store (see Details).

Method list()

List data in the vault at a give path. This can be used to list keys, etc (e.g., at /secret).

Usage

vault_client_kv2$list(path, full_names = FALSE, mount = NULL)

Arguments

path

The path to list

full_names

Logical, indicating if full paths (relative to the vault root) should be returned.

mount

Custom mount path to use for this store (see Details).

value

A character vector (of zero length if no keys are found). Paths that are "directories" (i.e., that contain keys and could themselves be listed) will be returned with a trailing forward slash, e.g. path/

Method metadata_get()

Read secret metadata and versions at the specified path

Usage

vault_client_kv2$metadata_get(path, mount = NULL)

Arguments

path

Path of secret to read metadata for

mount

Custom mount path to use for this store (see Details).

Method metadata_put()

Update metadata for a secret. This is allowed even if a secret does not yet exist, though this requires the create vault permission at this path.

Usage

vault_client_kv2$metadata_put(
  path,
  cas_required = NULL,
  max_versions = NULL,
  mount = NULL
)

Arguments

path

Path of secret to update metadata for

cas_required

Logical, indicating that if If true the key will require the cas parameter to be set on all write requests (see put). If FALSE, the backend's configuration will be used.

max_versions

Integer, indicating the maximum number of versions to keep per key. If not set, the backend's configured max version is used. Once a key has more than the configured allowed versions the oldest version will be permanently deleted.

mount

Custom mount path to use for this store (see Details).

Method metadata_delete()

This method permanently deletes the key metadata and all version data for the specified key. All version history will be removed.

Usage

vault_client_kv2$metadata_delete(path, mount = NULL)

Arguments

path

Path to delete

mount

Custom mount path to use for this store (see Details).

Method put()

Create or update a secret in this store.

Usage

vault_client_kv2$put(path, data, cas = NULL, mount = NULL)

Arguments

path

Path for the secret to write, such as /secret/mysecret

data

A named list of values to write into the vault at this path.

cas

Integer, indicating the "cas" value to use a "Check-And-Set" operation. If not set the write will be allowed. If set to 0 a write will only be allowed if the key doesn't exist. If the index is non-zero the write will only be allowed if the key's current version matches the version specified in the cas parameter.

mount

Custom mount path to use for this store (see Details).

Method undelete()

Undeletes the data for the provided version and path in the key-value store. This restores the data, allowing it to be returned on get requests. This works with data deleted with $delete but not with $destroy.

Usage

vault_client_kv2$undelete(path, version, mount = NULL)

Arguments

path

The path to undelete

version

Integer vector of versions to undelete

mount

Custom mount path to use for this store (see Details).

Examples


server <- vaultr::vault_test_server(if_disabled = message)
#> ...waiting for Vault to start
#> ...waiting for Vault to start
if (!is.null(server)) {
  client <- server$client()
  # With the test server as created by vaultr, the kv2 storage
  # engine is not enabled.  To use the kv2 store we must first
  # enable it; the command below will add it at the path /kv on
  # our vault server
  client$secrets$enable("kv", version = 2)

  # For ease of reading, create a 'kv' object for interacting with
  # the store (see below for the calls without this object)
  kv <- client$secrets$kv2$custom_mount("kv")
  kv$config()

  # The version-2 kv store can be treated largely the same as the
  # version-1 store, though with slightly different command names
  # (put instead of write, get instead of read)
  kv$put("/kv/path/secret", list(key = "value"))
  kv$get("/kv/path/secret")

  # But it also allows different versions to be stored at the same path:
  kv$put("/kv/path/secret", list(key = "s3cret!"))
  kv$get("/kv/path/secret")

  # Old versions can be retrieved still:
  kv$get("/kv/path/secret", version = 1)

  # And metadata about versions can be retrieved
  kv$metadata_get("/kv/path/secret")

  # cleanup
  server$kill()
}