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

Движок секретов базы данных (API)

В данном разделе представлена документация API для движка секретов базы данных StarVault. Для общей информации о использовании и работе движка секретов базы данных, пожалуйста, смотрите документацию по движку секретов базы данных StarVault.

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

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

Эта конечная точка настраивает строку соединения, используемую для общения с необходимой базой данных. В дополнение к параметрам, перечисленным здесь, каждый плагин Database имеет дополнительные параметры, специфичные для плагина базы данных, для этой конечной точки. Пожалуйста, изучите HTTP API для плагина, который вы хотите настроить, чтобы увидеть полный список дополнительных параметров.

Эта конечная точка различает возможности ACL create и update.
Метод Путь

POST

/database/config/:name

1.1. Параметры

  • name (string: <обязательный>) - указывает имя для этого соединения с базой данных. Это указано как часть URL.

  • plugin_name (string: <обязательный>) - указывает имя плагина, который нужно использовать для этого соединения.

  • plugin_version (string: "") - указывает семантическую версию плагина, который нужно использовать для этого соединения.

  • verify_connection (bool: true) - указывает, проверяется ли соединение во время первоначальной настройки. По умолчанию true.

  • allowed_roles (list: []) - список ролей, которым разрешено использовать это соединение. По умолчанию пусто (без ролей); если содержит *, любая роль может использовать это соединение.

  • root_rotation_statements (list: []) - указывает SQL заявления для базы данных, которые будут выполнены для ротации учетных данных пользователя root. Смотрите API старницу плагина для получения дополнительной информации о поддержке и форматировании для этого параметра.

  • password_policy (string: "") - имя политики паролей, которая будет использоваться при создании паролей для этой базы данных. Если не указано, будет использоваться политика по умолчанию, определенная как: 20 символов с минимум 1 заглавной буквой, 1 строчной, 1 цифрой и 1 тире.

Мы настоятельно рекомендуем вам использовать специализированного пользователя StarVault, а не администратора в вашей базе данных при настройке плагина. Этот пользователь будет использоваться для создания/обновления/удаления пользователей внутри базы данных, поэтому он должен иметь соответствующие права доступа для этого. Если плагин поддерживает ротацию учетных данных root, мы настоятельно рекомендуем выполнить это действие после настройки плагина. Это изменит пароль пользователя, сконфигурированного на этом этапе. Новый пароль не будет виден пользователям.

1.2. Общие поля

Есть несколько общих полей, которые вы увидите во многих плагинах баз данных. Пожалуйста, обращайтесь к документации по отдельным плагинам для получения подробной информации о том, поддерживаются ли эти поля и любые дополнительные детали о них.

  • connection_url (string) - указывает строку соединения, используемую для подключения к базе данных. Некоторые плагины используют url вместо connection_url. Это позволяет простое шаблонирование имени пользователя и пароля пользователя root. Обычно это делается путем включения поля {{username}}, {{name}} и/или {{password}} в строку. Эти поля обычно заменяются значениями в полях username и password.

  • username (string) - указывает имя пользователя, который будет использоваться в качестве "root" пользователя при подключении к базе данных. Этот "root" пользователь используется для создания обновления/удаления пользователей, управляемых этими плагинами, поэтому вам нужно убедиться, что у этого пользователя есть права для выполнения действий с пользователями, соответствующими базе данных. Обычно это используется в поле connection_url через директиву шаблона {{username}} или {{name}}.

  • password (string) - указывает пароль, который необходимо использовать при подключении с помощью username. Это значение не будет возвращено StarVault при выполнении чтения из конфигурации. Обычно это используется в поле connection_url через директиву шаблона {{password}}.

  • disable_escaping (boolean: false) - определяет, будут ли специальные символы в полях имени пользователя и пароля экранированы. Полезно для альтернативных форматов строк соединения типа ADO. Дополнительную информацию о этом параметре можно найти в документации движка секретов баз данных. По умолчанию false.

Пример тела запроса:
{
  "plugin_name": "mysql-database-plugin",
  "allowed_roles": "readonly",
  "connection_url": "{{username}}:{{password}}@tcp(127.0.0.1:3306)/",
  "username": "starvaultuser",
  "password": "secretpassword"
}
Пример запроса cURL:
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/database/config/mysql
Пример запроса CLI:
$ starvault write database/config/mysql \
    plugin_name="mysql-database-plugin" \
    allowed_roles="readonly" \
    connection_url="{{username}}:{{password}}@tcp(127.0.0.1:3306)/" \
    username="starvaultuser" \
    password="secretpassword"
Пример запроса CLI с строкой соединения в стиле ADO:
$ starvault write database/config/mysql \
    plugin_name="mysql-database-plugin" \
    connection_url='server=localhost;port=3306;user id={{username}};password={{password}};database=mysql;' \
    username="starvaultuser" \
    password='your#StrongPassword%' \
    disable_escaping="true"

2. Чтение соединения

Эта конечная точка возвращает настройки конфигурации для соединения.

Метод Путь

GET

/database/config/:name

2.1. Параметры

  • name (string: <обязательный>) - указывает имя соединения для чтения. Это указано как часть URL.

Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request GET \
    http://127.0.0.1:8200/v1/database/config/mysql
Пример ответа:
{
  "data": {
    "allowed_roles": ["readonly"],
    "connection_details": {
      "connection_url": "{{username}}:{{password}}@tcp(127.0.0.1:3306)/",
      "username": "starvaultuser"
    },
    "password_policy": "",
    "plugin_name": "mysql-database-plugin",
    "plugin_version": "",
    "root_credentials_rotate_statements": []
  }
}

3. Список соединений

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

Метод Путь

LIST

/database/config
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/database/config
Пример ответа:
{
  "data": {
    "keys": ["db-one", "db-two"]
  }
}

4. Удаление соединения

Эта конечная точка удаляет соединение.

Метод Путь

DELETE

/database/config/:name

4.1. Параметры

  • name (string: <обязательный>) - указывает имя соединения для удаления. Это указано как часть URL.

Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/database/config/mysql

5. Сброс соединения

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

Метод Путь

POST

/database/reset/:name

5.1. Параметры

  • name (string: <обязательный>) - указывает имя соединения для сброса. Это указано как часть URL.

Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    http://127.0.0.1:8200/v1/database/reset/mysql

6. Ротация учетных данных root

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

Метод Путь

POST

/database/rotate-root/:name

Пароль пользователя root не будет доступен после ротации, поэтому настоятельно рекомендуется создать пользователя для использования StarVault, а не использовать фактического пользователя root.

6.1. Параметры

  • name (string: <обязательный>) - указывает имя соединения для ротации. Это указано как часть URL.

Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    http://127.0.0.1:8200/v1/database/rotate-root/mysql

7. Создание роли

Эта конечная точка создает или обновляет определение роли.

Эта конечная точка различает возможности ACL create и update.
Метод Путь

POST

/database/roles/:name

7.1. Параметры

  • name (string: <обязательный>) - указывает имя роли для создания. Это указано как часть URL.

  • db_name (string: <обязательный>) - имя соединения с базой данных, которое будет использоваться для этой роли.

  • default_ttl (string/int: 0) - указывает TTL для аренды, связанной с этой ролью. Принимает строки с суффиксом времени (1h) или целое количество секунд. По умолчанию соответствует системному/движковому значению времени TTL.

  • max_ttl (string/int: 0) - указывает максимальный TTL для аренды, связанной с этой ролью. Принимает строки с суффиксом времени (1h) или целое количество секунд. По умолчанию соответствует значению TTL по умолчанию для sys/mounts; это значение может быть меньше максимального TTL монтирования (или, если он не установлен, максимального системного TTL), но не может быть больше. Также см. Общий случай TTL.

  • creation_statements (list: <обязательный>) - указывает SQL заявления базы данных, выполняемые для создания и настройки пользователя. Смотрите страницу API плагина для получения дополнительной информации о поддержке и форматировании этого параметра.

  • revocation_statements (list: []) - указывает SQL заявления базы данных для выполнения удаления пользователя. Смотрите страницу API плагина для получения дополнительной информации о поддержке и форматировании этого параметра.

  • rollback_statements (list: []) - указывает SQL заявления базы данных для выполнения отката операции создания в случае ошибки. Не каждый тип плагина будет поддерживать эту функциональность. Смотрите странице API плагина для получения дополнительной информации о поддержке и форматировании этого параметра.

  • renew_statements (list: []) - указывает SQL заявления базы данных для выполнения обновления для пользователя. Не каждый тип плагина будет поддерживать эту функциональность. Смотрите страницу API плагина для получения дополнительной информации о поддержке и форматировании этого параметра.

Пример тела запроса:
{
  "db_name": "mysql",
  "creation_statements": [
    "CREATE USER '{{name}}'@'%' IDENTIFIED BY '{{password}}'",
    "GRANT SELECT ON *.* TO '{{name}}'@'%'"
  ],
  "default_ttl": "1h",
  "max_ttl": "24h"
}
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/database/roles/my-role

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

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

Метод Путь

GET

/database/roles/:name

8.1. Параметры

  • name (string: <обязательный>) - указывает имя роли для чтения. Это указано как часть URL.

Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/database/roles/my-role
Пример ответа:
{
  "data": {
    "creation_statements": [
      "CREATE ROLE \"{{name}}\" WITH LOGIN PASSWORD '{{password}}' VALID UNTIL '{{expiration}}';",
      "GRANT SELECT ON ALL TABLES IN SCHEMA public TO \"{{name}}\";"
    ],
    "credential_type": "password",
    "db_name": "mysql",
    "default_ttl": 3600,
    "max_ttl": 86400,
    "renew_statements": [],
    "revocation_statements": [],
    "rollback_statements": []
  }
}

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

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

Метод Путь

LIST

/database/roles

9.1. Параметры

  • after (string: "") - необязательная запись, чтобы начать перечисление после для постраничного разбивания; не обязательно должно существовать.

  • limit (int: 0) - необязательное количество записей для возврата; по умолчанию возвращаются все записи.

Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/database/roles
Пример ответа:
{
  "auth": null,
  "data": {
    "keys": ["dev-static", "prod-static"]
  }
}

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

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

Метод Путь

DELETE

/database/roles/:name

10.1. Параметры

  • name (string: <обязательный>) - указывает имя роли для удаления. Это указано как часть URL.

Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/database/roles/my-role

11. Генерация учетных данных

Эта конечная точка генерирует новый набор динамических учетных данных на основе именованной роли.

Метод Путь

GET

/database/creds/:name

11.1. Параметры

  • name (string: <обязательный>) - указывает имя роли для создания учетных данных. Это указано как часть URL.

Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/database/creds/my-role
Пример ответа:
{
  "data": {
    "username": "root-1430158508-126",
    "password": "132ae3ef-5a64-7499-351e-bfe59f3a2a21"
  }
}

12. Создание статической роли

Эта конечная точка создает или обновляет определение статической роли. Статические роли являются один-к-одному соответствием роли StarVault к пользователю в базе данных, которые автоматически роторизуются на основе установленного rotation_period.

Эта конечная точка различает возможности ACL create и update.

StarVault будет ротировать пароль при создании статической роли. StarVault должен это сделать, чтобы знать пароль.
Метод Путь

POST

/database/static-roles/:name

12.1. Параметры

  • name (string: <обязательный>) - указывает имя роли для создания. Это указано как часть URL.

  • username (string: <обязательный>) - указывает имя пользователя базы данных, которое соответствует этой роли StarVault.

  • rotation_period (string/int: <обязательный>) - указывает, сколько времени StarVault должно ждать перед ротацией пароля. Минимум - 5 секунд.

  • db_name (string: <обязательный>) - имя соединения базой данных, которое будет использоваться для этой роли.

  • rotation_statements (list: []) - указывает SQL заявления базы данных, которые будут выполняться для ротации пароля для установленного пользователя базы данных. Не каждый тип плагина будет поддерживать эту функциональность. Смотрите страницу API плагина для получения дополнительной информации о поддержке и форматировании этого параметра.

Пример тела запроса:
{
  "db_name": "mysql",
  "username": "static-database-user",
  "rotation_statements": [
    "ALTER USER '{{name}}' IDENTIFIED BY '{{password}}';"
  ],
  "rotation_period": "1h"
}
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/database/static-roles/my-static-role

13. Чтение статической роли

Эта конечная точка запрашивает определение статической роли.

Метод Путь

GET

/database/static-roles/:name

13.1. Параметры

  • name (string: <обязательный>) - указывает имя статической роли для чтения. Это указано как часть URL.

Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/database/static-roles/my-static-role
Пример ответа:
{
  "data": {
    "credential_type": "password",
    "db_name": "mysql",
    "username": "static-user",
    "rotation_statements": [
      "ALTER USER \"{{name}}\" IDENTIFIED BY '{{password}}';"
    ],
    "rotation_period": "1h"
  }
}

14. Список статических ролей

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

Метод Путь

LIST

/database/static-roles

14.1. Параметры

  • after (string: "") - необязательная запись для начала перечисления после для постраничного разбивания; не обязательно должно существовать.

  • limit (int: 0) - необязательное количество записей для возврата; по умолчанию возвращаются все записи.

Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/database/static-roles
Пример ответа:
{
  "auth": null,
  "data": {
    "keys": ["dev-static", "prod-static"]
  }
}

15. Удаление статической роли

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

Метод Путь

DELETE

/database/static-roles/:name

15.1. Параметры

  • name (string: <обязательный>) - указывает имя статической роли для удаления. Это указано как часть URL.

Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/database/static-roles/my-role

16. Получение статических учетных данных

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

Метод Путь

GET

/database/static-creds/:name

16.1. Параметры

  • name (string: <обязательный>) - Указывает имя статической роли, для которой нужно получить учетные данные. Это указано как часть URL.

Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/database/static-creds/my-static-role
Пример ответа:
{
  "data": {
    "username": "static-user",
    "password": "132ae3ef-5a64-7499-351e-bfe59f3a2a21",
    "last_openbao_rotation": "2025-08-05T15:26:42.525302-05:00",
    "rotation_period": 30,
    "ttl": 28
  }
}

17. Ротация учетных данных статической роли

Эта конечная точка используется для ротирования статических учетных данных, хранящихся для данного имени роли. Хотя статические роли ротируются автоматически StarVault в соответствии с установленными периодами ротации, пользователи могут использовать эту конечную точку, чтобы вручную инициировать ротацию, чтобы изменить сохраненный пароль и сбросить TTL пароля статической роли.

Метод Путь

POST

/database/rotate-role/:name

17.1. Параметры

  • name (string: <обязательный>) - указывает имя статической роли, для которой необходимо вызвать ротацию пароля. Имя указывается как часть URL.

Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    http://127.0.0.1:8200/v1/database/rotate-role/my-static-role

18. Содержание раздела