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

Движки секретов. VK Object Storage (API)

В разделе описано API механизма секретов VK Object Storage. Настройка в веб-интерфейсе и работа с арендой приведены в разделе Механизм секретов VK Object Storage.

Пути ниже даны для монтирования vk. Если механизм подключен по другому пути, замените префикс. Параметры передаются в теле JSON на верхнем уровне, без оболочки data.

Ответы чтения используют обычную оболочку StarVault: данные механизма лежат в data, сведения об аренде — на верхнем уровне. Ответ с кодом 204 не содержит тела.

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

Конечная точка записывает параметры доступа StarVault к VK Object Storage. Если конфигурация уже есть, новый запрос её заменяет. Запрос не проверяет ключи и доступность хранилища.

Метод Путь

POST

/vk/config/root

1.1. Параметры

  • access_key (string: <обязательный>) — идентификатор статического ключа S3.

  • secret_key (string: <обязательный>) — секретная часть ключа S3.

  • x_pid (string: <обязательный>) — идентификатор проекта VK Object Storage.

  • x_email (string: <обязательный>) — адрес электронной почты для обращения к API Hotbox.

  • hotbox_endpoint (string: <обязательный>) — адрес API Hotbox.

  • s3_endpoint (string: <обязательный>) — адрес API S3.

  • region (string: "" <необязательный>) — регион для запросов S3.

  • max_retries (int: <необязательный>) — максимальное число повторных попыток при восстановимых ошибках.

Пример тела запроса
{
  "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
}
Пример запроса
$ curl \
    --header "X-Vault-Token: <token>" \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/vk/config/root

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

2. Чтение конфигурации

Конечная точка возвращает сохраненные параметры соединения. Secret Key в ответ не входит.

Метод Путь

GET

/vk/config/root

Пример запроса
$ curl \
    --header "X-Vault-Token: <token>" \
    http://127.0.0.1:8200/v1/vk/config/root
Пример поля data
{
  "access_key": "<access_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
}

Secret Key в data не возвращается.

Срок аренды точки монтирования настраивается общей конечной точкой Настройка конфигурации монтирования. Текущие значения читаются конечной точкой Чтение конфигурации монтирования.

3. Создание и изменение роли

Конечная точка создает роль или обновляет роль с тем же именем. Через роль задаются шаблоны разрешений для бакетов. Каждый элемент buckets становится отдельным правилом политики.

Метод Путь

POST

/vk/roles/:name

3.1. Параметры

  • name (string: <обязательный>) — имя роли. Передается в пути.

  • buckets (array: []) — список шаблонов разрешений. Список можно не передавать.

  • buckets[].name (string: <обязательный>) — имя существующего бакета.

  • buckets[].effect (string: <обязательный>) — действие правила. Для выдачи используется Allow.

  • buckets[].actions (array: <обязательный>) — непустой список операций S3 без повторов.

  • buckets[].resources (array: <обязательный>) — непустой список идентификаторов ARN без повторов. Каждый идентификатор должен относиться к бакету из name того же шаблона.

  • buckets[].condition (object: null) — дополнительные условия. Объект копируется в создаваемое правило.

Поля Principal и Sid StarVault заполняет самостоятельно.

Пример тела запроса
{
  "buckets": [
    {
      "name": "reports-prod",
      "effect": "Allow",
      "actions": ["s3:ListBucket"],
      "resources": ["arn:aws:s3:::reports-prod"]
    },
    {
      "name": "reports-prod",
      "effect": "Allow",
      "actions": ["s3:GetObject"],
      "resources": ["arn:aws:s3:::reports-prod/*"]
    }
  ]
}
Пример запроса
$ curl \
    --header "X-Vault-Token: <token>" \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/vk/roles/reports-access

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

4. Чтение роли

Конечная точка возвращает конфигурацию роли внутри data. Имя роли задается в пути. Если роли нет, ответ — 404.

Метод Путь

GET

/vk/roles/:name

4.1. Параметры

  • name (string: <обязательный>) — имя роли. Передается в пути.

Пример запроса
$ curl \
    --header "X-Vault-Token: <token>" \
    http://127.0.0.1:8200/v1/vk/roles/reports-access
Пример поля data
{
  "buckets": [
    {
      "name": "reports-prod",
      "effect": "Allow",
      "actions": ["s3:ListBucket"],
      "resources": ["arn:aws:s3:::reports-prod"]
    },
    {
      "name": "reports-prod",
      "effect": "Allow",
      "actions": ["s3:GetObject"],
      "resources": ["arn:aws:s3:::reports-prod/*"]
    }
  ]
}

5. Список ролей

Конечная точка возвращает имена ролей механизма.

Метод Путь

GET

/vk/roles?list=true

Пример запроса
$ curl \
    --header "X-Vault-Token: <token>" \
    http://127.0.0.1:8200/v1/vk/roles?list=true
Пример поля data
{
  "keys": ["reports-access", "backup-access"]
}

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

Конечная точка удаляет роль. Ранее выданные аренды при этом не отзываются. Если роли нет, ответ — 404.

Метод Путь

DELETE

/vk/roles/:name

6.1. Параметры

  • name (string: <обязательный>) — имя удаляемой роли. Передается в пути.

Пример запроса
$ curl \
    --header "X-Vault-Token: <token>" \
    --request DELETE \
    http://127.0.0.1:8200/v1/vk/roles/reports-access

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

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

Конечная точка создает учетную запись VK Object Storage по шаблонам роли и возвращает ключи. Роль нужно создать заранее. Повторный запрос выполняет новую выдачу и не возвращает прежний ключ.

Метод Путь

GET

/vk/creds/:name

7.1. Параметры

  • name (string: <обязательный>) — имя роли. Передается в пути.

Пример запроса
$ curl \
    --header "X-Vault-Token: <token>" \
    http://127.0.0.1:8200/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 в ответе отсутствует.