vaultr (version 1.0.2)

vault_client_kv2: Key-Value Store (Version 2)

Description

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://www.vaultproject.io/docs/secrets/kv/kv-v2.html for detailed information about this secret store.

Methods

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:

config(mount = NULL)

Arguments:

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

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:

custom_mount(mount)

Arguments:

• mount: String, indicating the path that the engine is mounted at.

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:

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.

destroy

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

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.

get

Read a secret from the vault Usage:

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.

list

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

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/

metadata_get

Read secret metadata and versions at the specified path Usage:

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.

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:

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 backends 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.

metadata_delete

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

metadata_delete(path, mount = NULL)

Arguments:

• path: Path to delete

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

put

Create or update a secret in this store. Usage:

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.

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:

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.

Details

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.

Examples

# NOT RUN {
server <- vaultr::vault_test_server(if_disabled = message)
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()
}
# }