Note
Every method under the :py:attr:`Kv class's v2 attribute<hvac.api.secrets_engines.Kv>` includes a mount_point parameter that can be used to address the KvV2 secret engine under a custom mount path. E.g., If enabling the KvV2 secret engine using Vault's CLI commands via vault secrets enable -path=my-kvv2 -version=2 kv", the mount_point parameter in :py:meth:`hvac.api.secrets_engines.KvV2` methods would be set to "my-kvv2".
:py:meth:`hvac.api.secrets_engines.KvV2.configure`
Setting the default max_versions for a key/value engine version 2 under a path of kv:
import hvac
client = hvac.Client()
client.secrets.kv.v2.configure(
max_versions=20,
mount_point='kv',
)
Setting the default cas_required (check-and-set required) flag under the implicit default path of secret:
import hvac
client = hvac.Client()
client.secrets.kv.v2.configure(
cas_required=True,
)
:py:meth:`hvac.api.secrets_engines.KvV2.configure`
Reading the configuration of a KV version 2 engine mounted under a path of kv:
import hvac
client = hvac.Client()
kv_configuration = client.secrets.kv.v2.read_configuration(
mount_point='kv',
)
print('Config under path "kv": max_versions set to "{max_ver}"'.format(
max_ver=kv_configuration['data']['max_versions'],
))
print('Config under path "kv": check-and-set require flag set to {cas}'.format(
cas=kv_configuration['data']['cas_required'],
))
:py:meth:`hvac.api.secrets_engines.KvV2.read_secret_version`
Read the latest version of a given secret/path ("hvac"):
import hvac
client = hvac.Client()
secret_version_response = client.secrets.kv.v2.read_secret_version(
path='hvac',
)
print('Latest version of secret under path "hvac" contains the following keys: {data}'.format(
data=secret_version_response['data']['data'].keys(),
))
print('Latest version of secret under path "hvac" created at: {date}'.format(
date=secret_version_response['data']['metadata']['created_time'],
))
print('Latest version of secret under path "hvac" is version #{ver}'.format(
ver=secret_version_response['data']['metadata']['version'],
))
Read specific version (1) of a given secret/path ("hvac"):
import hvac
client = hvac.Client()
secret_version_response = client.secrets.kv.v2.read_secret_version(
path='hvac',
version=1,
)
print('Version 1 of secret under path "hvac" contains the following keys: {data}'.format(
data=secret_version_response['data']['data'].keys(),
))
print('Version 1 of secret under path "hvac" created at: {date}'.format(
date=secret_version_response['data']['metadata']['created_time'],
))
:py:meth:`hvac.api.secrets_engines.KvV2.create_or_update_secret`
import hvac
client = hvac.Client()
client.secrets.kv.v2.create_or_update_secret(
path='hvac',
secret=dict(pssst='this is secret'),
)
cas parameter with an argument that doesn't match the current version:
import hvac
client = hvac.Client()
# Assuming a current version of "6" for the path "hvac" =>
client.secrets.kv.v2.create_or_update_secret(
path='hvac',
secret=dict(pssst='this is secret'),
cas=5,
) # Raises hvac.exceptions.InvalidRequest
cas parameter set to 0 will only succeed if the path hasn't already been written.
import hvac
client = hvac.Client()
client.secrets.kv.v2.create_or_update_secret(
path='hvac',
secret=dict(pssst='this is secret #1'),
cas=0,
)
client.secrets.kv.v2.create_or_update_secret(
path='hvac',
secret=dict(pssst='this is secret #2'),
cas=0,
) # => Raises hvac.exceptions.InvalidRequest
Method (similar to the Vault CLI command vault kv patch) to update an existing path. Either to add a new key/value to the secret and/or update the value for an existing key. Raises an :py:class:`hvac.exceptions.InvalidRequest` if the path hasn't been written to previously.
:py:meth:`hvac.api.secrets_engines.KvV2.patch`
import hvac
client = hvac.Client()
client.secrets.kv.v2.patch(
path='hvac',
secret=dict(pssst='this is a patched secret'),
)
:py:meth:`hvac.api.secrets_engines.KvV2.delete_latest_version_of_secret`
import hvac
client = hvac.Client()
client.secrets.kv.v2.delete_latest_version_of_secret(
path=hvac,
)
:py:meth:`hvac.api.secrets_engines.KvV2.delete_secret_versions`
Marking the first 3 versions of a secret deleted under path "hvac":
import hvac
client = hvac.Client()
client.secrets.kv.v2.delete_secret_versions(
path='hvac',
versions=[1, 2, 3],
)
:py:meth:`hvac.api.secrets_engines.KvV2.undelete_secret_versions`
Marking the last 3 versions of a secret deleted under path "hvac" as "undeleted":
import hvac
client = hvac.Client()
hvac_path_metadata = client.secrets.kv.v2.read_secret_metadata(
path='hvac',
)
oldest_version = hvac_path_metadata['data']['oldest_version']
current_version = hvac_path_metadata['data']['current_version']
versions_to_undelete = range(max(oldest_version, current_version - 2), current_version + 1)
client.secrets.kv.v2.undelete_secret_versions(
path='hvac',
versions=versions_to_undelete,
)
:py:meth:`hvac.api.secrets_engines.KvV2.destroy_secret_versions`
Destroying the first three versions of a secret under path 'hvac':
import hvac
client = hvac.Client()
client.secrets.kv.v2.destroy_secret_versions(
path='hvac',
versions=[1, 2, 3],
)
:py:meth:`hvac.api.secrets_engines.KvV2.list_secrets`
Listing secrets under the 'hvac' path prefix:
import hvac
client = hvac.Client()
client.secrets.kv.v2.create_or_update_secret(
path='hvac/big-ole-secret',
secret=dict(pssst='this is a large secret'),
)
client.secrets.kv.v2.create_or_update_secret(
path='hvac/lil-secret',
secret=dict(pssst='this secret... not so big'),
)
list_response = client.secrets.kv.v2.list_secrets(
path='hvac',
)
print('The following paths are available under "hvac" prefix: {keys}'.format(
keys=','.join(list_response['data']['keys']),
))
:py:meth:`hvac.api.secrets_engines.KvV2.read_secret_metadata`
import hvac
client = hvac.Client()
hvac_path_metadata = client.secrets.kv.v2.read_secret_metadata(
path='hvac',
)
print('Secret under path hvac is on version {cur_ver}, with an oldest version of {old_ver}'.format(
cur_ver=hvac_path_metadata['data']['oldest_version'],
old_ver=hvac_path_metadata['data']['current_version'],
))
:py:meth:`hvac.api.secrets_engines.KvV2.update_metadata`
Set max versions for a given path ("hvac") to 3:
import hvac
client = hvac.Client()
client.secrets.kv.v2.update_metadata(
path='hvac',
max_versions=3,
)
Set cas (check-and-set) parameter as required for a given path ("hvac"):
import hvac
client = hvac.Client()
client.secrets.kv.v2.update_metadata(
path='hvac',
cas_required=True,
)
:py:meth:`hvac.api.secrets_engines.KvV2.delete_metadata_and_all_versions`
Delete all versions and metadata for a given path:
import hvac
client = hvac.Client()
client.secrets.kv.v2.delete_metadata_and_all_versions(
path='hvac',
)