Store versioned key/value secrets

1. Display all the enabled secrets engine.

   $ vault secrets list -detailed
   
   Path          Type         Accessor           ...   Options           Description
   ----          ----         --------                 -------           -----------
   cubbyhole/    cubbyhole    cubbyhole_9d52aeac ...   map[]             per-token private secret storage
   identity/     identity     identity_acea5ba9  ...   map[]             identity store
   secret/       kv           kv_2226b7d3        ...   map[version:2]    key/value secret storage
   ...
   

   The results display a table of all enabled secrets engines. One entry in the table has the Path of secret/ with the Type of kv. The Options column displays the version number.

2. Display the details of kv secrets engine enabled at sys/mounts/<name>.

   $ vault read sys/mounts/secret
   

   Example output:

   Key                        Value
   ---                        -----
   accessor                   kv_a99903ee
   config                     map[default_lease_ttl:0 force_no_cache:false max_lease_ttl:0]
   deprecation_status         supported
   description                key/value secret storage
   external_entropy_access    false
   local                      false
   options                    map[version:2]
   plugin_version             n/a
   running_plugin_version     v0.20.0+builtin
   running_sha256             n/a
   seal_wrap                  false
   type                       kv
   uuid                       d8a40382-902e-57c3-16bb-df49300a3e0f
   

   When KV secrets engine is NOT enabled, enable KV v2 secrets engine at 'secret/'

   Enable KV v2 at secret/.

   $ vault secrets enable -path=secret kv-v2
   

   If the KV version is version:1, upgrade it to version:2.

   $ vault kv enable-versioning secret/
   

Display all the enabled secrets engine.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
    --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
    $VAULT_ADDR/v1/sys/mounts | jq

Example output:

...snip...
   "secret/": {
      "accessor": "kv_f42ae9d1",
      "config": {
        "default_lease_ttl": 0,
        "force_no_cache": false,
        "max_lease_ttl": 0
      },
      "description": "key/value secret storage",
      "external_entropy_access": false,
      "local": false,
      "options": {
        "version": "2"
      },
      "seal_wrap": false,
      "type": "kv",
      "uuid": "b3ffe87c-4479-552c-7338-946deda76b39"
    },
...snip...

The results display all the enabled secrets engines. One entry in the results has the path of secret/ with the type of kv. The options displays the version number.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
    --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
    --request POST \
    --data '{ "type": "kv-v2" }' \
    $VAULT_ADDR/v1/sys/mounts/secret

$ tee payload.json <<EOF
{
  "options": {
      "version": "2"
  }
}
EOF

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
    --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
    --request POST \
    --data @payload.json \
    $VAULT_ADDR/v1/sys/mounts/secret/tune

Open a web browser and launch the Vault UI (for example, http://localhost:8200/ui) and then login.

1. Create a secret at the path secret/customer/acme with a customer_name and contact_email.

   $ vault kv put secret/customer/acme customer_name="ACME Inc." \
           contact_email="john.smith@acme.com"
   

   The following command is equivalent to the above command, but specifies the -mount parameter specifies which secrets engine to use.

   $ vault kv put -mount=secret customer/acme customer_name="ACME Inc." \
           contact_email="john.smith@acme.com"
   

   Example output:

   ====== Secret Path ======
   secret/data/customer/acme
   
   ======= Metadata =======
   Key                Value
   ---                -----
   created_time       2022-06-13T13:41:45.673767Z
   custom_metadata    <nil>
   deletion_time      n/a
   destroyed          false
   version            1
   

   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="john.smith@acme.com"
   

   Example output:

   ====== Secret Path ======
   secret/data/customer/acme
   
   ======= Metadata =======
   Key                Value
   ---                -----
   created_time       2022-06-13T13:41:45.673767Z
   custom_metadata    <nil>
   deletion_time      n/a
   destroyed          false
   version            2
   

   The secret is fully replaced and the version incremented to 2.

3. Get the secret defined at the path secret/customer/acme.

   $ vault kv get secret/customer/acme
   

   The following command is equivalent to the above command, but specifies the -mount parameter specifies which secrets engine to use.

   $ vault kv get -mount=secret customer/acme
   

   Example output:

   ====== Secret Path ======
   secret/data/customer/acme
   
   ======= Metadata =======
   Key                Value
   ---                -----
   created_time       2022-06-13T12:59:47.15049Z
   custom_metadata    <nil>
   deletion_time      n/a
   destroyed          false
   version            2
   
   ======== Data ========
   Key              Value
   ---              -----
   contact_email    jsmith@acme.com
   name             ACME Inc.
   

   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 the changing values to Vault.

1. Update the contact_email value to admin@acme.com (current value is john.smith@acme.com).

   $ vault kv patch secret/customer/acme contact_email="admin@acme.com"
   

   Example output:

   ====== Secret Path ======
   secret/data/customer/acme
   
   ======= Metadata =======
   Key                Value
   ---                -----
   created_time       2022-06-13T13:40:17.992243Z
   custom_metadata    <nil>
   deletion_time      n/a
   destroyed          false
   version            6
   

   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
   ====== Secret Path ======
   secret/data/customer/acme
   
   ======= Metadata =======
   Key                Value
   ---                -----
   created_time       2022-06-13T13:41:45.673767Z
   custom_metadata    <nil>
   deletion_time      n/a
   destroyed          false
   version            3
   
   ======== Data ========
   Key              Value
   ---              -----
   contact_email    john.smith@acme.com
   customer_name    ACME Inc.
   

   The contact_email value is now admin@acme.com, and the version is now 3.

Add custom metadata

You saw that the secret's key (in this example, secret/customer/acme) has metadata associated with it. An organization may want to add custom metadata describing further details (technical contact, mission criticality, etc.) about the secret.

1. 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
   Success! Data written to: secret/metadata/customer/acme
   

2. You can repeat the -custom-metadata flag to add multiple key-value pairs.

   $ vault kv metadata put -custom-metadata=Membership="Platinum" \
       -custom-metadata=Region="US West" secret/customer/acme
   

   Output:

   Success! Data written to: secret/metadata/customer/acme
   

3. When you read the secret, the returned secret metadata displays the custom metadata.

   $ vault kv get secret/customer/acme
   

   Example output:

   ====== Secret Path ======
   secret/data/customer/acme
   
   ======= Metadata =======
   Key                Value
   ---                -----
   created_time       2022-06-13T13:41:45.673767Z
   custom_metadata    map[Membership:Platinum Region:US West]
   deletion_time      n/a
   destroyed          false
   version            3
   
   ======== Data ========
   Key              Value
   ---              -----
   contact_email    john.smith@acme.com
   customer_name    ACME Inc.
   

1. Create an API request payload containing some test data.

   $ tee payload.json <<EOF
   {
     "data": {
       "name": "ACME Inc.",
       "contact_email": "jsmith@acme.com"
     }
   }
   EOF
   

2. Write some data at secret/customer/acme.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
     --request POST \
     --data @payload.json \
     $VAULT_ADDR/v1/secret/data/customer/acme | jq
   

   Example output:

   {
     "request_id": "e8021c29-394e-faee-ecab-9a2d55a6f622",
     "lease_id": "",
     "renewable": false,
     "lease_duration": 0,
     "data": {
       "created_time": "2021-10-29T02:08:37.389337Z",
       "custom_metadata": null,
       "deletion_time": "",
       "destroyed": false,
       "version": 1
     },
     "wrap_info": null,
     "warnings": null,
     "auth": null
   }
   

   Notice that the endpoint for KV v2 is /secret/data/<path>; therefore to write secrets at secret/customer/acme, the API endpoint becomes /secret/data/customer/acme.

3. Create an API request payload containing the data to update the current data.

   $ tee payload_2.json <<EOF
   {
     "data": {
       "customer_name": "ACME Inc.",
       "contact_email": "john.smith@acme.com"
     }
   }
   EOF
   

4. Update the secret to create another version.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
     --request POST \
     --data @payload_2.json \
     $VAULT_ADDR/v1/secret/data/customer/acme | jq
   

   Example output:

   {
     "request_id": "8fcdec0f-99bb-a62a-20be-e3239e8a2d7a",
     "lease_id": "",
     "renewable": false,
     "lease_duration": 0,
     "data": {
       "created_time": "2021-10-29T02:09:32.112647Z",
       "custom_metadata": null,
       "deletion_time": "",
       "destroyed": false,
       "version": 2
     },
     "wrap_info": null,
     "warnings": null,
     "auth": null
   }
   

   Now you have two versions of the secret/customer/acme data.

5. Read back the secret.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
     $VAULT_ADDR/v1/secret/data/customer/acme | jq -r ".data"
   

   Example output:

   {
     "data": {
       "contact_email": "john.smith@acme.com",
       "customer_name": "ACME Inc."
     },
     "metadata": {
       "created_time": "2021-10-29T02:09:32.112647Z",
       "custom_metadata": null,
       "deletion_time": "",
       "destroyed": false,
       "version": 2
     }
   }
   

Patch the existing data

While POST 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. You can use PATCH to partially update the current version of the secret.

Use case: Use case: Think of an application that does not have read permission, but captures partial data updates. The PATCH operation allows the application to send the changing values to Vault.

Update the contact_email value to admin@acme.com (current value is john.smith@acme.com).

1. Create an API request payload containing the data to update the current data.

   $ tee payload_patch.json <<EOF
   {
     "data": {
       "contact_email": "admin@acme.com"
     }
   }
   EOF
   

2. Update the secret to create another version.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
     --header "Content-Type: application/merge-patch+json" \
     --request PATCH \
     --data @payload_patch.json \
     $VAULT_ADDR/v1/secret/data/customer/acme | jq
   

   This uses JSON merge patch and must use a Content-Type header value of application/merge-patch+json.

   Example output:

   {
     "request_id": "deadc6ad-473d-2433-ae2c-5c4a2fecbbc6",
     "lease_id": "",
     "renewable": false,
     "lease_duration": 0,
     "data": {
       "created_time": "2021-10-29T02:11:45.005824Z",
       "custom_metadata": null,
       "deletion_time": "",
       "destroyed": false,
       "version": 3
     },
     "wrap_info": null,
     "warnings": null,
     "auth": null
   }
   

3. Read back the secret.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
     $VAULT_ADDR/v1/secret/data/customer/acme | jq -r ".data"
   

   Example output:

   {
     "data": {
       "contact_email": "admin@acme.com",
       "customer_name": "ACME Inc."
     },
     "metadata": {
       "created_time": "2021-10-29T02:11:45.005824Z",
       "custom_metadata": null,
       "deletion_time": "",
       "destroyed": false,
       "version": 3
     }
   }
   

   The contact_email value now admin@acme.com, and the version is now 3.

Add custom metadata

You saw that the secret's key (in this example, secret/customer/acme) has metadata associated with it. An organization may require adding custom metadata describing further details (technical contact, mission criticality, etc.) about the secret.

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.

1. Create an API request payload containing the custom metadata.

   $ tee payload_metadata.json <<EOF
   {
     "custom_metadata": {
       "Membership": "Platinum",
       "Region": "US West"
     }
   }
   EOF
   

2. Update the secret key metadata.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
     --request POST \
     --data @payload_metadata.json \
     $VAULT_ADDR/v1/secret/metadata/customer/acme
   

3. Read back the secret.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
     $VAULT_ADDR/v1/secret/data/customer/acme | jq -r ".data"
   

   Example output:

   {
     "data": {
       "contact_email": "admin@acme.com",
       "customer_name": "ACME Inc."
     },
     "metadata": {
       "created_time": "2021-10-29T02:11:45.005824Z",
       "custom_metadata": {
         "Membership": "Platinum",
         "Region": "US West"
       },
       "deletion_time": "",
       "destroyed": false,
       "version": 3
     }
   }
   

   The returned secret metadata displays the custom metadata.

1. In the Web UI, select secret/ and then click Create secret. Enter customer/acme in the Path for this secret field.

2. Under Secret data, enter customer_name in the key field, and ACME Inc. in its value field. You can click on the sensitive information toggle to show the entered secret values.

3. Click Add.

4. Enter contact_email in the second key field, and jsmith@acme.com as its value.

5. Click Save.

   Use JSON format

   Notice the JSON toggle in the UI. Instead of entering the key-value pairs one by one, you can enter the secret values using JSON.

6. To update the existing secret, select Create new version under the Secret tab.

7. Change the contact_email value (for example, john@acme.com) and then click Save.

Patch the existing data

Create new version 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 Patch latest version instead.

Update the contact_email value to admin@acme.com (current value is john.smith@acme.com).

1. Under the Secret tab, select Patch latest version.

2. Click the edit button next to the contact_email field.

3. Enter admin@acme.com in the text field.

4. Click Save.

The patch command creates a new version of the secret which merges the fields within the secret data.

The command updates the contact_email value to admin@acme.com, and the current version is 3.

Add custom metadata

You saw that the secret's key (in this example, secret/customer/acme) has metadata associated with it. An organization may require adding custom metadata describing further details (technical contact, mission criticality, etc.) about the secret.

1. Select the Metadata tab, and then click Add metadata.

2. Under Custom metadata, enter Membership in the key field, and Platinum in its value field.

3. Click Add.

4. Enter Region in the second key field, and US West in its value field.

5. Click Update. Now, set metadata on the secret/customer/acme key.

1. Get version 1 of the secret defined at the path secret/customer/acme.

   $ vault kv get -version=1 secret/customer/acme
   ====== Secret Path ======
   secret/data/customer/acme
   
   ======= Metadata =======
   Key                Value
   ---                -----
   created_time       2022-06-13T15:09:01.710331Z
   custom_metadata    map[Membership:Platinum Region:US West]
   deletion_time      n/a
   destroyed          false
   version            1
   
   ======== Data ========
   Key              Value
   ---              -----
   contact_email    admin@acme.com
   customer_name    ACME Inc.
   

2. Get the metadata of the secret defined at the path secret/customer/acme.

   $ vault kv metadata get secret/customer/acme
   ======= Metadata Path =======
   secret/metadata/customer/acme
   
   ========== Metadata ==========
   Key                     Value
   ---                     -----
   cas_required            false
   created_time            2021-10-31T00:08:46.869191Z
   current_version         3
   custom_metadata         map[Membership:Platinum Region:US West]
   delete_version_after    0s
   max_versions            0
   oldest_version          0
   updated_time            2021-10-31T00:10:14.147236Z
   
   ====== Version 1 ======
   Key              Value
   ---              -----
   created_time     2021-10-31T00:08:46.869191Z
   deletion_time    n/a
   destroyed        false
   
   ====== Version 2 ======
   Key              Value
   ---              -----
   created_time     2021-10-31T00:09:32.659503Z
   deletion_time    n/a
   destroyed        false
   
   ====== Version 3 ======
   Key              Value
   ---              -----
   created_time     2021-10-31T00:10:14.147236Z
   deletion_time    n/a
   destroyed        false
   

1. Get version 1 of the secret defined at the path secret/customer/acme.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
     $VAULT_ADDR/v1/secret/data/customer/acme\?version=1 | jq -r ".data"
   

   Example output:

   {
     "data": {
       "contact_email": "jsmith@acme.com",
       "name": "ACME Inc."
     },
     "metadata": {
       "created_time": "2021-10-29T02:08:37.389337Z",
       "custom_metadata": {
         "Membership": "Platinum",
         "Region": "US West"
       },
       "deletion_time": "",
       "destroyed": false,
       "version": 1
     }
   }
   

2. Get the metadata of the secret defined at the path secret/customer/acme.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
     $VAULT_ADDR/v1/secret/metadata/customer/acme | jq -r ".data"
   

   Example output:

   {
     "cas_required": false,
     "created_time": "2021-10-29T02:08:37.389337Z",
     "current_version": 3,
     "custom_metadata": {
       "Membership": "Platinum",
       "Region": "US West"
     },
     "delete_version_after": "0s",
     "max_versions": 0,
     "oldest_version": 0,
     "updated_time": "2021-10-29T02:11:45.005824Z",
     "versions": {
       "1": {
         "created_time": "2021-10-29T02:08:37.389337Z",
         "deletion_time": "",
         "destroyed": false
       },
       "2": {
         "created_time": "2021-10-29T02:09:32.112647Z",
         "deletion_time": "",
         "destroyed": false
       },
       "3": {
         "created_time": "2021-10-29T02:11:45.005824Z",
         "deletion_time": "",
         "destroyed": false
       }
     }
   }
   

1. Click the Secret tab.

2. Select the down-arrow next to Version 3 and then Version 1

3. The version changes from Version 3 to Version 1. To view the raw values, click on the sensitive information toggle.

4. To create a new version of the secrets based on the Version 1 data, Create new version +.

   This can help revert an older version of the secrets.

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
   Success! Data written to: secret/config
   

   Every secret stored for this engine can retain up to 4 versions.

2. Display the secrets engine configuration settings.

   $ vault read secret/config
   
   Key                     Value
   ---                     -----
   cas_required            false
   delete_version_after    0s
   max_versions            4
   

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
   Success! Data written to: secret/metadata/customer/acme
   

   The secret can also define the maximum number of versions.

4. Using this command 4 times, create four more secrets at the path secret/customer/acme.

   $ vault kv put secret/customer/acme customer_name="ACME Inc." \
           contact_email="admin@acme.com"
   

5. Get the metadata of the secret defined at the path secret/customer/acme.

   $ vault kv metadata get secret/customer/acme
   

   Example output:

   ======= Metadata Path =======
   secret/metadata/customer/acme
   
   ========== Metadata ==========
   Key                     Value
   ---                     -----
   cas_required            false
   created_time            2021-10-31T00:08:46.869191Z
   current_version         7
   custom_metadata         map[Membership:Platinum Region:US West]
   delete_version_after    0s
   max_versions            4
   oldest_version          4
   updated_time            2021-10-31T00:15:04.591209Z
   
   ====== Version 4 ======
   Key              Value
   ---              -----
   created_time     2021-10-31T00:14:59.830407Z
   deletion_time    n/a
   destroyed        false
   
   ====== Version 5 ======
   Key              Value
   ---              -----
   created_time     2021-10-31T00:15:01.892226Z
   deletion_time    n/a
   destroyed        false
   
   ====== Version 6 ======
   Key              Value
   ---              -----
   created_time     2021-10-31T00:15:03.418051Z
   deletion_time    n/a
   destroyed        false
   
   ====== Version 7 ======
   Key              Value
   ---              -----
   created_time     2021-10-31T00:15:04.591209Z
   deletion_time    n/a
   destroyed        false
   

   The metadata displays the current_version and the history of versions stored. There is a limit of 4 versions of the secrets stored at this path. Earlier, you deleted Version 1 and 2.

6. Verify deletion of that version 1 of the secret defined at the path secret/customer/acme.

   $ vault kv get -version=1 secret/customer/acme
   No value found at secret/data/customer/acme
   

1. Create an API request payload specifying the max_versions to 4.

   $ tee payload-config.json<<EOF
   {
     "max_versions": 4,
     "cas_required": false
   }
   EOF
   

2. Configure the secrets engine at path secret/ to limit all secrets to a maximum of 4 versions.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
     --request POST \
     --data @payload-config.json \
     $VAULT_ADDR/v1/secret/config
   

   Every secret stored for this engine can retain up to 4 versions.

3. Display the secrets engine configuration settings.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
     $VAULT_ADDR/v1/secret/config | jq -r ".data"
   

   The output should as follow:

   {
     "cas_required": false,
     "delete_version_after": "0s",
     "max_versions": 4
   }
   

4. Configure the secret at path secret/customer/acme to limit secrets to a maximum of 4 versions.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
     --request POST \
     --data @payload.json \
     $VAULT_ADDR/v1/secret/metadata/customer/acme
   

   The secret can also define the maximum number of versions.

5. Create four more secrets at the path secret/customer/acme.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
     --request POST \
     --data @payload.json \
     $VAULT_ADDR/v1/secret/data/customer/acme
   

6. Get the metadata of the secret defined at the path secret/customer/acme.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
     $VAULT_ADDR/v1/secret/metadata/customer/acme | jq -r ".data"
   

   Example output:

   {
     "cas_required": false,
     "created_time": "2021-10-29T02:08:37.389337Z",
     "current_version": 7,
     "custom_metadata": {
       "Membership": "Platinum",
       "Region": "US West"
     },
     "delete_version_after": "0s",
     "max_versions": 0,
     "oldest_version": 4,
     "updated_time": "2021-10-29T02:57:54.601033Z",
     "versions": {
       "4": {
         "created_time": "2021-10-29T02:55:31.078902Z",
         "deletion_time": "",
         "destroyed": false
       },
       "5": {
         "created_time": "2021-10-29T02:57:13.519347Z",
         "deletion_time": "",
         "destroyed": false
       },
       "6": {
         "created_time": "2021-10-29T02:57:21.096945Z",
         "deletion_time": "",
         "destroyed": false
       },
       "7": {
         "created_time": "2021-10-29T02:57:54.601033Z",
         "deletion_time": "",
         "destroyed": false
       }
     }
   }
   

   The metadata displays the current_version and the history of versions stored. There is a limit of 4 secrets stored at this path. Earlier, you deleted Version 1, 2, and 3.

7. Verify deletion of that version 1 of the secret defined at the path secret/customer/acme.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
     $VAULT_ADDR/v1/secret/data/customer/acme\?version=1 | jq
   

   The output should look as follow:

   {
     "errors": []
   }
   

1. Click the Vault CLI shell icon (>_) to open a command shell. Execute the following command to tune the maximum number of versions to keep:

   $ vault write secret/config max_versions=4
   

   

2. Click the icon (>_) again to hide the shell.

3. Overwrite the data a few more times to see what happens to its versions.

   In this example, the current version is 7. Notice that version 1 through 2 do not show up in the metadata. Because you configured the kv secrets engine to keep 4 versions, the oldest two versions are permanently deleted and you won't be able to read them.

1. Delete version 4 and 5 of the secrets at path secret/customer/acme.

   $ vault kv delete -versions="4,5" secret/customer/acme
   Success! Data deleted (if it existed) at: secret/customer/acme
   

2. Get the metadata of the secret defined at the path secret/customer/acme.

   $ vault kv metadata get secret/customer/acme
   
   ##...snip...
   ====== Version 4 ======
   Key              Value
   ---              -----
   created_time     2021-10-31T00:14:59.830407Z
   deletion_time    2021-10-31T00:16:25.860618Z
   destroyed        false
   
   ====== Version 5 ======
   Key              Value
   ---              -----
   created_time     2021-10-31T00:15:01.892226Z
   deletion_time    2021-10-31T00:16:25.860619Z
   destroyed        false
   ##...snip...
   

   The metadata on versions 4 and 5 reports its deletion timestamp (deletion_time); however, the destroyed parameter set to false.

3. Undelete version 5 of the secrets at path secret/customer/acme.

   $ vault kv undelete -versions=5 secret/customer/acme
   Success! Data written to: secret/undelete/customer/acme
   

1. Delete version 4 and 5 of the secrets at path secret/customer/acme.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
     --request POST \
     --data '{ "versions":[4,5] }' \
     $VAULT_ADDR/v1/secret/delete/customer/acme
   

2. Get the metadata of the secret defined at the path secret/customer/acme.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
     $VAULT_ADDR/v1/secret/metadata/customer/acme | jq -r ".data.versions"
   

   Example output:

   {
     "4": {
       "created_time": "2021-10-29T02:55:31.078902Z",
       "deletion_time": "2021-10-29T03:05:26.946674Z",
       "destroyed": false
     },
     "5": {
       "created_time": "2021-10-29T02:57:13.519347Z",
       "deletion_time": "2021-10-29T03:05:26.946675Z",
       "destroyed": false
     },
     "6": {
       "created_time": "2021-10-29T02:57:21.096945Z",
       "deletion_time": "",
       "destroyed": false
     },
     "7": {
       "created_time": "2021-10-29T02:57:54.601033Z",
       "deletion_time": "",
       "destroyed": false
     }
   }
   

   The metadata on versions 4 and 5 reports its deletion timestamp (deletion_time); however, the destroyed parameter set to false.

3. You can undelete version 5 of the secrets at path secret/customer/acme in case of accidental deletion.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
     --request POST \
     --data '{ "versions":[5] }' \
     $VAULT_ADDR/v1/secret/undelete/customer/acme
   

Delete versions 4 and 5.

1. At the secret/customer/acme path, select the down-arrow next to Version 7 and then select Version 4, and then click Delete.

2. At the confirmation dialog, the Delete this version radio button, and then click Confirm to proceed.

3. If you deleted version 4 by mistake and you want to recover it, select Undelete from then menu.

4. Delete Version 5, and notice that the UI now marks version as deleted.

5. Select Version 5 and then View version history. Here you can see the state of all versions.

1. Destroy version 4 of the secrets at path secret/customer/acme.

   $ vault kv destroy -versions=4 secret/customer/acme
   Success! Data written to: secret/destroy/customer/acme
   

2. Get the metadata of the secret defined at the path secret/customer/acme.

   $ vault kv metadata get secret/customer/acme
   
   ##...snip...
   ====== Version 4 ======
   Key              Value
   ---              -----
   created_time     2021-10-31T00:14:59.830407Z
   deletion_time    2021-10-31T00:16:25.860618Z
   destroyed        true
   ##...snip...
   

   The metadata displays that you destroyed Version 4.

3. Delete all versions of the secret at the path secret/customer/acme.

   $ vault kv metadata delete secret/customer/acme
   Success! Data deleted (if it existed) at: secret/metadata/customer/acme
   

4. Check that the secret is no longer available.

   $ vault kv metadata get secret/customer/acme
   No value found at secret/metadata/customer/acme
   

1. Destroy version 4 of the secrets at path secret/customer/acme.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
     --request POST \
     --data '{ "versions":[4] }' \
     $VAULT_ADDR/v1/secret/destroy/customer/acme
   

2. Get the metadata of the secret defined at the path secret/customer/acme.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
     $VAULT_ADDR/v1/secret/metadata/customer/acme | jq -r ".data.versions"
   

   Example output:

   {
     "4": {
       "created_time": "2021-10-29T02:55:31.078902Z",
       "deletion_time": "2021-10-29T03:05:26.946674Z",
       "destroyed": true
     },
     "5": {
       "created_time": "2021-10-29T02:57:13.519347Z",
       "deletion_time": "",
       "destroyed": false
     },
     "6": {
       "created_time": "2021-10-29T02:57:21.096945Z",
       "deletion_time": "",
       "destroyed": false
     },
     "7": {
       "created_time": "2021-10-29T02:57:54.601033Z",
       "deletion_time": "",
       "destroyed": false
     }
   }
   

   The metadata indicates the destruction of Version 4.

3. Delete all versions of the secret at the path secret/customer/acme.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
     --request DELETE \
     $VAULT_ADDR/v1/secret/metadata/customer/acme
   

To permanently delete a version of secret, select Permanently destroy version from its menu.

1. Select Version 4 from the menu and switch to Version 3.

2. Select Delete, choose Destroy this version and then click Delete.

3. Select Version 3 from the menu and switch to View version history.

4. You can validate the destruction of Version 3 and deletion of Version 4.

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
   Success! Data written to: secret/metadata/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"
   

   Tip

   You can use upper-arrow key to recover the command executed earlier.

5. Get the metadata of the secret defined at the path secret/test.

   $ vault kv metadata get secret/test
   

   Example output:

   === Metadata Path ===
   secret/metadata/test
   
   ========== Metadata ==========
   Key                     Value
   ---                     -----
   cas_required            false
   created_time            2021-05-28T19:03:03.618924Z
   current_version         3
   delete_version_after    40s
   max_versions            0
   oldest_version          0
   updated_time            2021-05-28T19:03:20.857496Z
   
   ====== Version 1 ======
   Key              Value
   ---              -----
   created_time     2021-05-28T19:03:09.818797Z
   deletion_time    2021-05-28T19:03:49.818797Z
   destroyed        false
   
   ====== Version 2 ======
   Key              Value
   ---              -----
   created_time     2021-05-28T19:03:16.991649Z
   deletion_time    2021-05-28T19:03:56.991649Z
   destroyed        false
   
   ====== Version 3 ======
   Key              Value
   ---              -----
   created_time     2021-05-28T19:03:20.857496Z
   deletion_time    2021-05-28T19:04:00.857496Z
   destroyed        false
   

   The metadata displays a deletion_time set on each version. After 40 seconds, Vault automatically deletes the version data, but does not destroy the secret.

6. Get version 1 of the secret defined at the path secret/test.

   $ vault kv get -version=1 secret/test
   == Secret Path ==
   secret/data/test
   
   ====== Metadata ======
   Key              Value
   ---              -----
   created_time     2021-05-28T19:03:09.818797Z
   deletion_time    2021-05-28T19:03:49.818797Z
   destroyed        false
   version          1
   
   ===== Data =====
   Key        Value
   ---        -----
   message    data1
   

1. For demonstration, configure the secrets at path secret/test to delete versions after 40 seconds.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
     --request POST \
     --data '{ "delete_version_after": "40s" }' \
     $VAULT_ADDR/v1/secret/metadata/test
   

2. Create a secret at the path secret/test.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
     --request POST \
     --data '{"data": {"message": "data1"}}' \
     $VAULT_ADDR/v1/secret/data/test | jq -r ".data"
   

   Example output:

   {
     "created_time": "2021-10-29T03:15:39.375151Z",
     "custom_metadata": null,
     "deletion_time": "2021-10-29T03:16:19.375151Z",
     "destroyed": false,
     "version": 1
   }
   

3. Again, create a secret at the path secret/test.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
   --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
   --request POST \
   --data '{"data": {"message": "data2"}}' \
   $VAULT_ADDR/v1/secret/data/test

1. Again, create a secret at the path secret/test.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
     --request POST \
     --data '{"data": {"message": "data3"}}' \
     $VAULT_ADDR/v1/secret/data/test
   

2. Get the metadata of the secret defined at the path secret/test.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
     $VAULT_ADDR/v1/secret/metadata/test | jq -r ".data"
   

   Example output:

   {
     "cas_required": false,
     "created_time": "2021-10-29T03:15:31.743167Z",
     "current_version": 3,
     "custom_metadata": null,
     "delete_version_after": "40s",
     "max_versions": 0,
     "oldest_version": 0,
     "updated_time": "2021-10-29T03:16:11.848245Z",
     "versions": {
       "1": {
         "created_time": "2021-10-29T03:15:39.375151Z",
         "deletion_time": "2021-10-29T03:16:19.375151Z",
         "destroyed": false
       },
       "2": {
         "created_time": "2021-10-29T03:16:03.366448Z",
         "deletion_time": "2021-10-29T03:16:43.366448Z",
         "destroyed": false
       },
       "3": {
         "created_time": "2021-10-29T03:16:11.848245Z",
         "deletion_time": "2021-10-29T03:16:51.848245Z",
         "destroyed": false
       }
     }
   }
   

   The metadata displays a deletion_time set on each version. After 40 seconds, Vault automatically deletes the version data, but does not destroy the secret.

3. Get version 1 of the secret defined at the path secret/test.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
     $VAULT_ADDR/v1/secret/data/test\?version=1 | jq -r ".data"
   

   Example output:

   {
     "data": null,
     "metadata": {
       "created_time": "2021-10-29T03:15:39.375151Z",
       "custom_metadata": null,
       "deletion_time": "2021-10-29T03:16:19.375151Z",
       "destroyed": false,
       "version": 1
     }
   }
   

For demonstration, configure the secrets at path secret/test to delete versions after 40 seconds.

1. In the Web UI, select secret/ and then click Create secret.

2. Enter test in the Path for this secret field.

3. Under Secret data, enter message in the key field, and data1 in its value field.

4. Expand Show secret metadata.

5. Slide the Automate secret deletion toggle to enable it, and enter 40 to set the secrets at this path for deletion after 40 seconds.

6. Click Save.

7. Click Create new version +, and then click Save to create a new version of the secret.

8. Repeat the step a couple of more times to create many versions of the secret.

9. Select the Metadata tab, and you should notice that the Delete version after parameter set to 40s.

10. Wait for 40 seconds and select the Secret tab.

    Secrets delete automatically after 40 seconds, so the UI shows no key values.

1. Configure the secrets engine at path secret/ to enable Check-And-Set.

   $ vault write secret/config cas_required=true
   

2. Configure the secret at path secret/partner to enable Check-And-Set.

   $ vault kv metadata put -cas-required=true secret/partner
   

   After enabling check-and-set, 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.

3. Create a new secret at the path secret/partner.

   $ vault kv put -cas=0 secret/partner name="Example Co." partner_id="123456789"
   
   Key              Value
   ---              -----
   created_time     2021-05-28T19:05:50.165496Z
   deletion_time    n/a
   destroyed        false
   version          1
   

4. Overwrite the secret at the path secret/partner.

   $ vault kv put -cas=1 secret/partner name="Example Co." \
         partner_id="ABCDEFGHIJKLMN"
   

   Example output:

   Key              Value
   ---              -----
   created_time     2021-05-28T19:06:57.350072Z
   deletion_time    n/a
   destroyed        false
   version          2
   

1. Create an API request payload that sets cas_required to true.

   $ tee payload-cas.json<<EOF
   {
     "max_versions": 10,
     "cas_required": true
   }
   EOF
   

2. Configure the secrets engine at path secret/ to enable Check-And-Set.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
     --request POST \
     --data @payload-cas.json \
     $VAULT_ADDR/v1/secret/config
   

3. Configure the secret at path secret/partner to enable Check-And-Set.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
     --request POST \
     --data '{"cas_required": true}' \
     $VAULT_ADDR/v1/secret/metadata/partner
   

   After enabling check-and-set, 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 an API request payload with secret data and the cas value to 0.

   $ tee payload_3.json <<EOF
   {
     "options": {
       "cas": 0
     },
     "data": {
       "name": "Example Co.",
       "partner_id": "123456789"
     }
   }
   EOF
   

5. Create a new secret at the path secret/partner.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
     --request POST \
     --data @payload_3.json \
     $VAULT_ADDR/v1/secret/data/partner | jq -r ".data"
   

   Example output:

   {
     "created_time": "2021-10-31T01:08:29.152955Z",
     "custom_metadata": null,
     "deletion_time": "",
     "destroyed": false,
     "version": 1
   }
   

6. Create an API request payload with updated secret data and the cas value to 1.

   $ tee payload_4.json <<EOF
   {
     "options": {
       "cas": 1
     },
     "data": {
       "name": "Example Co.",
       "partner_id": "ABCDEFGHIJKLMN"
     }
   }
   EOF
   

7. Overwrite the secret at the path secret/partner.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
     --request POST \
     --data @payload_4.json \
     $VAULT_ADDR/v1/secret/data/partner | jq -r ".data"
   

   Example output:

   {
     "created_time": "2021-10-31T01:09:11.106648Z",
     "custom_metadata": null,
     "deletion_time": "",
     "destroyed": false,
     "version": 2
   }
   

To enable the Check-And-Set operation, select the Require Check and Set check-box when you create secrets.