В Standalone-установке внешние плагины администратор доставляет на сервер самостоятельно. После этого плагин необходимо зарегистрировать в каталоге плагинов и только затем включить как secret, auth или database engine.

Как устроены внешние плагины

Внешние плагины являются отдельными приложениями, которые Stronghold запускает и с которыми взаимодействует по RPC.

Это означает:

  • процесс плагина не разделяет память с основным процессом Stronghold;
  • плагин получает только явно переданные интерфейсы и аргументы;
  • сбой плагина не должен приводить к падению всего Stronghold.

Предварительные требования

Для работы внешних плагинов в Standalone-конфигурации необходимо:

  • указать api_addr в конфигурации Stronghold;
  • настроить plugin_directory;
  • поместить бинарные файлы плагинов в этот каталог;
  • зарегистрировать плагин в каталоге плагинов.

Настройка plugin_directory

Stronghold использует параметр plugin_directory в конфигурационном файле, чтобы определить каталог, из которого разрешено запускать внешние плагины.

Пример:

api_addr = "https://stronghold.example.com:8200"

plugin_directory = "/opt/stronghold/plugins"

Важно учитывать:

  • plugin_directory не должен быть символьной ссылкой;
  • если plugin_directory не задан, внешние плагины использовать нельзя;
  • бинарный файл плагина должен физически находиться в этом каталоге.

Регистрация внешнего плагина

Перед включением внешний плагин нужно зарегистрировать в каталоге плагинов, чтобы Stronghold мог проверить его подлинность и целостность.

Пример регистрации:

PLUGIN_SHA=$(sha256sum /opt/stronghold/plugins/passthrough-plugin | awk '{print $1}')

stronghold plugin register \
  -sha256="${PLUGIN_SHA}" \
  secret \
  passthrough-plugin

Если плагин использует versioning, можно явно указать версию:

stronghold plugin register \
  -sha256="${PLUGIN_SHA}" \
  -version="v1.0.0" \
  secret \
  passthrough-plugin

Stronghold поддерживает регистрацию нескольких версий одного и того же плагина.

Включение внешнего плагина

После регистрации плагин можно включить по нужному mount path:

stronghold secrets enable -path=my-secrets passthrough-plugin

Пример результата:

Success! Enabled the passthrough-plugin secrets engine at: my-secrets/

После этого плагин будет отображаться в списке подключённых движков.

Отключение плагина

Отключение внешнего плагина выполняется так же, как и для встроенных движков:

stronghold secrets disable my-secrets

Если нужно полностью убрать внешний плагин из каталога, после отключения его можно снять с регистрации:

stronghold plugin deregister secret passthrough-plugin

Версии плагинов

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

Если версия задаётся вручную:

  • она должна соответствовать semantic version;
  • рекомендуется использовать формат с префиксом v, например v1.0.0;
  • один и тот же тип и имя плагина могут существовать в каталоге в нескольких версиях.

Если версия не указана при монтировании, Stronghold выбирает плагин по следующему приоритету:

  1. Плагин, зарегистрированный без версии.
  2. Плагин с наиболее новой semantic version.
  3. Встроенный плагин.

Права на файлы и mlock

Если Stronghold использует mlock, бинарным файлам внешних плагинов также может понадобиться право на использование mlock.

В таких случаях может потребоваться:

sudo setcap cap_ipc_lock=+ep /opt/stronghold/plugins/<plugin-binary>

Дополнительно Stronghold может проверять владельца и права каталога и файлов плагинов при включённой проверке file permissions.

Практические рекомендации

  • Храните внешние плагины в отдельном каталоге с ограниченным доступом.
  • Проверяйте SHA256 перед регистрацией.
  • Не используйте символьные ссылки для plugin_directory.
  • Для production-сред заранее проверяйте совместимость версии плагина с версией Stronghold.

См. также