Механизм секретов 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. С помощью веб-интерфейса
-
Откройте раздел Секреты. Нажмите + Добавить.
-
В подразделе Infra выберите VK Object Storage и нажмите Далее.
-
Укажите путь монтирования, например
vk. -
При необходимости измените стандартные параметры подключения.
-
Подтвердите подключение, нажав Включить механизм.
После подключения откроется список ролей. У нового механизма список пуст.
|
Подключение механизма и настройка соединения — разные операции. Перед выдачей учетных данных настройте соединение с 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. С помощью веб-интерфейса
-
Откройте подключенный механизм в разделе Секреты.
-
Перейдите к конфигурации и нажмите Настроить VK Object Storage >
-
Заполните параметры соединения.
-
Нажмите Сохранить.
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. С помощью веб-интерфейса
-
Перейдите на страницу механизма в разделе Секреты.
-
Перейдите на вкладку Конфигурация и нажмите > Конфигурировать.
-
Нажмите на переключатель TTL и укажите значение.
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. С помощью веб-интерфейса
-
Перейдите на страницу механизма в разделе Секреты.
-
Перейдите на вкладку Конфигурация.
Если конфигурация не задана, страница пуста. При ошибке прочитайте сообщение и повторите загрузку.
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. С помощью веб-интерфейса
-
. Перейдите на страницу механизма в разделе Секреты.
-
Перейдите на вкладку Конфигурация. и нажмите > Конфигурировать.
-
Выполните необходимые изменения и нажмите Сохранить.
После сохранения отображаются конфигурация и уведомление. При ошибке введенные значения остаются в форме. Чтобы выйти без сохранения, нажмите Отменить.
|
Порядок повторного ввода |
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 — объект дополнительных условий. В примере оно не задано.
|
Примеры используют |
5.2.2. С помощью веб-интерфейса
-
Перейдите на страницу Секреты и нажмите на карточку механизма.
-
Перейдите во вкладку Роли и нажмите Создать роль.
-
Укажите имя, например
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/*"]
}
]
}
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. С помощью веб-интерфейса
-
Перейдите на страницу Секреты и нажмите на карточку механизма.
-
Перейдите во вкладку Роли.
Здесь представлен список всех существующих ролей. Используйте строку поиска для быстрого перемещения к нужной роли.
Если совпадений нет, отобразится сообщение Роли по запросу не найдены.
Если список пуст, создайте роль. При ошибке загрузки прочитайте сообщение и повторите загрузку.
Чтобы открыть конфигурацию, выберите роль. На странице роли можно выдать учетные данные, изменить роль и удалить её.
5.3.3. С помощью API
Получите список ролей:
GET /v1/vk/roles?list=true
{
"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. С помощью веб-интерфейса
-
Перейдите на страницу Секреты и выберите нужный механизм.
-
Нажмите на кнопку действия и выберите Изменить.
-
Измените шаблоны разрешений.
-
Нажмите Сохранить.
Чтобы выйти без сохранения, нажмите Отменить. При ошибке сохранения введенные значения остаются в форме.
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.2. С помощью веб-интерфейса
-
Откройте действия роли в списке или на странице роли.
-
Выберите Удалить роль.
-
Подтвердите удаление.
После удаления откроется список ролей.
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. С помощью веб-интерфейса
-
Откройте список ролей или страницу нужной роли.
-
Выберите Выпустить учетные данные.
-
Нажмите Генерировать.
-
Скопируйте полученные данные.
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).
|
Каждый запрос создает новую учетную запись и новые ключи. Повторный выпуск не показывает ранее созданный ключ. |
Продление и отзыв аренды описаны в статье Аренда, обновление и отзыв.
7. Устранение неполадок
| Ситуация | Действие |
|---|---|
Не удалось загрузить роли или конфигурацию |
Прочитайте сообщение об ошибке и повторите загрузку |
Конфигурация сохранена, но выдача не выполняется |
Проверьте ключи, идентификатор проекта, адрес электронной почты, адреса API, регион и доступность API VK Object Storage |
Ошибка применения политики бакета |
Проверьте, что бакет существует, что есть право менять его политику и что шаблоны заполнены верно |
Не удалось сохранить роль |
Проверьте обязательные поля, непустые списки операций и идентификаторов ресурсов и соответствие ресурсов бакету |
Учетные данные работают после удаления роли |
Отзовите аренду отдельно |
Не удалось отозвать аренду |
Проверьте сообщение об ошибке и доступность API VK Object Storage. Пока отзыв не завершен, доступ к хранилищу сохраняется |
При ошибке сохранения формы введенные значения не очищаются. Повторная выдача не показывает ранее созданный ключ.
8. API
Путь запроса начинается с /v1/ и пути монтирования. В таблице путь монтирования — vk. Параметры передаются в теле JSON на верхнем уровне, без оболочки data.
| Операция | Метод | Путь |
|---|---|---|
Настроить соединение |
|
|
Прочитать конфигурацию |
|
|
Настроить срок действия |
|
|
Прочитать срок действия |
|
|
Создать или изменить роль |
|
|
Прочитать роль |
|
|
Получить список ролей |
|
|
Удалить роль |
|
|
Выдать учетные данные |
|
|
Тела запросов, коды ответов и примеры приведены в разделе VK Object Storage (API).