vault_client_kv2: Key-Value Store (Version 2)
In vaultr: Vault Client for Secrets and Sensitive Data
vault_client_kv2 R Documentation
Key-Value Store (Version 2)
Description
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_clientA vault_api_client object
mountMount 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
mountCustom 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
mountString, 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
pathPath to delete
versionOptional 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.
mountCustom 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
pathPath to delete
versionVersion numbers to delete, as a vector of
integers (this is required)
mountCustom 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
pathPath of the secret to read
versionOptional version of the secret to read. If
NULL (the default) then the most recent version is read.
Otherwise this must be a scalar integer.
fieldOptional 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.
metadataLogical, 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.
mountCustom 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
pathThe path to list
full_namesLogical, indicating if full paths (relative
to the vault root) should be returned.
mountCustom mount path to use for this store (see Details).
valueA 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
pathPath of secret to read metadata for
mountCustom 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
pathPath of secret to update metadata for
cas_requiredLogical, 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_versionsInteger, 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.
mountCustom 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
pathPath to delete
mountCustom 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
pathPath for the secret to write, such as
/secret/mysecret
dataA named list of values to write into the vault at
this path.
casInteger, 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.
mountCustom 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
pathThe path to undelete
versionInteger vector of versions to undelete
mountCustom mount path to use for this store (see Details).
Examples
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()
}
vaultr documentation built on Nov. 9, 2023, 5:07 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| vault_client_kv2 | R Documentation |
Key-Value Store (Version 2)
Description
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_clientA vault_api_client object
mountMount 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
mountCustom 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
mountString, 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
pathPath to delete
versionOptional version to delete. If
NULL(the default) then the latest version of the secret is deleted. Otherwise,versioncan be a vector of integer versions to delete.mountCustom 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
pathPath to delete
versionVersion numbers to delete, as a vector of integers (this is required)
mountCustom 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
pathPath of the secret to read
versionOptional version of the secret to read. If
NULL(the default) then the most recent version is read. Otherwise this must be a scalar integer.fieldOptional 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.metadataLogical, indicating if we should return metadata for this secret (lease information etc) as an attribute along with the values itself. Ignored if
fieldis specified.mountCustom 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
pathThe path to list
full_namesLogical, indicating if full paths (relative to the vault root) should be returned.
mountCustom mount path to use for this store (see
Details).valueA 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
pathPath of secret to read metadata for
mountCustom 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
pathPath of secret to update metadata for
cas_requiredLogical, indicating that if If true the key will require the cas parameter to be set on all write requests (see
put). IfFALSE, the backend's configuration will be used.max_versionsInteger, 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.
mountCustom 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
pathPath to delete
mountCustom 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
pathPath for the secret to write, such as
/secret/mysecretdataA named list of values to write into the vault at this path.
casInteger, 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.
mountCustom 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
pathThe path to undelete
versionInteger vector of versions to undelete
mountCustom mount path to use for this store (see
Details).
Examples
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()
}
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.