[Yandex Cloud documentation](../../index.md) > [Yandex Lockbox](../index.md) > [Step-by-step guides](index.md) > Secret version management

# Secret version management


With secret version management, you can:

* [Create a new user secret version](#create-version).
* [Create a new generated secret version](#create-generated-version).
* [Get information about a version](#get-version).
* [Create a version based on an existing version](#create-version-based-on-other).
* [Roll back to a particular version](#backup).
* [Schedule a version for deletion](#set-deleting-time).

## Creating a new user secret version {#create-version}

{% list tabs group=instructions %}

- Management console {#console}

    1. In the [management console](https://console.yandex.cloud), select the folder the secret belongs to.
    1. Navigate to **Lockbox**.
    1. Click the name of the secret you need.
    1. Under **Versions**, click **Add version**.
    1. Add the following parameters:
        * (Optional) **Description**: Version description.
        * **Key**: Non-secret name  you will use to identify a value.
        * **Value**: Explicitly represented secret data.
        You can create multiple key-value pairs per version.
        
    1. Click **Add version**.

- Terraform {#tf}

  With [Terraform](https://www.terraform.io/), you can quickly create a cloud infrastructure in Yandex Cloud and manage it using configuration files. These files store the infrastructure description written in HashiCorp Configuration Language (HCL). If you change the configuration files, Terraform automatically detects which part of your configuration is already deployed, and what should be added or removed.
  
  Terraform is distributed under the [Business Source License](https://github.com/hashicorp/terraform/blob/main/LICENSE). The [Yandex Cloud provider for Terraform](https://github.com/yandex-cloud/terraform-provider-yandex) is distributed under the [MPL-2.0](https://www.mozilla.org/en-US/MPL/2.0/) license.
  
  For more information about the provider resources, see the guides on the [Terraform](https://www.terraform.io/docs/providers/yandex/index.html) website or [its mirror](../../terraform/index.md).

  If you do not have Terraform yet, [install it and configure the Yandex Cloud provider](../../tutorials/infrastructure-management/terraform-quickstart.md#install-terraform).
  
  
  To manage infrastructure using Terraform under a service account or user accounts (a Yandex account, a federated account, or a local user), [authenticate](../../terraform/authentication.md) using the appropriate method.

  1. In the configuration file, specify the properties of the resources you want to create:

      ```hcl
      resource "yandex_lockbox_secret_version_hashed" "my_version" {
        secret_id    = "<secret_ID>"

        key_1        = "<secret_1_key>"
        text_value_1 = "<secret_1_value>"

        key_2        = "<secret_2_key>"
        text_value_2 = "<secret_2_value>"
      }
      ```

      Where:

      * `secret_id`: ID of the secret you are creating a version for.
      * (Optional) `description`: Any comment on the secret version.
      * `key_N`: Secret key. Non-secret name you will use to identify a value.
      * `text_value_N`: Explicitly represented secret data.

      The `key_N/text_value_N` pairs are numbered sequentially from 1 to 10 (10 pairs are supported). If only one pair is required, use `key_1/text_value_1`.

      {% note info %}
      
      We recommend using `yandex_lockbox_secret_version_hashed`: it stores values in Terraform state in hashed format. We continue supporting `yandex_lockbox_secret_version`.
      
      For more information about the `yandex_lockbox_secret_version_hashed` resource, see [this provider guide](../../terraform/resources/lockbox_secret_version_hashed.md).
      
      {% endnote %}

  1. Create the resources:

      1. In the terminal, navigate to the configuration file directory.
      1. Make sure the configuration is correct using this command:
      
         ```bash
         terraform validate
         ```
      
         If the configuration is valid, you will get this message:
      
         ```bash
         Success! The configuration is valid.
         ```
      
      1. Run this command:
      
         ```bash
         terraform plan
         ```
      
         You will see a list of resources and their properties. No changes will be made at this step. Terraform will show any errors in the configuration.
      1. Apply the configuration changes:
      
         ```bash
         terraform apply
         ```
      
      1. Type `yes` and press **Enter** to confirm the changes.

  This creates a new version of the specified secret. You can check the new version and its settings using the [management console](https://console.yandex.cloud) or this [CLI](../../cli/quickstart.md) command:

  ```bash
  yc lockbox secret list-versions <secret_ID>
  ```

- API {#api}

  To create a new secret version, use the [addVersion](../api-ref/Secret/addVersion.md) REST API method for the [Secret](../api-ref/Secret/index.md) resource or the [SecretService/AddVersion](../api-ref/grpc/Secret/addVersion.md) gRPC API call.

{% endlist %}

## Creating a new generated secret version {#create-generated-version}

{% list tabs group=instructions %}

- Management console {#console}

    1. In the [management console](https://console.yandex.cloud), select the folder the secret belongs to.
    1. Navigate to **Lockbox**.
    1. Click the name of the secret you need.
    1. Under **Versions**, click **Add version**.
    1. (Optional) Add **Description** of the version.
    1. (Optional) To change other parameters, click **Edit** and specify:
       * **Secret type**: You can either leave the generated type or select the user type.
       * **Key** and **Automatic generation options**, for the generated secret type.
       * **Key** and **Value**, for the user secret type.

          You can create multiple key-value pairs per version.
    1. Click **Add version** or **Save**.


- Terraform {#tf}

    #### Secret generation with Yandex Cloud

    With [Terraform](https://www.terraform.io/), you can quickly create a cloud infrastructure in Yandex Cloud and manage it using configuration files. These files store the infrastructure description written in HashiCorp Configuration Language (HCL). If you change the configuration files, Terraform automatically detects which part of your configuration is already deployed, and what should be added or removed.
    
    Terraform is distributed under the [Business Source License](https://github.com/hashicorp/terraform/blob/main/LICENSE). The [Yandex Cloud provider for Terraform](https://github.com/yandex-cloud/terraform-provider-yandex) is distributed under the [MPL-2.0](https://www.mozilla.org/en-US/MPL/2.0/) license.
    
    For more information about the provider resources, see the guides on the [Terraform](https://www.terraform.io/docs/providers/yandex/index.html) website or [its mirror](../../terraform/index.md).

    If you do not have Terraform yet, [install it and configure the Yandex Cloud provider](../../tutorials/infrastructure-management/terraform-quickstart.md#install-terraform).
    
    
    To manage infrastructure using Terraform under a service account or user accounts (a Yandex account, a federated account, or a local user), [authenticate](../../terraform/authentication.md) using the appropriate method.

    1. You can create a new generated secret version when [creating](secret-create.md) it. Specify the secret generation parameters in the `yandex_lockbox_secret` resource description under `password_payload_specification` and create a new secret version with a reference to the secret:
  
       ```hcl
       # Creating a generated secret
       resource "yandex_lockbox_secret" "my_secret" {
         name = "<secret_name>"

         password_payload_specification {
           password_key        = "<secret_key>"
           length              = "<length>"
           include_uppercase   = true
           include_lowercase   = true
           include_digits      = true
           include_punctuation = true
         }
       }

       # Creating a secret version
       resource "yandex_lockbox_secret_version" "my_version" {
         secret_id = yandex_lockbox_secret.my_secret.id
       }
       ```
  
       Where:
       * `password_payload_specification`: Secret generating parameters:
         * `password_key`: Secret key. Non-secret name you will use to identify a value.
         * `length`: Length of the generated secret value. This is a required setting.
         * `include_uppercase `: Use uppercase Latin letters (A...Z). The default value is `true`.
         * `include_lowercase`: Use lowercase Latin letters (a...z). The default value is `true`.
         * `include_digits`: Use numbers (0...9). The default value is `true`.
         * `include_punctuation`: Use special characters. The default value is `true`.

       For more on the properties of the `yandex_lockbox_secret` resource, see [this provider guide](../../terraform/resources/lockbox_secret.md).

    1. Apply the changes:

       1. In the terminal, navigate to the configuration file directory.
       1. Make sure the configuration is correct using this command:
       
          ```bash
          terraform validate
          ```
       
          If the configuration is valid, you will get this message:
       
          ```bash
          Success! The configuration is valid.
          ```
       
       1. Run this command:
       
          ```bash
          terraform plan
          ```
       
          You will see a list of resources and their properties. No changes will be made at this step. Terraform will show any errors in the configuration.
       1. Apply the configuration changes:
       
          ```bash
          terraform apply
          ```
       
       1. Type `yes` and press **Enter** to confirm the changes.
  
    You can check the new secret and its contents using the [management console](https://console.yandex.cloud) or this [CLI](../../cli/index.md) command:
  
    ```bash
    yc lockbox payload get <secret_name_or_ID>
    ```

    #### Secret generation with a custom script

    You can create a new generated secret version using a secret generation script of your own. The script's output value will not be displayed in Terraform State.

    {% cut "Example of a bash secret generation script" %}
    
    ```bash
    #!/bin/bash
    choose() { echo ${1:RANDOM%${#1}:1}; }
    
    {
        choose 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
        choose 'abcdefghijklmnopqrstuvwxyz'
        choose '0123456789'
        choose '!@#$%^\&'
        for i in $( seq 1 $(( 4 + RANDOM % 8 )) )
        do
            choose '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'
        done
    } | sort -R | tr -d '\n'
    ```
   
    {% endcut %}

    1. In the `yandex_lockbox_secret_version` resource description under `entries`, specify the `command.path` parameter, i.e., path to the secret generation script.

       ```hcl
       # Creating a secret version with a password generation script
       resource "yandex_lockbox_secret_version" "my_version" {
         secret_id = "<secret_ID>"

         entries {
           key = "<secret_key>"
           command {
             path = "<path_to_script>"
           }
         }
       }
       ```

       Where:
       * `secret_id`: ID of the secret you are creating a version for.
       * `key`: Secret key. Non-secret name you will use to identify a value.
       * `path`: Path to the secret generation script.

       For more on the properties of the `yandex_lockbox_secret_version` resource, see [this provider guide](../../terraform/resources/lockbox_secret_version.md).

    1. Apply the changes:

       1. In the terminal, navigate to the configuration file directory.
       1. Make sure the configuration is correct using this command:
       
          ```bash
          terraform validate
          ```
       
          If the configuration is valid, you will get this message:
       
          ```bash
          Success! The configuration is valid.
          ```
       
       1. Run this command:
       
          ```bash
          terraform plan
          ```
       
          You will see a list of resources and their properties. No changes will be made at this step. Terraform will show any errors in the configuration.
       1. Apply the configuration changes:
       
          ```bash
          terraform apply
          ```
       
       1. Type `yes` and press **Enter** to confirm the changes.
  
    You can check the new secret and its contents using the [management console](https://console.yandex.cloud) or this [CLI](../../cli/index.md) command:
  
    ```bash
    yc lockbox payload get <secret_name_or_ID>
    ```

{% endlist %}

## Getting information about a version {#get-version}

{% list tabs group=instructions %}

- Management console {#console}

    1. In the [management console](https://console.yandex.cloud), select the folder the secret belongs to.
    1. Navigate to **Lockbox**.
    1. Click the name of the secret you need.
    1. Under **Versions**, you will see a list of all secret versions with information about them.
    1. Click a version to see the details about its key-value pairs.

- CLI {#cli}

  If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../cli/quickstart.md#install).

  The folder used by default is the one specified when [creating](../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set folder-id <folder_ID>` command. You can also specify a different folder for any command using `--folder-name` or `--folder-id`. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

  1. View the description of the CLI command to view secret versions:

      ```bash
      yc lockbox secret list-version --help
      ```
  1. Run this command:
      
      ```bash
      yc lockbox secret list-version <secret_name>
      ```

  It will return information about all versions of the secret, key names included. Secret version values will not be displayed.

- API {#api}

  To get information about a version, use the [listVersions](../api-ref/Secret/listVersions.md) REST API method for the [Secret](../api-ref/Secret/index.md) resource or the [SecretService/ListVersions](../api-ref/grpc/Secret/listVersions.md) gRPC API call.

{% endlist %}

## Creating a version based on an existing version {#create-version-based-on-other}

{% list tabs group=instructions %}

- Management console {#console}

    1. In the [management console](https://console.yandex.cloud), select the folder the secret belongs to.
    1. Navigate to **Lockbox**.
    1. Click the name of the secret you need.
    1. Under **Versions**, next to the appropriate version, click ![image](../../_assets/console-icons/ellipsis.svg).
    1. Select **Create a version from this one**.
    1. Edit or add the following parameters:
        * (Optional) **Description**: Version description.
        * **Key**: Non-secret name  you will use to identify a value.
        * For a user secret, **Value**: Secret data in an explicit form.
        You can create multiple key-value pairs per version.
        * For a generated secret, you can change the key and the value parameters. To do this, click **Edit secret** and [specify new parameters](secret-update.md).
    1. Click **Add version**.

- CLI {#cli}

  If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../cli/quickstart.md#install).

  The folder used by default is the one specified when [creating](../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set folder-id <folder_ID>` command. You can also specify a different folder for any command using `--folder-name` or `--folder-id`. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

  1. View the description of the CLI command to create a new secret version:

      ```bash
      yc lockbox secret add-version --help
      ```
  1. Run this command:
      
      ```bash
      yc lockbox secret add-version <secret_name> \
        --description <secret_version_description> \
        --payload "<array_with_secret_version_contents>" \
        --base-version-id <existing_secret_version_ID>
      ```

      Where:
     * `<secret_name>`: Name of the secret you are creating a version for.
     * `--description`: Description of the new secret version (optional).
     * `--payload`: Contents of the new secret version as a YAML or JSON array.
     * `--base-version-id`: ID of the secret version used to create a new secret. If this parameter is not specified, the new version will be created based on the current version.

      Result:

      ```text
      id: e6qor8pe3ju7********
      secret_id: e6qkkp3k29jf********
      created_at: "2024-04-25T13:49:26.621Z"
      status: ACTIVE
      payload_entry_keys:
        - secret-key1
        - secret-key2
      ```

- API {#api}

  To create a version based on an existing version, use the [addVersion](../api-ref/Secret/addVersion.md) REST API method for the [Secret](../api-ref/Secret/index.md) resource or the [SecretService/AddVersion](../api-ref/grpc/Secret/addVersion.md) gRPC API call.

{% endlist %}

## Changing the current version {#backup}

{% list tabs group=instructions %}

- Management console {#console}

    1. In the [management console](https://console.yandex.cloud), select the folder the secret belongs to.
    1. Navigate to **Lockbox**.
    1. Click the name of the secret you need.
    1. Under **Versions**, next to the appropriate version, click ![image](../../_assets/console-icons/ellipsis.svg).
    1. Select ![image](../../_assets/console-icons/flag.svg) **Set as current version**.

- API {#api}

  To change the current version, use the [addVersion](../api-ref/Secret/addVersion.md) REST API method for the [Secret](../api-ref/Secret/index.md) resource or the [SecretService/AddVersion](../api-ref/grpc/Secret/addVersion.md) gRPC API call and specify the required version.

{% endlist %}

## Scheduling a version for deletion {#set-deleting-time}

{% list tabs group=instructions %}

- Management console {#console}

    1. In the [management console](https://console.yandex.cloud), select the folder the secret belongs to.
    1. Navigate to **Lockbox**.
    1. Click the name of the secret you need.
    1. Under **Versions**, next to the appropriate version, click ![image](../../_assets/console-icons/ellipsis.svg).
    1. Select ![image](../../_assets/console-icons/trash-bin.svg) **Schedule destruction**.
    1. Enter the deletion pending period.
    1. Click **Schedule**.

- CLI {#cli}

  If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../cli/quickstart.md#install).

  The folder used by default is the one specified when [creating](../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set folder-id <folder_ID>` command. You can also specify a different folder for any command using `--folder-name` or `--folder-id`. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

  1. See the description of the CLI command to schedule version deletion:

      ```bash
      yc lockbox secret schedule-version-destruction --help
      ```
  1. Schedule a version for deletion by specifying the secret name, version ID, and the deletion pending period. For example, 1 week: `168h`:

      ```bash
      yc lockbox secret schedule-version-destruction <secret_name> \
        --version-id <version_ID> \
        --pending-period 168h
      ```
      Result:

      ```text
      id: e6qor8pe3ju7********
      secret_id: e6qkkp3k29jf********
      created_at: "2023-11-08T13:14:34.676Z"
      destroy_at: "2023-11-15T17:06:28.795Z"
      status: SCHEDULED_FOR_DESTRUCTION
      payload_entry_keys:
        - secret-key
      ```

- Terraform {#tf}

  To schedule the removal of a version, remove the resource description for that version from the configuration file. You cannot use Terraform to set time to deletion, it will be set by default: 7 days.

- API {#api}

  To schedule a version for deletion, use the [scheduleVersionDestruction](../api-ref/Secret/addVersion.md) REST API method for the [Secret](../api-ref/Secret/index.md) resource or the [SecretService/ScheduleVersionDestruction](../api-ref/grpc/Secret/scheduleVersionDestruction.md) gRPC API call.

{% endlist %}

#### Useful links {#see-also}

[Secrets in Yandex Lockbox](../concepts/secret.md)