`/sys/leases`

Конечные точки /sys/leases используются для просмотра и управления арендами в StarVault.

1. Прочитать договор аренды

Эта конечная точка извлекает метаданные аренды.

Метод

Путь

POST

/sys/leases/lookup

1.1. Параметры

lease_id (string: <required>) – Указывает идентификатор аренды для поиска.

1.2. Пример тела запроса

{
  "lease_id": "auth/userpass/login/user/h5a2..."
}

1.3. Пример запроса

curl \
  --header "X-Vault-Token: ..." \
  --request POST \
  --data @payload.json \
  http://127.0.0.1:8200/v1/sys/leases/lookup

1.4. Пример ответа

{
  "data": {
    "expire_time": "2024-03-07T20:34:02.005655614+01:00",
    "id": "auth/userpass/login/user/h5a2d7506918f459d022267a3351666b35bd8b5d6d39b0bcfe14927c0e4464225",
    "issue_time": "2024-02-04T20:34:02.005663311+01:00",
    "last_renewal": null,
    "renewable": true,
    "ttl": 2764397
  }
}

2. Список договоров аренды

Эта конечная точка возвращает список идентификаторов аренды.

Для этой конечной точки требуется возможность «sudo».

Метод

Путь

LIST

/sys/leases/lookup/:prefix

2.1. Пример запроса

curl \
  --header "X-Vault-Token: ..." \
  --request LIST \
  http://127.0.0.1:8200/v1/sys/leases/lookup/auth/userpass/login/user/

2.2. Пример ответа

{
  "data": {
    "keys": [
      "h5a2d7506918f459d022267a3351666b35bd8b5d6d39b0bcfe14927c0e4464225"
    ]
  }
}

3. Отозвать аренду

Эта конечная точка немедленно отзывает аренду.

Метод

Путь

POST

/sys/leases/revoke

3.1. Параметры

lease_id (string: <required>) – Указывает идентификатор аренды, которую необходимо отозвать. Этот параметр можно указать в JSON-запросе, как показано ниже, или предоставить как параметр пути к конечной точке, например, /sys/leases/revoke/:lease_id. Если указаны оба параметра, приоритет имеет параметр leaseID в JSON-запросе.
sync (bool: false) - Вместо стандартного поведения постановки отзыва аренды в очередь, sync=true немедленно отменит аренду и вернет управление только после ее завершения.

3.2. Пример тела запроса

{
  "lease_id": "postgresql/creds/readonly/abcd-1234..."
}

3.3. Пример запроса

curl \
  --header "X-Vault-Token: ..." \
  --request POST \
  --data @payload.json \
  http://127.0.0.1:8200/v1/sys/leases/revoke

4. Принудительный отзыв аренды

Эта конечная точка немедленно отзывает все секреты или токены, сгенерированные с заданным префиксом. В отличие от /sys/leases/revoke-prefix, этот путь игнорирует ошибки бэкенда, возникающие при отзыве. Это потенциально очень опасно и должно использоваться только в особых экстренных ситуациях, когда ошибки бэкенда или подключенной бэкенд-службы препятствуют нормальному отзыву аренды.

Игнорируя эти ошибки, Orion soft снимает с себя ответственность за обеспечение надлежащего отзыва и/или удаления выданных учётных данных или секретов. Доступ к этой конечной точке должен строго контролироваться.

Для этой конечной точки требуется возможность «sudo».

Метод

Путь

POST

/sys/leases/revoke-force/:prefix

4.1. Параметры

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

4.2. Пример запроса

curl \
  --header "X-Vault-Token: ..." \
  --request POST \
  http://127.0.0.1:8200/v1/sys/leases/revoke-force/auth/userpass

5. Отозвать через префикс

Эта конечная точка немедленно отзывает все секреты (через префикс идентификатора аренды) или токены (через свойство пути токенов), сгенерированные с заданным префиксом. Для этого требуется определённая sudo возможность, и доступ к ней должен строго контролироваться, поскольку она может использоваться для отзыва очень большого количества секретов/токенов одновременно.

Для этой конечной точки требуется возможность «sudo».

Метод

Путь

POST

/sys/leases/revoke-prefix/:prefix

5.1. Параметры

prefix (string: <required>) – Указывает префикс для отзыва. Он указывается как часть URL-адреса.
sync (bool: false) - Вместо стандартного поведения постановки в очередь отзывов аренды, sync=true немедленно отменит эти аренды и вернет управление только после их завершения.

5.2. Пример запроса

curl \
  --header "X-Vault-Token: ..." \
  --request POST \
  http://127.0.0.1:8200/v1/sys/leases/revoke-prefix/auth/userpass

6. Очищение договоров аренды

Эта конечная точка очищает неактивные записи хранилища для договоров аренды: для каждой записи аренды в хранилище StarVault проверит, есть ли в хранилище соответствующий действительный неистекший токен, и если нет, то договор аренды будет отозван.

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

Метод

Путь

POST

/sys/leases/tidy

6.1. Пример запроса

curl \
  --header "X-Vault-Token: ..." \
  --request POST \
  http://127.0.0.1:8200/v1/sys/leases/tidy

7. Подсчёт договоров аренды

Эта конечная точка возвращает общее количество type аренд, а также количество аренд на точку монтирования. Обратите внимание, что в настоящее время поддерживается только тип безотзывный.

Это может помочь определить, приводят ли определенные конечные точки к непропорционально высокой доле безотзывной аренды.

Метод

Путь

GET

/sys/leases/count

7.1. Параметры

type (string: <required>) - Указывает тип аренды.
include_child_namespaces (bool: false) — указывает, следует ли включать в результат аренду в дочерних пространствах имен.

7.2. Пример запроса

curl \
  --header "X-Vault-Token: ..." \
  --request GET \
  http://127.0.0.1:8200/v1/sys/leases/count?type=irrevocable

8. Список договоров аренды

Эта конечная точка возвращает общее количество договоров type аренды, а также список договоров аренды для каждой точки монтирования. Обратите внимание, что в настоящее время поддерживается только тип безотзывный.

Метод

Путь

GET

/sys/leases

8.1. Параметры

type (string: <required>) - Указывает тип аренды.
include_child_namespaces (bool: false) — указывает, следует ли включать в результат аренду в дочерних пространствах имен.
limit (string: "") — определяет максимальное количество договоров аренды, возвращаемых в запросе. Чтобы вернуть все результаты, установите значение none. Если значение не задано, API вернет не более 10 000 договоров аренды. Если значение не задано как none и количество договоров аренды превышает limit, ответ будет содержать предупреждение.

8.2. Пример запроса

curl \
    --header "X-Vault-Token: ..." \
    --request GET \
    "http://127.0.0.1:8200/v1/sys/leases?type=irrevocable"