Плагины Logstash

Базовый образ Logstash в составе дистрибутива уже содержит плагины для работы с OpenSearch (logstash-input-opensearch, logstash-output-opensearch). Некоторым пользователям требуются дополнительные плагины (например, для S3, syslog и др.), которые не входят в поставку.

Такие плагины можно установить без пересборки образа и без отключения read_only — через переопределяемый файл docker-compose.additional.yml.

Как это работает

Образ подготовлен так, что при монтировании именованного тома logstash-plugins в каталог /usr/share/logstash/vendor/bundle все файлы, которые создаёт logstash-plugin install (гемы, Gemfile, Gemfile.lock), попадают на этот том, а корневая файловая система контейнера остаётся read_only. При первом запуске Docker сам наполняет том содержимым образа, поэтому встроенные плагины OpenSearch сохраняются. Плагины из переменной LOGSTASH_PLUGINS устанавливает entrypoint образа — один раз; при перезапуске и пересоздании контейнера они берутся с тома и повторно не устанавливаются.

Оригинальный образ и его контрольная сумма при этом не меняются.

Установка плагинов из сети (онлайн)

Если сервер имеет доступ к репозиторию гемов (rubygems.org или зеркалу), достаточно перечислить нужные плагины в переменной LOGSTASH_PLUGINS (через пробел) и примонтировать том logstash-plugins.

Добавьте в additional-конфиг:

docker-compose.additional.yml

services:
  logstash:
    environment:
      LOGSTASH_PLUGINS: "logstash-output-syslog logstash-filter-translate"
    volumes:
      - type: volume
        source: logstash-plugins
        target: /usr/share/logstash/vendor/bundle

volumes:
  logstash-plugins:

Примените изменения (контейнер будет пересоздан, entrypoint установит плагины):

pamirctl start logstash

примечание

Некоторые плагины уже входят в базовый образ через интеграционные пакеты (например, logstash-output-s3 предоставляется пакетом logstash-integration-aws). Для таких плагинов logstash-plugin install вернёт сообщение вида «already provided» — это не ошибка, установка продолжится, плагин доступен «из коробки».

Установка из офлайн-пака (без доступа в интернет)

Если у сервера нет доступа к репозиторию гемов, плагины ставятся из заранее подготовленного offline-пака (.zip). Пак готовится на машине с доступом в интернет, затем переносится на сервер.

Шаг 1. Подготовка пака

warning

prepare-offline-pack упаковывает уже установленные плагины. Если указать плагин, которого нет в образе, команда завершится ошибкой об его отсутствии. Поэтому плагин нужно сначала установить.

Удобнее всего сделать это одной командой: переменная LOGSTASH_PLUGINS заставит entrypoint образа сначала установить плагин, после чего запустится prepare-offline-pack, который соберёт его в архив. Каталог out пробрасывается на хост, туда попадёт готовый .zip.

docker run --rm \
  -v "$(pwd)/data/logstash:/out" \
  -e LOGSTASH_PLUGINS="logstash-output-syslog" \
  pamir.io/logstash:9.2.4 \
  /usr/share/logstash/bin/logstash-plugin prepare-offline-pack \
    --output /out/ls-plugins-9.2.4.zip \
    logstash-output-syslog

Несколько плагинов упаковываются в один архив — перечислите их и в LOGSTASH_PLUGINS (для установки), и в аргументах prepare-offline-pack (для упаковки):

docker run --rm \
  -v "$(pwd)/data/logstash:/out" \
  -e LOGSTASH_PLUGINS="logstash-output-syslog logstash-filter-translate" \
  pamir.io/logstash:9.2.4 \
  /usr/share/logstash/bin/logstash-plugin prepare-offline-pack \
    --output /out/ls-plugins-9.2.4.zip \
    logstash-output-syslog logstash-filter-translate

Совместимость

Пак должен готовиться на той же версии Logstash и той же архитектуре, что и целевой сервер, иначе нативные/зависимые гемы не совпадут. Используйте тот же образ, что и в дистрибутиве (pamir.io/logstash:9.2.4 — уточнить имя и тег можно командой docker compose images logstash или в переменных REGISTRY/LOGSTASH_TAG файла .env). Версию Logstash удобно отражать в имени файла пака.

Шаг 2. Подключение пака

Перенесите полученный .zip на сервер (в примере — в каталог data/logstash рядом с compose-файлами) и укажите путь к нему через схему file://, примонтировав каталог с паком в контейнер:

docker-compose.additional.yml

services:
  logstash:
    environment:
      LOGSTASH_PLUGINS: "file:///tmp/logstash/ls-plugins-9.2.4.zip"
    volumes:
      - type: volume
        source: logstash-plugins
        target: /usr/share/logstash/vendor/bundle
      - type: bind
        source: ./data/logstash
        target: /tmp/logstash

volumes:
  logstash-plugins:

Примените изменения:

pamirctl start logstash

Установка одного пака ставит все входящие в него плагины. Можно комбинировать пак и обычные имена: LOGSTASH_PLUGINS: "file:///tmp/logstash/ls-plugins-9.2.4.zip logstash-filter-tld" — каждый токен обрабатывается отдельной командой установки.

Проверка

Убедиться, что плагин установлен и загружается:

# список установленных плагинов
docker compose exec logstash bin/logstash-plugin list | grep syslog

# логи установки (сообщения entrypoint)
docker compose logs logstash | grep '\[pamir\]'

Строки вида [pamir] plugins ready: ... (первый запуск) и [pamir] plugins already installed: ... (последующие запуски) подтверждают, что механизм отработал и переустановка не выполняется.

Ограничения

• Онлайн-установка требует доступа к rubygems.org или настроенному зеркалу гемов.
• Идемпотентность отслеживается по строке LOGSTASH_PLUGINS. Если обновили содержимое пака, задайте новому файлу другое имя (например, с версией/датой), иначе изменения не будут применены.
• Обновление образа Logstash. Том logstash-plugins «замораживает» каталог vendor/bundle. При переходе на новую версию образа Logstash пересоздайте том (docker volume rm <project>_logstash-plugins при остановленном сервисе) — он будет заново наполнен из нового образа, а пользовательские плагины переустановит entrypoint.