Static Secrets
- Step 1: Check the KV secrets engine version
- Step 2: Write secrets
- Patch the existing data
- Add custom metadata
- Step 3: Retrieve a specific version of secret
- Step 4: Specify the number of versions to keep
- Step 5: Delete versions of secret
- Step 6: Permanently delete data
- Step 7: Configure automatic data deletion
- Step 8: Check-and-Set operations
Prerequisites
To perform the tasks described in this tutorial, you need to have a Vault environment. Refer to the Getting Started tutorial to install Vault.
Policy requirements
NOTE: For the purpose of this tutorial, you can use root token to work with Vault. However, it is recommended that root tokens are only used for initial setup or in emergencies. As a best practice, use tokens with appropriate set of policies based on your role in the organization.
To perform all tasks demonstrated in this tutorial, your policy must include the following permissions:
# Write and manage secrets in key-value secrets engine
# The 'patch' capability is new in Vault 1.9
path "secret*" {
capabilities = [ "create", "read", "update", "delete", "list", "patch" ]
}
# To enable secrets engines
path "sys/mounts/*" {
capabilities = [ "create", "read", "update", "delete" ]
}
If you are not familiar with policies, complete the policies tutorial.
Step 1: Check the KV secrets engine version
(Persona: admin)
Verify that KV secrets engine is enabled and is set to version 2.
1.Display all the enabled secrets engine.
vault secrets list -detailed
You may not have access to the API based on the USER Permissions
2. Enable KV v2 at secret/.
vault secrets enable -path=secret kv-v2
3. If the KV version is version:1, upgrade it to version:2.
vault kv enable-versioning secret/
Step 2: Write secrets
To understand how the versioning works, let's write some test data.
1.Create a secret at the path secret/customer/acme with a name and contact_email.
vault kv put secret/customer/acme name="ACME Inc." \
contact_email="[email protected]"
The secret stores metadata along with the secret data. The version is an auto-incrementing number that starts at 1.
2. Create secret at the same path secret/customer/acme but with different secret data.
vault kv put secret/customer/acme customer_name="ACME Inc." \
contact_email="[email protected]"
The secret is fully replaced and the version is incremented to 2.
3. Get the secret defined at the path secret/customer/acme.
vault kv get secret/customer/acme
The output displays version 2 of the secret. Creating a secret at the same path replaces the existing data; fields are not merged together. The secret data stored in earlier versions is still accessible but it is no longer returned by default.
Patch the existing data
While vault kv put fully replaces the current version of the secret; therefore, you need to send the entire set of data including the values that remain the same. To partially update the current version of the secret, you can use vault kv patch command instead.
Use case: Think of an application that does not have read permission, but captures partial data updates. The vault kv patch command allows the application to send only the changing values to Vault.
ACL Policy: KV v2 secrets engine honors the distinction between the
createandupdatecapabilities inside ACL policies. Thepatchcapability is also supported which is used to represent partial updates whereas theupdatecapability represents full overwrites. To permit partial updates, be sure to addpatchcapability in the ACL policy.
1.Update the contact_email value to [email protected]
(current value is [email protected])
vault kv patch secret/customer/acme contact_email="[email protected]"
The patch command creates a new version of the secret which merges the fields within the secret data.
2. Read the secret at secret/customer/acme to verify the change.
vault kv get secret/customer/acme
The contact_email value is updated to [email protected], and the version is now 3.
Add custom metadata
NOTE: This section describes new feature introduced in Vault 1.9.0.
You saw that the secret's key (in this example, secret/customer/acme) has metadata associated with it. An organization may wish to add custom metadata describing further details (technical contact, mission criticality, etc.) about the secret.
1.When you are running Vault 1.9.0 or later, you can add custom metadata using custom_metadata parameter. This feature stores a map of arbitrary string-to-string valued user-provided metadata meant to describe the secret.
vault kv metadata put -custom-metadata=Membership="Platinum" secret/customer/acme
2. The -custom-metadata flag can be repeated to add multiple key-value pairs.
vault kv metadata put -custom-metadata=Membership="Platinum" \
-custom-metadata=Region="US West" secret/customer/acme
3. Now, when you read the secret, the returned secret metadata displays the custom metadata.
vault kv get secret/customer/acme
Step 3: Retrieve a specific version of secret
You may run into a situation where you need to view the secret before an update.
1.Get version 1 of the secret defined at the path secret/customer/acme.
vault kv get -version=1 secret/customer/acme
2. Get the metadata of the secret defined at the path secret/customer/acme.
vault kv metadata get secret/customer/acme
Step 4: Specify the number of versions to keep
By default, the kv-v2 secrets engine keeps up to 10 versions. Let's limit the maximum number of versions to keep to be 4.
1.Configure the secrets engine at path secret/ to limit all secrets to a maximum of 4 versions.
vault write secret/config max_versions=4
Every secret stored for this engine are set to a maximum of 4 versions.
2. Display the secrets engine configuration settings.
vault read secret/config
3. Configure the secret at path secret/customer/acme to limit secrets to a maximum of 4 versions.
vault kv metadata put -max-versions=4 secret/customer/acme
The secret can also define the maximum number of versions.
4. Create four more secrets at the path secret/customer/acme.
vault kv put secret/customer/acme name="ACME Inc." \
contact_email="[email protected]"
5. Get the metadata of the secret defined at the path secret/customer/acme.
vault kv metadata get secret/customer/acme
The metadata displays the current_version and the history of versions stored. Secrets stored at this path are limited to 4 versions. Version 1 and 2 are deleted.
6. Verify that version 1 of the secret defined at the path secret/customer/acme are deleted.
vault kv get -version=1 secret/customer/acme
Step 5: Delete versions of secret
1.Delete version 4 and 5 of the secrets at path secret/customer/acme.
vault kv delete -versions="4,5" secret/customer/acme
2. Get the metadata of the secret defined at the path secret/customer/acme.
vault kv metadata get secret/customer/acme
The metadata on versions 4 and 5 reports its deletion timestamp (deletion_time); however, the destroyed parameter is set to false.
3. Undelete version 5 of the secrets at path secret/customer/acme.
vault kv undelete -versions=5 secret/customer/acme
Step 6: Permanently delete data
1.Destroy version 4 of the secrets at path secret/customer/acme.
vault kv destroy -versions=4 secret/customer/acme
2. Get the metadata of the secret defined at the path secret/customer/acme.
vault kv metadata get secret/customer/acme
The metadata displays that Version 4 is destroyed.
3. Delete all versions of the secret at the path secret/customer/acme.
vault kv metadata delete secret/customer/acme
Step 7: Configure automatic data deletion
As of Vault 1.2, you can configure the length of time before a version gets deleted. For example, if your organization requires data to be deleted after 10 days from its creation, you can configure the K/V v2 secrets engine to do so by setting the delete_version_after parameter.
1.For demonstration, configure the secrets at path secret/test to delete versions after 40 seconds.
vault kv metadata put -delete-version-after=40s secret/test
2. Create a secret at the path secret/test.
vault kv put secret/test message="data1"
3. Again, create a secret at the path secret/test.
vault kv put secret/test message="data2"
4. Again, create a secret at the path secret/test.
vault kv put secret/test message="data3"
NOTE: You can use upper-arrow key to recover the previously executed command.
5. Get the metadata of the secret defined at the path secret/test.
vault kv metadata get secret/test
The metadata displays a deletion_time set on each version. After 40 seconds, the data gets deleted automatically. The data has not been destroyed.
6. Get version 1 of the secret defined at the path secret/test.
vault kv get -version=1 secret/test
Step 8: Check-and-Set operations
The v2 of KV secrets engine supports a Check-And-Set operation to prevent unintentional secret overwrite. When you pass the cas flag to Vault, it first checks if the key already exists.
- Display the secrets engine configuration settings.
vault read secret/config
The cas_required setting is false. The KV secrets engine defaults to disable the Check-And-Set operation.
2. Configure the secrets engine at path secret/ to enable Check-And-Set.
vault write secret/config cas_required=true
3. Configure the secret at path secret/partner to enable Check-And-Set.
vault kv metadata put -cas-required=true secret/partner
Once check-and-set is enabled, every write operation requires the cas parameter with the current version of the secret. Set cas to 0 when a secret at that path does not already exist.
4. Create a new secret at the path secret/partner.
vault kv put -cas=0 secret/partner name="Example Co." partner_id="123456789"
5. Overwrite the secret at the path secret/partner.
vault kv put -cas=1 secret/partner name="Example Co." \
partner_id="ABCDEFGHIJKLMN"
This tutorial demonstrated the versioned KV secrets engine (kv-v2) feature. To integrate the KV secrets engine into your existing application, you must implement the Vault API to accomplish that.
Alternatively, you can leverage Vault Agent which significantly reduces the amount of code change introduced to your application.