[Документация Yandex Cloud](../index.md) > [Yandex Lockbox](index.md) > Начало работы

# Начало работы с Yandex Lockbox


{% note info %}

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

{% endnote %}


Создайте ваш первый секрет и получите его содержимое.

Секрет состоит из набора версий, в которых хранятся ваши данные. Версия содержит наборы ключей и значений:
* Ключ — это несекретное название для значения, по которому вы будете его идентифицировать.
* Значение — это секретные данные.

Версия не изменяется. Для любого изменения количества пар ключей-значений или их содержимого необходимо создать новую версию.

## Создать секрет {#secret}

Чтобы создать [секрет](concepts/secret.md):

{% list tabs group=instructions %}

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

  1. В [консоли управления](https://kz.console.yandex.cloud) выберите [каталог](../resource-manager/concepts/resources-hierarchy.md#folder), в котором будет создан секрет.
  1. Перейдите в сервис **Lockbox**.
  1. Нажмите кнопку **Создать секрет**.
  1. В поле **Имя** введите имя секрета.
  1. (Опционально) Для разделения ресурсов на логические группы добавьте [метку](../resource-manager/concepts/labels.md).
  1. (Опционально) Включите опцию **Запретить удаление секрета**. Пока опция включена, удалить секрет невозможно. Не защищает содержимое секрета от изменения.
  1. Выберите **Тип секрета**:
      * **Генерируемый** — значение формируется автоматически:
  
        * В поле **Ключ** введите неконфиденциальный идентификатор.
        * (Опционально) Разверните блок **Параметры автоматической генерации** и задайте парамеры для конфиденциального значения (например, пароля).
  
      * **Пользовательский** — значение задается вручную:

        * В поле **Ключ** введите неконфиденциальный идентификатор.
        * В поле **Значение** введите конфиденциальные данные для хранения.

          Чтобы добавить больше данных, нажмите кнопку **Добавить ключ/значение** и повторите шаги.
  1. (Опционально) В поле **Ключ KMS** укажите существующий [ключ](../kms/concepts/key.md) или [создайте новый](../kms/operations/key.md#create).

     Указанный ключ [Yandex Key Management Service](../kms/index.md) используется для шифрования секрета. Если вы не будете указывать ключ, секрет будет зашифрован специальным системным ключом.

     {% note tip %}

     Использование своего ключа Key Management Service дает возможность использовать все преимущества сервиса Key Management Service.

     {% endnote %}

  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 create --help
     ```

  1. Выполните команду:

     ```bash
     yc lockbox secret create \
       --name <имя_секрета> \
       --description <описание_секрета> \
       --payload "<массив_с_содержимым_секрета>" \
       --cloud-id <идентификатор_облака> \
       --folder-id <идентификатор_каталога> \
       --deletion-protection
     ```

     Где:
     * `--name` — имя секрета. Обязательный параметр.
     * `--description` — описание секрета. Необязательный параметр.
     * `--payload` — содержимое секрета в виде массива формата YAML или JSON.

       Вы можете одновременно передать один или несколько [ключей](../kms/concepts/key.md) `key`. Если секрет будет содержать несколько значений, перечислите их через запятую. Если ключи будут содержать значения в бинарном формате, передавайте их в кодировке `base64`.

       >Например, для сохранения ключа `username` с текстовым значением `myusername` и ключа `avatar` с загруженным из файла `avatar.jpg` значением в бинарном формате можно указать:
       >
       >`[{'key': 'username', 'text_value': 'myusername'},{'key': 'avatar', 'binary_value': $(base64 -w 0 ./avatar.jpg)}]`
     * `--cloud-id` — [идентификатор облака](../resource-manager/operations/cloud/get-id.md), в котором будет создан секрет.
     * `--folder-id` — [идентификатор каталога](../resource-manager/operations/folder/get-id.md), в котором будет создан секрет.
     * `--deletion-protection` — защита от удаления секрета. Пока опция включена, удалить секрет невозможно. Не защищает содержимое секрета. Необязательный параметр.

     >Пример команды для создания секрета:
     >
     >```bash
     >yc lockbox secret create \
     >  --name sample-secret \
     >  --description sample_secret \
     >  --payload "[{'key': 'username', 'text_value': 'myusername'},{'key': 'avatar', 'binary_value': $(base64 -w 0 ./avatar.jpg)}]" \
     >  --cloud-id b1gwa87mbaom******** \
     >  --folder-id b1qt6g8ht345******** \
     >  --deletion-protection
     >```
     >
     >В этом примере создается секрет с двумя ключами: один ключ с текстовым значением, другой — со значением в бинарном формате.
     >
     >Результат:
     >
     >```text
     >id: e6q6nbjfu9m2********
     >folder_id: b1qt6g8ht345********
     >created_at: "2023-10-09T16:29:11.402Z"
     >...
     >    - username
     >    - avatar
     >deletion_protection: true
     >```

- Terraform {#tf}

  Секрет содержит только метаинформацию о себе: имя, описание, уникальный идентификатор и т. д. Для начала работы с секретом необходимо, после его создания, [создать версию](operations/secret-version-manage.md) секрета.

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

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

     ```hcl
     resource "yandex_lockbox_secret" "my_secret" {
       name                = "<имя_секрета>"
       description         = "<описание_секрета>"
       folder_id           = "<идентификатор_каталога>"
       kms_key_id          = "<идентификатор_ключа_шифрования>"
       deletion_protection = <флаг_защиты_от_удаления>
       labels              = {
         <ключ_метки_1> = "<значение_метки_1>",
         <ключ_метки_2> = "<значение_метки_2>"
       }
     }
     ```

     Где:
     * `name` — имя секрета. Обязательный параметр.
     * `description` — описание секрета. Необязательный параметр.
     * `folder_id` — [идентификатор](../resource-manager/operations/folder/get-id.md) [каталога](../resource-manager/concepts/resources-hierarchy.md#folder) в котором будет создан секрет. Необязательный параметр.
     * `kms_key_id` — идентификатор [ключа шифрования Key Management Service](../kms/concepts/key.md). Указанный ключ Key Management Service используется для шифрования секрета. Если не указывать ключ Key Management Service, секрет будет зашифрован специальным системным ключом. Необязательный параметр.
     * `deletion_protection` — флаг защиты от удаления. Для включения защиты укажите значение `true`. Для отключения защиты — `false`. Значение по умолчанию `false`. Необязательный параметр.
     * `labels` — [метка](../overview/concepts/services.md#labels) ресурса в формате `<ключ>:"<значение>"`. Необязательный параметр.

     Более подробную информацию о параметрах ресурса `yandex_lockbox_secret` в Terraform, смотрите в [документации провайдера](../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 secret get <имя_секрета>
  ```

- API {#api}

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

{% endlist %}

## Получить содержимое секрета {#get}

### Роли, необходимые для получения секрета {#roles}

Если при создании секрета вы указали свой ключ KMS, необходимо назначить на этот секрет роли [kms.keys.encrypterDecrypter](../kms/security/index.md#service-roles) и [lockbox.payloadViewer](security/index.md#roles-list). Они нужны для получения доступа к ключу, а также для шифрования и расшифровки.

### Получите содержимое секрета {#payload}

{% 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 payload get --help
      ```

  1. Получите идентификатор секрета (столбец `ID` в выводе команды):
     
        ```bash
        yc lockbox secret list
        ```
     
        Результат:
     
        ```text
        +----------------------+-------------+------------+---------------------+----------------------+--------+
        |          ID          |    NAME     | KMS KEY ID |     CREATED AT      |  CURRENT VERSION ID  | STATUS |
        +----------------------+-------------+------------+---------------------+----------------------+--------+
        | e6qetpqfe8vvag9h7jkr | test-secret |            | 2023-12-06 15:12:13 | e6qdnt9t2qsdggusve4g | ACTIVE |
        +----------------------+-------------+------------+---------------------+----------------------+--------+
        ```

  1. Выполните команду:

      ```bash
      yc lockbox payload get \
        --id <идентификатор_секрета> \
        --key <ключ_секрета> \
        --version-id <идентификатор_версии_секрета>
      ```

      Где:

      * `--id` — идентификатор секрета. Обязательный параметр.
      * `--key` – ключ содержимого секрета для получения единственного значения. Необязательный параметр.
      * `--version-id` – версия секрета. Необязательный параметр. По умолчанию используется текущая версия секрета.

      Пример команды для получения содержимого секрета:

      ```bash
      yc lockbox payload get \
        --id e6qetpqfe8vv******** \
        --version-id e6qqr7k79ecm********
      ```

      В этом примере возвращается содержимое секрета версии `e6qqr7k79ecm********`.

      Результат:

      ```text
      version_id: e6qqr7k79ecm********
      entries:
        - key: first_key
          text_value: value_1
        - key: second_key
          text_value: value_2
      ```

      Если в качестве конфиденциального значения используется файл, то содержимое секрета возвращается в [кодировке Base64](https://ru.wikipedia.org/wiki/Base64). Вы можете декодировать файл с помощью утилиты base64 на Linux:
      
      ```bash
      base64 --decode <путь_к_файлу> > output.txt
      ```

- API {#api}

    При запросе без указания версии будет возвращаться содержимое текущей (последней) версии.

    Вы можете использовать эту логику в скриптах, сервисах и приложениях, где необходимо использовать содержимое секрета.

    Чтобы получить содержимое секрета:
    1. [Получите IAM-токен](../iam/operations/iam-token/create.md), необходимый для аутентификации и сохраните его в переменную:

        ```
        export IAM_TOKEN=$(yc iam create-token)
        ```

        Также вы можете получить IAM-токен сервисного аккаунта изнутри [ВМ](../glossary/vm.md), к которой он привязан. Для этого выполните запрос в [сервис метаданных](../compute/operations/vm-info/get-info.md#request-examples). Пример с использованием утилиты [jq](https://stedolan.github.io/jq/):
        
        ```
        export IAM_TOKEN=$(curl --header Metadata-Flavor:Google http://169.254.169.254/computeMetadata/v1/instance/service-accounts/default/token | jq -r .access_token)
        ```

    1. Выполните запрос:

        ```
        curl \
          --request GET \
          --header "Authorization: Bearer ${IAM_TOKEN}" \
          https://dpl.lockbox.api.yandexcloud.kz/lockbox/v1/secrets/<идентификатор_секрета>/payload
        ```

    Если в качестве конфиденциального значения используется файл, то содержимое секрета возвращается в [кодировке Base64](https://ru.wikipedia.org/wiki/Base64). Вы можете декодировать файл с помощью модуля [base64 в Python](https://docs.python.org/3/library/base64.html) или других инструментов.

{% endlist %}

Вы можете управлять секретами и их содержимым не только при помощи [консоли управления](https://kz.console.yandex.cloud), [CLI](../cli/quickstart.md) и [API](../overview/api.md), но и с использованием SDK для популярных языков программирования. Подробнее в разделе [Интерфейсы работы с сервисом](concepts/index.md#interface).