`/sys/plugins/catalog`

Конечная точка /sys/plugins/catalog используется для чтения, регистрации, обновления и удаления плагинов в каталоге StarVault. Плагины необходимо зарегистрировать перед использованием, и после регистрации бэкенды смогут использовать плагин, отправляя запросы к каталогу.

1. Список плагинов

Эта конечная точка выводит список плагинов в каталоге по типу.

Метод

Путь

GET

/sys/plugins/catalog

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

curl \
  --header "X-Vault-Token: ..." \
  http://127.0.0.1:8200/v1/sys/plugins/catalog

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

{
    "data": {
        "auth": [
            "custom-auth-plugin",
            "ldap"
        ],
        "database": [
            "cassandra-database-plugin",
            "mysql-database-plugin",
            "postgresql-database-plugin"
        ],
        "detailed": [
            {
                "builtin": true,
                "deprecation_status": "supported",
                "name": "ldap",
                "type": "auth",
                "version": "v1.1.0+builtin.starvault"
            },
            ...
            {
                "builtin": true,
                "deprecation_status": "supported",
                "name": "cassandra-database-plugin",
                "type": "database",
                "version": "v1.1.0+builtin.starvault"
            },
            ...
        ],
        "secret": [
            "transit"
        ]
    }
}

2. Список плагинов

Эта конечная точка выводит список плагинов в каталоге по типу.

Метод

Путь

LIST

/sys/plugins/catalog/auth

LIST

/sys/plugins/catalog/database

LIST

/sys/plugins/catalog/secret

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

curl \
  --header "X-Vault-Token: ..." \
  --request LIST \
  http://127.0.0.1:8200/v1/sys/plugins/catalog/auth

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

{
    "data": {
        "keys": [
            "custom-auth-plugin",
            "ldap"
        ]
    }
}

3. Зарегистрировать плагин

Эта конечная точка регистрирует новый плагин или обновляет существующий с указанным именем.

sudo требуется – эта конечная точка требует sudo возможности в дополнение к любым возможностям, специфичным для пути.

Метод

Путь

POST

/sys/plugins/catalog/:type/:name

3.1. Параметры

name (string: <required>) – задаёт имя плагина. Имя используется для поиска плагинов в каталоге. Это часть URL-адреса запроса.
type (string: <required>) – указывает тип этого плагина. Может быть «auth», «database» или «secret».
version (string: "") - указывает семантическую версию этого плагина.
sha256 (string: <required>) – это сумма SHA256 двоичного файла плагина. Перед запуском плагина его SHA-сумма будет сверена с этим значением. Если они не совпадают, плагин не запустится.
command (string: <required>) – указывает команду, используемую для запуска плагина. Указывается относительно каталога плагина, например "myplugin".
args (array: []) – задаёт аргументы, используемые для запуска плагина. Если аргументы указаны здесь, параметр command должен содержать только указанную программу. Например "--my_flag=1".
env (array: []) – задаёт переменные окружения, используемые во время работы плагина. Каждая запись имеет форму «ключ=значение», например "FOO=BAR".

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

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

{
  "sha256": "d130b9a0fbfddef9709d8ff92e5e6053ccd246b78632fc03b8548457026961e9",
  "command": "mysql-database-plugin"
}

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

curl \
  --header "X-Vault-Token: ..." \
  --request POST \
  --data @payload.json \
  http://127.0.0.1:8200/v1/sys/plugins/catalog/secret/example-plugin

4. Чтение плагина

Данная конечная точка возвращает данные конфигурации для плагина с заданным именем.

sudo требуется – эта конечная точка требует sudo возможности в дополнение к любым возможностям, специфичным для пути.

Метод

Путь

GET

/sys/plugins/catalog/:type/:name?version=:version

4.1. Параметры

name (string: <required>) – указывает имя плагина. Это часть URL-адреса запроса;
type (string: <required>) – указывает тип этого плагина. Может быть «auth», «database» или «secret»;
version (string: "") - семантическая версия плагина. Требуется, если плагин зарегистрирован с версией.

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

curl \
  --header "X-Vault-Token: ..." \
  --request GET \
  http://127.0.0.1:8200/v1/sys/plugins/catalog/secret/example-plugin

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

{
  "data": {
    "args": [],
    "builtin": false,
    "command": "/tmp/starvault-plugins/mysql-database-plugin",
    "name": "example-plugin",
    "sha256": "0TC5oPv93vlwnY/5Ll5gU8zSRreGMvwDuFSEVwJpYek=",
    "version": "v1.0.0"
  }
}

5. Удаление плагина из каталога

Эта конечная точка удаляет плагин с указанным именем.

Метод

Путь

DELETE

/sys/plugins/catalog/:type/:name?version=:version

5.1. Параметры

name (string: <required>) – указывает имя плагина. Это часть URL-адреса запроса;
type (string: <required>) – указывает тип этого плагина. Может быть «auth», «database» или «secret»;
version (string: "") - указывает семантическую версию плагина.

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

curl \
  --header "X-Vault-Token: ..." \
  --request DELETE \
  http://127.0.0.1:8200/v1/sys/plugins/catalog/secret/example-plugin