Движки секретов. KV - версия 1 (API)

В данном разделе представлена документация API для движка секретов KV в StarVault, версия 1.

Это документация API для движка секретов KV в StarVault. Общая информация о работе с версией 1 движка KV доступна в документации StarVault KV.

Данная документация предполагает, что движок секретов kv включен по пути /secret в StarVault. Поскольку движки секретов можно включать по любому пути, учитывайте это при вызовах API.

1. Чтение секрета

Эта конечная точка возвращает секрет по указанному пути.

Метод Путь

Метод	Путь
`GET`	`/secret/:path`

GET

/secret/:path

1.1. Параметры

path (string: <required>) - путь к читаемому секрету. Указывается в URL.

Пример запроса:

$ curl \
    --header "X-Vault-Token: ..." \
    https://127.0.0.1:8200/v1/secret/my-secret

Пример ответа:

{
  "auth": null,
  "data": {
    "foo": "bar",
    "ttl": "1h"
  },
  "lease_duration": 3600,
  "lease_id": "",
  "renewable": false
}

Поле lease_duration, которое заполняется при наличии поля "ttl" в данных, носит рекомендательный характер. Аренда не создается. Это способ указать клиенту, как часто следует перечитывать значение. Подробнее в документации KV.

2. Список секретов

Возвращает список ключей по указанному пути. Папки имеют суффикс /. Путь должен указывать на папку - вызов для файла не вернет значений. Фильтрация по политикам доступа не применяется к именам ключей - не используйте чувствительную информацию в именах. Значения через этот API недоступны.

Поддерживается рекурсивный вывод (сканирование).

Метод Путь

Метод	Путь
`LIST`	`/secret/:path`
`SCAN`	`/secret/:path`

LIST

/secret/:path

SCAN

/secret/:path

2.1. Параметры

path (string: <required>) - путь для вывода списка секретов. Указывается в URL.

Пример запроса:

$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    https://127.0.0.1:8200/v1/secret/my-secret

Пример вывода для пути secret/, когда существуют секреты secret/foo и secret/foo/bar:

Пример ответа:

{
  "auth": null,
  "data": {
    "keys": ["foo", "foo/"]
  },
  "lease_duration": 2764800,
  "lease_id": "",
  "renewable": false
}

3. Создание/Обновление секрета

Сохраняет секрет по указанному пути. Для создания нового значения требуется политика с правом create, для обновления существующего - update.

Метод Путь

Метод	Путь
`POST`	`/secret/:path`

POST

/secret/:path

3.1. Параметры

path (string: <required>) - путь для создания/обновления секрета. Указывается в URL.
:key (string: "") - ключ в передаваемых данных со связанным значением для сохранения. Можно указать несколько пар ключ-значение, все они будут возвращены при чтении. Ключ ttl активирует особое поведение (см. документацию KV).

Пример данных:

{
  "foo": "bar",
  "zip": "zap"
}

Пример запроса:

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    https://127.0.0.1:8200/v1/secret/my-secret

4. Удаление секрета

Удаляет секрет по указанному пути.

Метод Путь

Метод	Путь
`DELETE`	`/secret/:path`

DELETE

/secret/:path

4.1. Параметры

path (string: <required>) - путь к удаляемому секрету. Указывается в URL.

Пример запроса:

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    https://127.0.0.1:8200/v1/secret/my-secret