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

Если у вас еще нет интерфейса командной строки Yandex Cloud, установите и инициализируйте его.

По умолчанию используется каталог, указанный в профиле CLI. Вы можете указать другой каталог с помощью параметра --folder-name или --folder-id.

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

   yc lockbox secret create --help
   

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

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

   Где:

   • --name — имя секрета. Обязательный параметр.

   • --description — описание секрета. Необязательный параметр.

   • --payload — содержимое секрета в виде массива формата YAML или JSON.

     Вы можете одновременно передать один или несколько ключей key. Если секрет будет содержать несколько значений, перечислите их через запятую. Если ключи будут содержать значения в бинарном формате, передавайте их в кодировке base64.

     Например, для сохранения ключа username с текстовым значением myusername и ключа avatar с загруженным из файла avatar.jpg значением в бинарном формате можно указать:

     [{'key': 'username', 'text_value': 'myusername'},{'key': 'avatar', 'binary_value': $(base64 -w 0 ./avatar.jpg)}]

   • --cloud-id — идентификатор облака, в котором будет создан секрет.

   • --folder-id — идентификатор каталога, в котором будет создан секрет.

   • --deletion-protection — защита от удаления секрета. Пока опция включена, удалить секрет невозможно. Не защищает содержимое секрета. Необязательный параметр.

   Пример команды для создания секрета:

   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
   

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

   Результат:

   id: e6q6nbjfu9m2********
   folder_id: b1qt6g8ht345********
   created_at: "2023-10-09T16:29:11.402Z"
   ...
      - username
      - avatar
   deletion_protection: true
   

Секрет содержит только метаинформацию о себе: имя, описание, уникальный идентификатор и т. д. Для начала работы с секретом необходимо создать версию секрета.

Если у вас еще нет Terraform, установите его и настройте провайдер Yandex Cloud.

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

   terraform {
     required_providers {
       yandex = {
         source = "yandex-cloud/yandex"
       }
     }
     required_version = ">= 0.13"
   }
   provider "yandex" {
     zone = "ru-central1-a"
   }
   
   resource "yandex_lockbox_secret" "my_secret" {
     name                = "<имя_секрета>"
     description         = "<описание_секрета>"
     folder_id           = "<идентификатор_каталога>"
     kms_key_id          = "<идентификатор_ключа_шифрования>"
     deletion_protection = <флаг_защиты_от_удаления>
     labels              = {
       <ключ_метки_1>  = "<значение_метки_1>",
       <ключ_метки_2>  = "<значение_метки_2>"
     }
   }
   

   Где:

   • name — имя секрета. Обязательный параметр.
   • description — описание секрета. Необязательный параметр.
   • folder_id — идентификатор каталога в котором будет создан секрет. Необязательный параметр.
   • kms_key_id — идентификатор ключа шифрования Key Management Service. Указанный ключ Key Management Service используется для шифрования секрета. Если не указывать ключ Key Management Service, секрет будет зашифрован специальным системным ключом. Необязательный параметр.
   • deletion_protection — флаг защиты от удаления. Для включения защиты укажите значение true. Для отключения защиты — false. Значение по умолчанию false. Необязательный параметр.
   • labels — метка ресурса в формате <ключ>:"<значение>". Необязательный параметр.

   Более подробную информацию о параметрах ресурса yandex_lockbox_secret в Terraform, см. в документации провайдера.

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

   1. В терминале перейдите в папку, где вы отредактировали конфигурационный файл.

   2. Проверьте корректность конфигурационного файла с помощью команды:

      terraform validate
      

      Если конфигурация является корректной, появится сообщение:

      Success! The configuration is valid.
      

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

      terraform plan
      

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

   4. Примените изменения конфигурации:

      terraform apply
      

   5. Подтвердите изменения: введите в терминале слово yes и нажмите Enter.

После этого в указанном каталоге будет создан секрет. Проверить появление секрета и его настройки можно в консоли управления или с помощью команды CLI:

yc lockbox secret get <имя_секрета>

Чтобы создать секрет, воспользуйтесь методом REST API create для ресурса Secret или вызовом gRPC API SecretService/Create.

Если у вас еще нет интерфейса командной строки Yandex Cloud, установите и инициализируйте его.

По умолчанию используется каталог, указанный в профиле CLI. Вы можете указать другой каталог с помощью параметра --folder-name или --folder-id.

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

   yc lockbox payload get --help
   

2. Получите идентификатор секрета (столбец ID в выводе команды):

   yc lockbox secret list
   

   Результат:

   +----------------------+-------------+------------+---------------------+----------------------+--------+
   |          ID          |    NAME     | KMS KEY ID |     CREATED AT      |  CURRENT VERSION ID  | STATUS |
   +----------------------+-------------+------------+---------------------+----------------------+--------+
   | e6qetpqfe8vvag9h7jkr | test-secret |            | 2023-12-06 15:12:13 | e6qdnt9t2qsdggusve4g | ACTIVE |
   +----------------------+-------------+------------+---------------------+----------------------+--------+
   

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

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

   Где:

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

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

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

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

   Результат:

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

   Если в качестве конфиденциального значения используется файл, то содержимое секрета возвращается в кодировке Base64. Вы можете декодировать файл с помощью утилиты base64 на Linux:

   base64 --decode <путь_к_файлу> > output.txt
   

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

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

Чтобы получить содержимое секрета:

1. Получите IAM-токен, необходимый для аутентификации и сохраните его в переменную:

   export IAM_TOKEN=$(yc iam create-token)
   

   Также вы можете получить IAM-токен сервисного аккаунта изнутри ВМ, к которой он привязан. Для этого выполните запрос в сервис метаданных. Пример с использованием утилиты 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)
   

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

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

Если в качестве конфиденциального значения используется файл, то содержимое секрета возвращается в кодировке Base64. Вы можете декодировать файл с помощью модуля base64 в Python или других инструментов.