Для улучшения работы сайта мы используем файлы cookies. Оставаясь на сайте, вы соглашаетесь с политикой обработки персональных данных.

Механизм секретов VK Object Storage

Механизм секретов VK Object Storage выдает динамические учетные данные для доступа к VK Object Storage и управляет сроком их действия.

Данный функционал недоступен в StarVault, поставляемом в составе Nova.

При выдаче StarVault создает отдельную учетную запись VK Object Storage и добавляет для неё правила в политики бакетов. Правила StarVault собирает из шаблонов выбранной роли. Когда срок действия истекает или аренду отзывают вручную, StarVault удаляет эту учетную запись и связанные с выдачей правила.

1. Общие сведения

Понятие Описание

Путь монтирования

Путь подключенного экземпляра механизма в StarVault

Конфигурация соединения

Параметры доступа StarVault к VK Object Storage

Роль

Именованный набор шаблонов разрешений

Шаблон разрешений

Правило для бакета: действие, список операций, идентификаторы ресурсов и необязательное условие

Аренда

Запись о выданных учетных данных: срок, продление и отзыв

Срок действия

Время, в течение которого аренда остается действительной

В примерах путь монтирования — vk. Если механизм подключен по другому пути, подставьте этот путь. У каждого экземпляра свои настройки и роли.

2. Подготовка

Подготовьте:

  • статический ключ доступа и секретный ключ, с которыми StarVault обращается к API S3;

  • идентификатор проекта VK Object Storage;

  • адрес электронной почты для обращения к API Hotbox;

  • адрес API Hotbox,

  • адрес API S3,

  • регион S3, если он нужен в вашем окружении;

  • имена существующих бакетов, к которым нужно выдавать доступ.

Бакеты должны быть доступны учетным данным из конфигурации соединения. Политику бакета StarVault читает и изменяет через API S3. Учетными записями StarVault управляет через API Hotbox.

Адреса API и нужные права уточните у администратора VK Object Storage. В примерах нет рабочих ключей и адресов сервисов.

3. Включение механизма

3.1. С помощью CLI

Включите механизм с помощью команды:

starvault secrets enable vk

По умолчанию механизм хранения секретов будет монтироваться по имени механизма. Чтобы включить механизм хранения секретов по другому пути, используйте -pathсоответствующий аргумент.

3.2. С помощью веб-интерфейса

  1. Откройте раздел Секреты. Нажмите + Добавить.

  2. В подразделе Infra выберите VK Object Storage и нажмите Далее.

    vk 1
  3. Укажите путь монтирования, например vk.

  4. При необходимости измените стандартные параметры подключения.

    vk 2
  5. Подтвердите подключение, нажав Включить механизм.

После подключения откроется список ролей. У нового механизма список пуст.

vk 3

Подключение механизма и настройка соединения — разные операции. Перед выдачей учетных данных настройте соединение с VK Object Storage.

4. Настройка соединения

4.1. Первичная настройка

При чтении сохранённой конфигурации Secret key не возвращается.

4.1.1. С помощью CLI

Запишите параметры соединения с помощью команды:

$ starvault write vk/config/root \
    access_key=<access_key> \ (1)
    secret_key=<secret_key> \ (2)
    x_pid=<project_id> \ (3)
    x_email=admin@example.com \ (4)
    hotbox_endpoint=https://hotbox.example.com \ (5)
    s3_endpoint=https://s3.example.com \ (6)
    region=<region> \ (7)
    max_retries=3 (8)
1 access_key (string: <обязательный>) — идентификатор статического ключа S3.
2 secret_key (string: <обязательный>) — секретная часть ключа S3.
3 x_pid (string: <обязательный>) — идентификатор проекта VK Object Storage.
4 x_email (string: <обязательный>) — адрес электронной почты для обращения к API Hotbox.
5 hotbox_endpoint (string: <обязательный>) — адрес API Hotbox.
6 s3_endpoint (string: <обязательный>) — адрес API S3.
7 region (string: "" <необязательный>) — регион для запросов S3.
8 max_retries (int: <необязательный>) — максимальное число повторных попыток при восстановимых ошибках.

4.1.2. С помощью веб-интерфейса

  1. Откройте подключенный механизм в разделе Секреты.

  2. Перейдите к конфигурации и нажмите Настроить VK Object Storage >

    vk 4
  3. Заполните параметры соединения.

    vk 5
  4. Нажмите Сохранить.

4.1.3. С помощью API

Отправьте параметры соединения:

POST /v1/vk/config/root
Пример тела запроса
{
  "access_key": "<access_key>",
  "secret_key": "<secret_key>",
  "x_pid": "<project_id>",
  "x_email": "admin@example.com",
  "hotbox_endpoint": "https://hotbox.example.com",
  "s3_endpoint": "https://s3.example.com",
  "region": "<region>",
  "max_retries": 3
}

Параметры region и max_retries необязательны. Успешный ответ не содержит тела. Код ответа — 204.

Описание конечной точки приведено в разделе VK Object Storage (API).

Сохранение конфигурации не проверяет действительность ключей и доступность VK Object Storage. Успешное сохранение подтверждает запись параметров, а не проверку соединения.

4.2. Настройка срока действия

Если lease не задан или равен 0, используется системный срок по умолчанию. Фактический срок смотрите в результате выдачи.

4.2.1. С помощью CLI

Задайте срок аренды:

$ starvault write vk/config/lease \
    lease=30m \ (1)
    lease_max=12h (2)
1 lease — срок новой аренды, если при выдаче не задан другой.
2 lease_max — предел срока с учетом продлений.

4.2.2. С помощью веб-интерфейса

  1. Перейдите на страницу механизма в разделе Секреты.

  2. Перейдите на вкладку Конфигурация и нажмите > Конфигурировать.

  3. Нажмите на переключатель TTL и укажите значение.

    vk 6

4.2.3. С помощью API

Задайте срок аренды:

POST /v1/vk/config/lease
Пример тела запроса
{
  "lease": "30m",
  "lease_max": "12h"
}

Успешный ответ не содержит тела. Код ответа — 204.

Описание конечной точки приведено в разделе Настройка конфигурации монтирования.

4.3. Просмотр конфигурации

4.3.1. С помощью CLI

Для чтения параметров соединения выполните команду:

$ starvault read vk/config/root

Для чтения срока действия выполните команду:

$ starvault read vk/config/lease

Secret key в ответ не входит.

4.3.2. С помощью веб-интерфейса

  1. Перейдите на страницу механизма в разделе Секреты.

  2. Перейдите на вкладку Конфигурация.

    vk 7

Если конфигурация не задана, страница пуста. При ошибке прочитайте сообщение и повторите загрузку.

4.3.3. С помощью API

Прочитайте параметры соединения:

GET /v1/vk/config/root

Secret Key в ответ не входит. Описание конечной точки приведено в разделе VK Object Storage (API).

Прочитайте срок действия:

GET /v1/vk/config/lease

Описание конечной точки приведено в разделе Чтение конфигурации монтирования.

4.4. Изменение конфигурации

4.4.1. С помощью CLI

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

$ starvault write vk/config/root \
    access_key=<access_key> \
    secret_key=<secret_key> \
    x_pid=<project_id> \
    x_email=admin@example.com \
    hotbox_endpoint=https://hotbox.example.com \
    s3_endpoint=https://s3.example.com

4.4.2. С помощью веб-интерфейса

  1. . Перейдите на страницу механизма в разделе Секреты.

  2. Перейдите на вкладку Конфигурация. и нажмите > Конфигурировать.

    vk 8
  3. Выполните необходимые изменения и нажмите Сохранить.

    vk 9

После сохранения отображаются конфигурация и уведомление. При ошибке введенные значения остаются в форме. Чтобы выйти без сохранения, нажмите Отменить.

Порядок повторного ввода Secret key при редактировании требует уточнения в требованиях. Не предполагайте, что пустое поле автоматически сохраняет прежний ключ.

4.4.3. С помощью API

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

POST /v1/vk/config/root
Пример тела запроса
{
  "access_key": "<access_key>",
  "secret_key": "<secret_key>",
  "x_pid": "<project_id>",
  "x_email": "admin@example.com",
  "hotbox_endpoint": "https://hotbox.example.com",
  "s3_endpoint": "https://s3.example.com",
  "region": "<region>",
  "max_retries": 3
}

Успешный ответ не содержит тела. Код ответа — 204.

Описание конечной точки приведено в разделе VK Object Storage (API).

5. Управление ролями

Роль хранит шаблоны разрешений. StarVault применяет их при выдаче учетных данных. Можно задать несколько шаблонов для разных бакетов или несколько шаблонов для одного бакета. Каждый элемент buckets становится отдельным правилом политики.

5.1. Ресурсы и условия

Примеры ресурсов бакета reports-prod:

  • arn:vk:s3:::reports-prod — сам бакет;

  • arn:vk:s3:::reports-prod/* — объекты бакета.

Condition передаётся как объект условий и копируется в создаваемый Statement. Поля Principal и Sid StarVault формирует самостоятельно.

Шаблон роли не следует трактовать как самостоятельную гарантию отсутствия других прав. Итоговый доступ необходимо проверять с учётом настроек и модели авторизации VK Object Storage.

5.2. Создание роли

5.2.1. С помощью CLI

Запишите роль. В примере два шаблона: просмотр содержимого бакета и чтение объектов.

$ starvault write vk/roles/reports-access @role.json (1)
1 reports-access — имя роли в StarVault. Обязательный параметр, передается в пути.
Пример конфигурации роли

Роль содержит два разрешающих шаблона: для перечисления содержимого бакета и чтения объектов. Пример не утверждает, что все остальные операции запрещены.

{
  "buckets": [ (1)
    {
      "name": "reports-prod", (2)
      "effect": "Allow", (3)
      "actions": ["s3:ListBucket"], (4)
      "resources": ["arn:vk:s3:::reports-prod"] (5)
    },
    {
      "name": "reports-prod",
      "effect": "Allow",
      "actions": ["s3:GetObject"],
      "resources": ["arn:vk:s3:::reports-prod/*"]
    }
  ]
}
1 buckets — список шаблонов разрешений. Список можно не передавать.
2 name — имя существующего бакета. Обязательный параметр внутри шаблона.
3 effect — действие правила. При выдаче используется Allow. Обязательный параметр внутри шаблона.
4 actions — непустой список операций S3 без повторов. Обязательный параметр внутри шаблона.
5 resources — непустой список идентификаторов ресурсов (ARN) без повторов. Каждый идентификатор должен относиться к бакету из name того же шаблона. Обязательный параметр внутри шаблона.

Необязательное поле condition — объект дополнительных условий. В примере оно не задано.

Примеры используют Allow. Поддержка Deny требует уточнения: enum и UI-требования допускают это значение, но описание backend-схемы ограничивает первоначальный выпуск значением Allow.

5.2.2. С помощью веб-интерфейса

  1. Перейдите на страницу Секреты и нажмите на карточку механизма.

  2. Перейдите во вкладку Роли и нажмите Создать роль.

    vk 10
  3. Укажите имя, например reports-access. Добавьте шаблон разрешений, нажав на + Добавить шаблон разрешений и заполните его поля.

    vk 11
  4. При необходимости добавьте другие шаблоны.

  5. Нажмите Сохранить.

После сохранения откроется конфигурация роли. При ошибке введенные значения не очищаются. При отмене откроется список ролей.

vk 12
Пример конфигурации роли

Роль содержит два разрешающих шаблона: для перечисления содержимого бакета и чтения объектов. Пример не утверждает, что все остальные операции запрещены.

{
  "buckets": [
    {
      "name": "reports-prod",
      "effect": "Allow",
      "actions": ["s3:ListBucket"],
      "resources": ["arn:vk:s3:::reports-prod"]
    },
    {
      "name": "reports-prod",
      "effect": "Allow",
      "actions": ["s3:GetObject"],
      "resources": ["arn:vk:s3:::reports-prod/*"]
    }
  ]
}

5.2.3. С помощью API

Создайте роль. Тело запроса — шаблоны из примера выше:

POST /v1/vk/roles/reports-access
Пример тела запроса
{
  "buckets": [
    {
      "name": "reports-prod",
      "effect": "Allow",
      "actions": ["s3:ListBucket"],
      "resources": ["arn:vk:s3:::reports-prod"]
    },
    {
      "name": "reports-prod",
      "effect": "Allow",
      "actions": ["s3:GetObject"],
      "resources": ["arn:vk:s3:::reports-prod/*"]
    }
  ]
}

Успешный ответ не содержит тела. Код ответа — 204.

Описание конечной точки приведено в разделе VK Object Storage (API).

5.3. Просмотр и поиск ролей

5.3.1. С помощью CLI

Получите список ролей:

$ starvault list vk/roles

Прочитайте конфигурацию роли:

$ starvault read vk/roles/reports-access

5.3.2. С помощью веб-интерфейса

  1. Перейдите на страницу Секреты и нажмите на карточку механизма.

  2. Перейдите во вкладку Роли.

    vk 13

    Здесь представлен список всех существующих ролей. Используйте строку поиска для быстрого перемещения к нужной роли.

    vk 14

Если совпадений нет, отобразится сообщение Роли по запросу не найдены.

vk 15

Если список пуст, создайте роль. При ошибке загрузки прочитайте сообщение и повторите загрузку.

Чтобы открыть конфигурацию, выберите роль. На странице роли можно выдать учетные данные, изменить роль и удалить её.

5.3.3. С помощью API

Получите список ролей:

GET /v1/vk/roles?list=true
Пример поля data
{
  "keys": ["reports-access", "backup-access"]
}

Описание конечной точки приведено в разделе VK Object Storage (API).

Прочитайте конфигурацию роли:

GET /v1/vk/roles/reports-access

Конфигурация возвращается внутри data. Описание конечной точки приведено в разделе VK Object Storage (API).

5.4. Изменение роли

5.4.1. С помощью CLI

Запишите новую конфигурацию в роль с тем же именем. Команда заменяет шаблоны этой роли.

$ starvault write vk/roles/reports-access @role.json

Файл role.json содержит шаблоны из раздела Создание роли.

5.4.2. С помощью веб-интерфейса

  1. Перейдите на страницу Секреты и выберите нужный механизм.

  2. Нажмите на кнопку действия и выберите Изменить.

  3. Измените шаблоны разрешений.

    vk 16
  4. Нажмите Сохранить.

Чтобы выйти без сохранения, нажмите Отменить. При ошибке сохранения введенные значения остаются в форме.

5.4.3. С помощью API

Запрос с тем же именем заменяет шаблоны роли. Тело совпадает с примером создания роли:

POST /v1/vk/roles/reports-access
Пример тела запроса
{
  "buckets": [
    {
      "name": "reports-prod",
      "effect": "Allow",
      "actions": ["s3:ListBucket"],
      "resources": ["arn:vk:s3:::reports-prod"]
    },
    {
      "name": "reports-prod",
      "effect": "Allow",
      "actions": ["s3:GetObject"],
      "resources": ["arn:vk:s3:::reports-prod/*"]
    }
  ]
}

Успешный ответ не содержит тела. Код ответа — 204. Сохранение роли не выдает учетные данные и не меняет политику бакета.

Описание конечной точки приведено в разделе VK Object Storage (API).

Следующие выдачи используют сохраненную конфигурацию.

5.5. Удаление роли

5.5.1. С помощью CLI

Удалите роль по имени:

$ starvault delete vk/roles/reports-access

5.5.2. С помощью веб-интерфейса

  1. Откройте действия роли в списке или на странице роли.

  2. Выберите Удалить роль.

    vk 17
  3. Подтвердите удаление.

После удаления откроется список ролей.

5.5.3. С помощью API

Удалите роль по имени:

DELETE /v1/vk/roles/reports-access

Успешный ответ не содержит тела. Код ответа — 204.

Описание конечной точки приведено в разделе VK Object Storage (API).

Удаление роли не отзывает ранее выданные аренды и учетные данные. Чтобы прекратить доступ раньше срока, отзовите аренду отдельно.

6. Выдача учетных данных

6.1. С помощью CLI

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

$ starvault read vk/creds/reports-access
Пример вывода:
Key                Value
---                -----
lease_id           vk/creds/reports-access/<lease_id> (1)
lease_duration     30m (2)
lease_renewable    true (3)
access_key         <access_key> (4)
secret_key         <secret_key> (5)
1 lease_id — полный идентификатор аренды.
2 lease_duration — срок действия аренды.
3 lease_renewable — признак того, что аренду можно продлить.
4 access_key — идентификатор созданного ключа S3.
5 secret_key — секретная часть созданного ключа S3.

6.2. С помощью веб-интерфейса

  1. Откройте список ролей или страницу нужной роли.

  2. Выберите Выпустить учетные данные.

    vk 18
  3. Нажмите Генерировать.

    vk 19
  4. Скопируйте полученные данные.

    vk 20

6.3. С помощью API

Выдайте учетные данные роли:

GET /v1/vk/creds/reports-access
Пример ответа
{
  "request_id": "<request_id>",
  "lease_id": "vk/creds/reports-access/<lease_id>",
  "renewable": true,
  "lease_duration": 1800,
  "data": {
    "access_key": "<access_key>",
    "secret_key": "<secret_key>"
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null,
  "mount_type": "vk"
}

lease_duration — срок аренды в секундах. Поле session_token в ответе отсутствует.

Описание конечной точки приведено в разделе VK Object Storage (API).

Каждый запрос создает новую учетную запись и новые ключи. Повторный выпуск не показывает ранее созданный ключ. Secret key храните как конфиденциальные данные.

Продление и отзыв аренды описаны в статье Аренда, обновление и отзыв.

7. Устранение неполадок

Ситуация Действие

Не удалось загрузить роли или конфигурацию

Прочитайте сообщение об ошибке и повторите загрузку

Конфигурация сохранена, но выдача не выполняется

Проверьте ключи, идентификатор проекта, адрес электронной почты, адреса API, регион и доступность API VK Object Storage

Ошибка применения политики бакета

Проверьте, что бакет существует, что есть право менять его политику и что шаблоны заполнены верно

Не удалось сохранить роль

Проверьте обязательные поля, непустые списки операций и идентификаторов ресурсов и соответствие ресурсов бакету

Учетные данные работают после удаления роли

Отзовите аренду отдельно

Не удалось отозвать аренду

Проверьте сообщение об ошибке и доступность API VK Object Storage. Пока отзыв не завершен, доступ к хранилищу сохраняется

При ошибке сохранения формы введенные значения не очищаются. Повторная выдача не показывает ранее созданный ключ.

8. API

Путь запроса начинается с /v1/ и пути монтирования. В таблице путь монтирования — vk. Параметры передаются в теле JSON на верхнем уровне, без оболочки data.

Операция Метод Путь

Настроить соединение

POST

/v1/vk/config/root

Прочитать конфигурацию

GET

/v1/vk/config/root

Настроить срок действия

POST

/v1/vk/config/lease

Прочитать срок действия

GET

/v1/vk/config/lease

Создать или изменить роль

POST

/v1/vk/roles/{name}

Прочитать роль

GET

/v1/vk/roles/{name}

Получить список ролей

GET

/v1/vk/roles?list=true

Удалить роль

DELETE

/v1/vk/roles/{name}

Выдать учетные данные

GET

/v1/vk/creds/{name}

Тела запросов, коды ответов и примеры приведены в разделе VK Object Storage (API).