[Документация Yandex Cloud](../../index.md) > [Yandex Lockbox](../index.md) > [Пошаговые инструкции](index.md) > Управление версиями секрета

# Управление версиями секрета


{% note info %}

В [регионе Казахстан](../../overview/concepts/region.md) доступна только [зона доступности](../../overview/concepts/geo-scope.md) `kz1-a`.

{% endnote %}


Управление версиями секрета позволяет:

* [Создать новую версию пользовательского секрета](#create-version).
* [Создать новую версию генерируемого секрета](#create-generated-version).
* [Получить информацию о версии](#get-version).
* [Создать версию на основе существующей](#create-version-based-on-other).
* [Откатиться к определенной версии](#backup).
* [Запланировать удаление версии](#set-deleting-time).

## Создать новую версию пользовательского секрета {#create-version}

{% list tabs group=instructions %}

- Консоль управления {#console}

    1. В [консоли управления](https://kz.console.yandex.cloud) выберите каталог, которому принадлежит секрет.
    1. Перейдите в сервис **Lockbox**.
    1. Нажмите на имя нужного секрета.
    1. В разделе **Версии** нажмите **Добавить версию**.
    1. Добавьте следующие параметры:
        * (Опционально) **Описание** — описание версии.
        * **Ключ** — несекретное название для значения, по которому вы будете его идентифицировать.
        * **Значение** — секретные данные в явном виде.
        Вы можете создать несколько пар ключей и значений в одной версии.
        
    1. Нажмите кнопку **Добавить версию**.

- Terraform {#tf}

  [Terraform](https://www.terraform.io/) позволяет быстро создать облачную инфраструктуру в Yandex Cloud и управлять ею с помощью файлов конфигураций. В файлах конфигураций хранится описание инфраструктуры на языке HCL (HashiCorp Configuration Language). При изменении файлов конфигураций Terraform автоматически определяет, какая часть вашей конфигурации уже развернута, что следует добавить или удалить.
  
  Terraform распространяется под лицензией [Business Source License](https://github.com/hashicorp/terraform/blob/main/LICENSE), а [провайдер Yandex Cloud для Terraform](https://github.com/yandex-cloud/terraform-provider-yandex) — под лицензией [MPL-2.0](https://www.mozilla.org/en-US/MPL/2.0/).
  
  Подробная информация о ресурсах провайдера в документации на сайте [Terraform](https://www.terraform.io/docs/providers/yandex/index.html) или в [зеркале](../../terraform/index.md).

  Если у вас еще нет Terraform, [установите его и настройте провайдер Yandex Cloud](../../tutorials/infrastructure-management/terraform-quickstart.md#install-terraform).
  
  
  Чтобы управлять инфраструктурой с помощью Terraform от имени сервисного аккаунта или пользовательских аккаунтов: аккаунта на Яндексе, федеративного аккаунта и локального пользователя, [аутентифицируйтесь](../../terraform/authentication.md) соответствующим способом.

  1. Опишите в конфигурационном файле параметры ресурсов, которые необходимо создать:

      ```hcl
      resource "yandex_lockbox_secret_version_hashed" "my_version" {
        secret_id    = "<идентификатор_секрета>"

        key_1        = "<ключ_секрета_1>"
        text_value_1 = "<значение_секрета_1>"

        key_2        = "<ключ_секрета_2>"
        text_value_2 = "<значение_секрета_2>"
      }
      ```

      Где:

      * `secret_id` — идентификатор секрета, для которого создается версия.
      * (Опционально) `description` — произвольный комментарий к версии секрета.
      * `key_N` — ключ секрета. Несекретное название для значения, по которому вы будете его идентифицировать.
      * `text_value_N` — секретные данные в явном виде.

      Пары `key_N/text_value_N` нумеруются последовательно от 1 до 10 (поддерживается 10 пар). Если нужна только одна пара, используйте `key_1/text_value_1`.

      {% note info %}
      
      Рекомендуется использовать ресурс `yandex_lockbox_secret_version_hashed`, он хранит в состоянии Terraform значения в хешированном виде. Поддержка ресурса `yandex_lockbox_secret_version` остается.
      
      Более подробную информацию о ресурсе `yandex_lockbox_secret_version_hashed` смотрите в [документации провайдера](../../terraform/resources/lockbox_secret_version_hashed.md).
      
      {% endnote %}

  1. Создайте ресурсы:

      1. В терминале перейдите в директорию с конфигурационным файлом.
      1. Проверьте корректность конфигурации с помощью команды:
      
         ```bash
         terraform validate
         ```
      
         Если конфигурация является корректной, появится сообщение:
      
         ```bash
         Success! The configuration is valid.
         ```
      
      1. Выполните команду:
      
         ```bash
         terraform plan
         ```
      
         В терминале будет выведен список ресурсов с параметрами. На этом этапе изменения не будут внесены. Если в конфигурации есть ошибки, Terraform на них укажет.
      1. Примените изменения конфигурации:
      
         ```bash
         terraform apply
         ```
      
      1. Подтвердите изменения: введите в терминале слово `yes` и нажмите **Enter**.

  После этого для указанного секрета будет создана версия. Проверить появление версии и ее настройки можно в [консоли управления](https://kz.console.yandex.cloud) или с помощью команды [CLI](../../cli/quickstart.md):

  ```bash
  yc lockbox secret list-versions <идентификатор_секрета>
  ```

- API {#api}

  Чтобы создать новую версию секрета, воспользуйтесь методом REST API [addVersion](../api-ref/Secret/addVersion.md) для ресурса [Secret](../api-ref/Secret/index.md) или вызовом gRPC API [SecretService/AddVersion](../api-ref/grpc/Secret/addVersion.md).

{% endlist %}

## Создать новую версию генерируемого секрета {#create-generated-version}

{% list tabs group=instructions %}

- Консоль управления {#console}

    1. В [консоли управления](https://kz.console.yandex.cloud) выберите каталог, которому принадлежит секрет.
    1. Перейдите в сервис **Lockbox**.
    1. Нажмите на имя нужного секрета.
    1. В разделе **Версии** нажмите **Добавить версию**.
    1. (Опционально) Добавьте **Описание** версии.
    1. (Опционально) Чтобы изменить другие параметры, нажмите **Редактировать** и укажите:
       * **Тип секрета** — вы можете оставить генерируемый тип или выбрать пользовательский.
       * **Ключ** и **Параметры автоматической генерации** — для генерируемого типа секрета.
       * **Ключ** и **Значение** — для пользовательского типа секрета.

          Вы можете создать несколько пар ключей и значений в одной версии.
    1. Нажмите кнопку **Добавить версию** или **Сохранить**.


- Terraform {#tf}

    #### Генерация секрета с помощью Yandex Cloud

    [Terraform](https://www.terraform.io/) позволяет быстро создать облачную инфраструктуру в Yandex Cloud и управлять ею с помощью файлов конфигураций. В файлах конфигураций хранится описание инфраструктуры на языке HCL (HashiCorp Configuration Language). При изменении файлов конфигураций Terraform автоматически определяет, какая часть вашей конфигурации уже развернута, что следует добавить или удалить.
    
    Terraform распространяется под лицензией [Business Source License](https://github.com/hashicorp/terraform/blob/main/LICENSE), а [провайдер Yandex Cloud для Terraform](https://github.com/yandex-cloud/terraform-provider-yandex) — под лицензией [MPL-2.0](https://www.mozilla.org/en-US/MPL/2.0/).
    
    Подробная информация о ресурсах провайдера в документации на сайте [Terraform](https://www.terraform.io/docs/providers/yandex/index.html) или в [зеркале](../../terraform/index.md).

    Если у вас еще нет Terraform, [установите его и настройте провайдер Yandex Cloud](../../tutorials/infrastructure-management/terraform-quickstart.md#install-terraform).
    
    
    Чтобы управлять инфраструктурой с помощью Terraform от имени сервисного аккаунта или пользовательских аккаунтов: аккаунта на Яндексе, федеративного аккаунта и локального пользователя, [аутентифицируйтесь](../../terraform/authentication.md) соответствующим способом.

    1. Вы можете создать новую версию генерируемого секрета, при его [создании](secret-create.md). Укажите в описании ресурса `yandex_lockbox_secret` параметры генерации секрета в блоке `password_payload_specification` и создайте новую версию секрета с указанием на этот секрет:
  
       ```hcl
       # Создание генерируемого секрета
       resource "yandex_lockbox_secret" "my_secret" {
         name = "<имя_секрета>"

         password_payload_specification {
           password_key        = "<ключ_секрета>"
           length              = "<длина>"
           include_uppercase   = true
           include_lowercase   = true
           include_digits      = true
           include_punctuation = true
         }
       }

       # Создание версии секрета
       resource "yandex_lockbox_secret_version" "my_version" {
         secret_id = yandex_lockbox_secret.my_secret.id
       }
       ```
  
       Где:
       * `password_payload_specification` — параметры генерации секрета:
         * `password_key` — ключ секрета. Несекретное название для значения, по которому вы будете его идентифицировать.
         * `length` — длина генерируемого значения секрета. Обязательный параметр.
         * `include_uppercase ` — использовать заглавные буквы латинского алфавита (A...Z). Значение по умолчанию `true`.
         * `include_lowercase` — использовать строчные буквы латинского алфавита (a...z). Значение по умолчанию `true`.
         * `include_digits` — использовать цифры (0...9). Значение по умолчанию `true`.
         * `include_punctuation` — использовать специальные символы. Значение по умолчанию `true`.

       Подробнее о параметрах ресурса `yandex_lockbox_secret` в [документации провайдера](../../terraform/resources/lockbox_secret.md).

    1. Примените изменения:

       1. В терминале перейдите в директорию с конфигурационным файлом.
       1. Проверьте корректность конфигурации с помощью команды:
       
          ```bash
          terraform validate
          ```
       
          Если конфигурация является корректной, появится сообщение:
       
          ```bash
          Success! The configuration is valid.
          ```
       
       1. Выполните команду:
       
          ```bash
          terraform plan
          ```
       
          В терминале будет выведен список ресурсов с параметрами. На этом этапе изменения не будут внесены. Если в конфигурации есть ошибки, Terraform на них укажет.
       1. Примените изменения конфигурации:
       
          ```bash
          terraform apply
          ```
       
       1. Подтвердите изменения: введите в терминале слово `yes` и нажмите **Enter**.
  
    Проверить появление секрета и его содержимое можно в [консоли управления](https://kz.console.yandex.cloud) или с помощью команды [CLI](../../cli/index.md):
  
    ```bash
    yc lockbox payload get <имя_или_идентификатор_секрета>
    ```

    #### Генерация секрета с помощью пользовательского скрипта

    Вы можете создать новую версию генерируемого секрета, используя собственный скрипт для генерации секрета. Значение, сгенерированное скриптом, не будет отображаться в State Terraform.

    {% cut "Пример bash скрипта для генерации секрета" %}
    
    ```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. Укажите в описании ресурса `yandex_lockbox_secret_version` в блоке `entries` параметр `command.path` — путь к скрипту для генерации пароля.

       ```hcl
       # Создание версии секрета с генерация пароля скриптом
       resource "yandex_lockbox_secret_version" "my_version" {
         secret_id = "<идентификатор_секрета>"

         entries {
           key = "<ключ_секрета>"
           command {
             path = "<путь_к_скрипту>"
           }
         }
       }
       ```

       Где:
       * `secret_id` — идентификатор секрета, для которого создается версия.
       * `key` — ключ секрета. Несекретное название для значения, по которому вы будете его идентифицировать.
       * `path` — путь к скрипту для генерации значения секрета.

       Подробнее о параметрах ресурса `yandex_lockbox_secret_version` в [документации провайдера](../../terraform/resources/lockbox_secret_version.md).

    1. Примените изменения:

       1. В терминале перейдите в директорию с конфигурационным файлом.
       1. Проверьте корректность конфигурации с помощью команды:
       
          ```bash
          terraform validate
          ```
       
          Если конфигурация является корректной, появится сообщение:
       
          ```bash
          Success! The configuration is valid.
          ```
       
       1. Выполните команду:
       
          ```bash
          terraform plan
          ```
       
          В терминале будет выведен список ресурсов с параметрами. На этом этапе изменения не будут внесены. Если в конфигурации есть ошибки, Terraform на них укажет.
       1. Примените изменения конфигурации:
       
          ```bash
          terraform apply
          ```
       
       1. Подтвердите изменения: введите в терминале слово `yes` и нажмите **Enter**.
  
    Проверить появление секрета и его содержимое можно в [консоли управления](https://kz.console.yandex.cloud) или с помощью команды [CLI](../../cli/index.md):
  
    ```bash
    yc lockbox payload get <имя_или_идентификатор_секрета>
    ```

{% endlist %}

## Получить информацию о версии {#get-version}

{% list tabs group=instructions %}

- Консоль управления {#console}

    1. В [консоли управления](https://kz.console.yandex.cloud) выберите каталог, которому принадлежит секрет.
    1. Перейдите в сервис **Lockbox**.
    1. Нажмите на имя нужного секрета.
    1. В разделе **Версии** будет показан список всех версий секрета и информация о них.
    1. Нажмите на нужную версию, чтобы получить информацию о ее парах ключ — значение.

- CLI {#cli}

  Если у вас еще нет интерфейса командной строки Yandex Cloud (CLI), [установите и инициализируйте его](../../cli/quickstart.md#install).

  По умолчанию используется каталог, указанный при [создании](../../cli/operations/profile/profile-create.md) профиля CLI. Чтобы изменить каталог по умолчанию, используйте команду `yc config set folder-id <идентификатор_каталога>`. Также для любой команды вы можете указать другой каталог с помощью параметров `--folder-name` или `--folder-id`. Если вы обращаетесь к ресурсу по имени, поиск будет выполнен в каталоге по умолчанию. Если вы обращаетесь к ресурсу по идентификатору, поиск будет выполнен глобально — во всех каталогах с учетом прав доступа.

  1. Посмотрите описание команды CLI для просмотра версий секрета:

      ```bash
      yc lockbox secret list-version --help
      ```
  1. Выполните команду:
      
      ```bash
      yc lockbox secret list-version <имя_секрета>
      ```

  Будет отображена информация обо всех версиях секрета, содержащая имена ключей. Значения версий секрета отображаться не будут.

- API {#api}

  Чтобы получить информацию о версии, воспользуйтесь методом REST API [listVersions](../api-ref/Secret/listVersions.md) для ресурса [Secret](../api-ref/Secret/index.md) или вызовом gRPC API [SecretService/ListVersions](../api-ref/grpc/Secret/listVersions.md).

{% endlist %}

## Создать версию на основе существующей {#create-version-based-on-other}

{% list tabs group=instructions %}

- Консоль управления {#console}

    1. В [консоли управления](https://kz.console.yandex.cloud) выберите каталог, которому принадлежит секрет.
    1. Перейдите в сервис **Lockbox**.
    1. Нажмите на имя нужного секрета.
    1. В разделе **Версии**, напротив нужной версии нажмите ![image](../../_assets/console-icons/ellipsis.svg).
    1. Выберите пункт **Создать версию на основе этой**.
    1. Измените или добавьте следующие параметры:
        * (Опционально) **Описание** — описание версии.
        * **Ключ** — несекретное название для значения, по которому вы будете его идентифицировать.
        * Для пользовательского секрета **Значение** — секретные данные в явном виде.
        Вы можете создать несколько пар ключей и значений в одной версии.
        * Для генерируемого секрета вы можете изменить ключ и параметры значения. Для этого нажмите **Редактировать секрет** и [укажите новые параметры](secret-update.md).
    1. Нажмите кнопку **Добавить версию**.

- CLI {#cli}

  Если у вас еще нет интерфейса командной строки Yandex Cloud (CLI), [установите и инициализируйте его](../../cli/quickstart.md#install).

  По умолчанию используется каталог, указанный при [создании](../../cli/operations/profile/profile-create.md) профиля CLI. Чтобы изменить каталог по умолчанию, используйте команду `yc config set folder-id <идентификатор_каталога>`. Также для любой команды вы можете указать другой каталог с помощью параметров `--folder-name` или `--folder-id`. Если вы обращаетесь к ресурсу по имени, поиск будет выполнен в каталоге по умолчанию. Если вы обращаетесь к ресурсу по идентификатору, поиск будет выполнен глобально — во всех каталогах с учетом прав доступа.

  1. Посмотрите описание команды CLI для создания новой версии секрета:

      ```bash
      yc lockbox secret add-version --help
      ```
  1. Выполните команду:
      
      ```bash
      yc lockbox secret add-version <имя_секрета> \
        --description <описание_версии_секрета> \
        --payload "<массив_с_содержимым_версии_секрета>" \
        --base-version-id <идентификатор_существующей_версии_секрета>
      ```

      Где:
     * `<имя_секрета>` — имя секрета, для которого создается версия.
     * `--description` — описание новой версии секрета (необязательно).
     * `--payload` — содержимое новой версии секрета в виде массива формата YAML или JSON.
     * `--base-version-id` — идентификатор версии секрета, на основе которой требуется создать новый секрет. Если параметр не указан, новая версия будет создана на основе текущей версии.

      Результат:

      ```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}

  Чтобы создать версию на основе существующей, воспользуйтесь методом REST API [addVersion](../api-ref/Secret/addVersion.md) для ресурса [Secret](../api-ref/Secret/index.md) или вызовом gRPC API [SecretService/AddVersion](../api-ref/grpc/Secret/addVersion.md).

{% endlist %}

## Изменить текущую версию {#backup}

{% list tabs group=instructions %}

- Консоль управления {#console}

    1. В [консоли управления](https://kz.console.yandex.cloud) выберите каталог, которому принадлежит секрет.
    1. Перейдите в сервис **Lockbox**.
    1. Нажмите на имя нужного секрета.
    1. В разделе **Версии**, напротив нужной версии нажмите ![image](../../_assets/console-icons/ellipsis.svg).
    1. Выберите пункт ![image](../../_assets/console-icons/flag.svg) **Сделать текущей версией**.

- API {#api}

  Чтобы изменить текущую версию, воспользуйтесь методом REST API [addVersion](../api-ref/Secret/addVersion.md) для ресурса [Secret](../api-ref/Secret/index.md) или вызовом gRPC API [SecretService/AddVersion](../api-ref/grpc/Secret/addVersion.md) с указанием целевой версии.

{% endlist %}

## Запланировать удаление версии {#set-deleting-time}

{% list tabs group=instructions %}

- Консоль управления {#console}

    1. В [консоли управления](https://kz.console.yandex.cloud) выберите каталог, которому принадлежит секрет.
    1. Перейдите в сервис **Lockbox**.
    1. Нажмите на имя нужного секрета.
    1. В разделе **Версии**, напротив нужной версии нажмите ![image](../../_assets/console-icons/ellipsis.svg).
    1. Выберите пункт ![image](../../_assets/console-icons/trash-bin.svg) **Запланировать удаление**.
    1. Введите время до удаления.
    1. Нажмите кнопку **Запланировать**.

- CLI {#cli}

  Если у вас еще нет интерфейса командной строки Yandex Cloud (CLI), [установите и инициализируйте его](../../cli/quickstart.md#install).

  По умолчанию используется каталог, указанный при [создании](../../cli/operations/profile/profile-create.md) профиля CLI. Чтобы изменить каталог по умолчанию, используйте команду `yc config set folder-id <идентификатор_каталога>`. Также для любой команды вы можете указать другой каталог с помощью параметров `--folder-name` или `--folder-id`. Если вы обращаетесь к ресурсу по имени, поиск будет выполнен в каталоге по умолчанию. Если вы обращаетесь к ресурсу по идентификатору, поиск будет выполнен глобально — во всех каталогах с учетом прав доступа.

  1. Посмотрите описание команды CLI для планирования удаления версии:

      ```bash
      yc lockbox secret schedule-version-destruction --help
      ```
  1. Запланируйте удаление версии, указав имя секрета, идентификатор версии и время до удаления. Например 1 неделя — `168h`:

      ```bash
      yc lockbox secret schedule-version-destruction <имя_секрета> \
        --version-id <идентификатор_версии> \
        --pending-period 168h
      ```
      Результат:

      ```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}

  Чтобы запланировать удаление версии, удалите из конфигурационного файла описание ресурсов этой версии. Через Terraform нельзя задать время до удаления, время будет установлено по умолчанию — 7 дней.

- API {#api}

  Чтобы запланировать удаление версии, воспользуйтесь методом REST API [scheduleVersionDestruction](../api-ref/Secret/addVersion.md) для ресурса [Secret](../api-ref/Secret/index.md) или вызовом gRPC API [SecretService/ScheduleVersionDestruction](../api-ref/grpc/Secret/scheduleVersionDestruction.md).

{% endlist %}

#### Полезные ссылки {#see-also}

[Секреты в Yandex Lockbox](../concepts/secret.md)