Стадия жизненного цикла модуля: Experimental
У модуля есть требования для установки

Просмотр логов контроллера и шлюза

Контроллер и шлюз работают в неймспейсе модуля (например d8-security-events-manager).

# Логи контроллера.
kubectl -n d8-security-events-manager logs -l app=security-events-manager-controller -c manager --tail=200

# Логи шлюза (Vector).
kubectl -n d8-security-events-manager logs -l app=gateway -c vector --tail=200

# Сайдкар перезапуска (применяет конфигурационный файл и перезагружает Vector).
kubectl -n d8-security-events-manager logs -l app=gateway -c reloader --tail=100

Просмотр сгенерированного конфигурационного файла Vector

Контроллер записывает полный конфигурационный файл Vector в секрет gateway-vector-config в неймспейсе модуля. Текущий конфигурационный файл можно вывести так:

kubectl -n d8-security-events-manager get secret gateway-vector-config -o jsonpath='{.data.vector\.json}' | base64 -d | jq .

Если jq не используется, часть команды | jq . можно не указывать. В этом случае команда вернёт JSON без форматирования. Проверьте, что sources, transforms и sinks соответствуют вашим ClusterSecurityEventConfig и ClusterSecurityEventDestination. Подробнее про имена преобразований можно прочитать в Конфигурационный файл Vector для шлюза и Подробная логика VRL.

Отладка Vector внутри пода шлюза

API Vector (порт 8686) привязан к 127.0.0.1 (только loopback) и не публикуется в Service шлюза. Это значит, что другие поды в кластере не могут до него достучаться, но вы можете получить к нему доступ изнутри пода шлюза через kubectl exec или port-forward к поду (не к Service).

vector top — метрики компонентов и поток событий в реальном времени

# Интерактивный TUI внутри пода
kubectl -n d8-security-events-manager exec -it deploy/gateway -c vector -- vector top

Или с рабочей станции через port-forward к поду:

kubectl -n d8-security-events-manager port-forward deploy/gateway 8686:8686
vector top --url http://127.0.0.1:8686

Vector CLI — валидация и топология конфигурационного файла

# Валидировать рабочий конфиг (проверка компиляции VRL, схемы sink/source и прочего)
kubectl -n d8-security-events-manager exec -it deploy/gateway -c vector -- vector validate /etc/vector/dynamic/vector.json

# Вывести топологию пайплайна в формате DOT-графа
kubectl -n d8-security-events-manager exec -it deploy/gateway -c vector -- vector graph /etc/vector/dynamic/vector.json

# Список всех компонентов (sources, transforms, sinks) и их конфигурация
kubectl -n d8-security-events-manager exec -it deploy/gateway -c vector -- vector list /etc/vector/dynamic/vector.json

Healthcheck и статус перезагрузки через reloader

Сайдкар reloader слушает на 0.0.0.0:9255 и предоставляет композитный healthcheck-эндпоинт, который проверяет состояние API Vector (GET /health на 127.0.0.1:8686), состояние применения конфигурации и статус fsnotify-watcher — строго лучше, чем прямой опрос /health Vector:

kubectl -n d8-security-events-manager exec deploy/gateway -c reloader -- wget -qO- http://127.0.0.1:9255/reloader/healthz

reloadVector() в reloader использует SIGHUP напрямую — HTTP-эндпоинта POST /reload не существует. Перезагрузка конфигурации запускается автоматически reloader’ом при изменении секрета gateway-vector-config; вручную вызывать какой-либо API не нужно.

Метрики и дашборды

Внутренние метрики Vector экспортируются через prometheus_exporter на 127.0.0.1:9090 внутри пода и собираются gateway PodMonitor через kube-rbac-proxy (порт 9254, путь /metrics). Используйте Grafana-дашборды из модуля (security-events-manager, security-events-manager-loki) или запросите Prometheus напрямую:

# Пример: проверить использование буфера через Prometheus
kubectl -n d8-monitoring exec prometheus-0 -- promtool query instant \
  'vector_buffer_byte_size{job="gateway"}'

Устранение неполадок

  • События не доходят до приёмника — проверьте строку источника в ClusterSecurityEventConfig (enabledSources или enabledSourcesMasks). Формат — clusterSecurityEventShipper/<имя>/<source> или podSecurityEventShipper/<неймспейс>/<имя>/<source>. Подробнее про диагностику доставки событий можно прочитать в FAQ.

  • Невалидный конфигурационный файл Vector — после изменения CR проверьте логи контроллера на ошибки реконсила. Если сгенерированный конфигурационный файл невалиден, перезапуск не применит его и выставит метрику security_events_manager_gateway_config_validation_error=1. В логах перезапуска будет сообщение об ошибке валидации.

  • Ошибки TLS/сертификатов — убедитесь, что настройки TLS и auth в ClusterSecurityEventDestination совпадают с вашим Loki/Elasticsearch и т. д. Для TLS до приёмника поле ca — base64-encoded PEM. Контроллер может создавать секрет с CA для приёмников; проверьте секрет gateway-destination-cas в неймспейсе модуля.

  • Не происходит обогащение через Plugin (enrich.source: Plugin) — сайдкар enrichment-cache обслуживает единый HTTP-эндпоинт обогащения, через который Vector вызывает Lua-трансформ. Проверьте, что сайдкар Ready (он возвращает 503 на /readyz, пока кеш informer подов не завершит первоначальную синхронизацию; кеш NodeUser — best-effort и не блокирует готовность) и что под шлюза Ready. Посмотрите логи и пробы:

    kubectl -n d8-security-events-manager logs -l app=gateway -c enrichment-cache --tail=200
kubectl -n d8-security-events-manager exec deploy/gateway -c enrichment-cache -- wget -qO- http://127.0.0.1:9260/readyz
kubectl -n d8-security-events-manager exec deploy/gateway -c enrichment-cache -- wget -qO- "http://127.0.0.1:9261/api/v1/enrich?plugin=k8s-container-info&container_id=test"
kubectl -n d8-security-events-manager exec deploy/gateway -c enrichment-cache -- wget -qO- "http://127.0.0.1:9261/api/v1/enrich?plugin=k8s-nodeuser-info&uid=1234"

    Сайдкар предоставляет два листенера: 0.0.0.0:9260 для health/readiness/metrics (пробы и kube-rbac-proxy) и 127.0.0.1:9261 для enrichment API (только loopback — только Lua-трансформ Vector в том же поде имеет к нему доступ).

    Метрики собираются через kube-rbac-proxy по пути /enrichment-cache/metrics; смотрите enrichment_cache_lookup_misses_total / enrichment_cache_nodeuser_lookup_misses_total (поиск вернул not-found) и enrichment_cache_informer_synced / enrichment_cache_nodeuser_informer_synced (статус синхронизации кеша). Частые причины: pod_name/namespace указывают на поля, отсутствующие в событии, container_id содержит префикс рантайма, который не был удалён, под удалён (отставание кеша informer), NodeUser с таким uid не существует (проверьте kubectl get nodeuser), либо value не входит в список допустимых значений (serviceAccountName, name, namespace для pod-плагинов; username для k8s-nodeuser-info). Обогащение не фатально — отсутствие записи оставляет поле назначения незаполненным и не отбрасывает событие. Поведение сгенерированного VRL см. в Подробной логике VRL.

Настройка буфера

Модуль использует двухслойную модель буфера для предотвращения потери данных при временной недоступности назначений. Оба слоя по умолчанию используют Disk + Block для нулевых потерь событий безопасности.

Выбор Disk или Memory

Тип Плюсы Минусы Когда использовать
Disk (по умолчанию) Переживает рестарт процесса Vector в поде; нет потерь при коротких сбоях Использует дисковое пространство; немного медленнее Memory Production — всегда используйте Disk для событий безопасности
Memory Быстрее; нет дискового ввода-вывода Все события теряются при рестарте процесса Vector Только тестовые/dev-окружения

Выбор Block или DropNewest

Политика Поведение Когда использовать
Block (по умолчанию) Обратное давление: пайплайн замедляется, НЕТ потерь событий Production — правильный выбор для событий безопасности
DropNewest Новые события отбрасываются при переполнении буфера; нет обратного давления Тестовые окружения, где потеря данных допустима

Расчёт размера буфера

Для оценки времени буферизации при недоступности назначения:

Длительность буфера (часы) = maxSize_байт / (средний_размер_события_байт × событий_в_секунду × 3600)

> `maxSize` задаётся строкой Kubernetes quantity (например `"512Mi"`, `"1Gi"`).
> Для формулы переведите в байты: `512Mi` = 536870912 байт.

Например, при значениях по умолчанию (512 МиБ буфер, ~500 байт на событие, 10 соб/с):

536870912 / (500 × 10 × 3600) ≈ 29.8 часов   (512Mi по умолчанию)

При 10 000 соб/с и событиях 1 КБ:

536870912 / (1024 × 10000 × 3600) ≈ 0.15 часов (~9 минут)

Увеличьте gateway.buffer.maxSize, если скорость событий высокая или ожидаются длительные сбои.

Каскадирование обратного давления

Когда назначение недоступно и whenFull: Block:

  1. Буфер sink gateway переполняется → обратное давление к трансформу route_by_destination
  2. Верхние трансформы блокируются → источник gateway_vector перестаёт принимать события
  3. Агенты log-shipper буферизуют на своей стороне (Слой 1, gateway.logShipperBuffer)
  4. Если буферы агента также заполняются, log-shipper применяет обратное давление к своим источникам (логи подов, хвосты файлов)

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

Ресурсные рекомендации для Disk-буфера

При использовании типа буфера Disk убедитесь, что под gateway имеет достаточно ephemeral storage:

  • emptyDir vector-data имеет sizeLimit, соответствующий gateway.buffer.maxSize
  • Каждая реплика gateway использует до maxSize (например 512Mi) дискового пространства узла
  • При нескольких репликах общее использование диска = реплики × maxSize
  • Рассмотрите добавление лимитов ephemeral storage для узлов или использование узлов с достаточным локальным хранилищем

Отправка событий в формате CEF

События безопасности можно отправлять в формате Common Event Format (CEF) для интеграции с SIEM-системами (Splunk, ArcSight, QRadar и т. д.).

Кодирование CEF настраивается для каждого назначения в ClusterSecurityEventDestination. Поддерживается для Kafka, Vector, File, Console и Socket. Loki, Elasticsearch и SplunkHEC всегда используют JSON.

Базовый CEF через Kafka

apiVersion: security.deckhouse.io/v1alpha1
kind: ClusterSecurityEventDestination
metadata:
  name: siem-kafka
spec:
  type: Kafka
  kafka:
    brokers:
      - "siem-kafka:9092"
    topic: "security-events"
    encoding:
      codec: CEF

События будут отправляться как голые CEF-строки. Шлюз сопоставляет SecurityEvent.event.severity (Low/Medium/High/Critical) в числовую критичность CEF (1/5/8/10), использует event.code как CEF signature ID и event.description как CEF name.

CEF с syslog-обёрткой

Для SIEM-систем, ожидающих CEF в syslog-кадре (типично для UDP/TCP syslog-коллекторов):

apiVersion: security.deckhouse.io/v1alpha1
kind: ClusterSecurityEventDestination
metadata:
  name: siem-syslog
spec:
  type: Kafka
  kafka:
    brokers:
      - "siem-kafka:9092"
    topic: "security-events"
    encoding:
      codec: CEF
      syslogWrapper: RFC5424

Поддерживаемые syslog-обёртки: RFC3164 (BSD syslog), RFC5424 (IETF syslog) или None (по умолчанию, голый CEF).

Кастомные CEF-метаданные

Переопределите device vendor/product/version для конкретного назначения:

apiVersion: security.deckhouse.io/v1alpha1
kind: ClusterSecurityEventDestination
metadata:
  name: siem-custom
spec:
  type: Kafka
  kafka:
    brokers:
      - "siem-kafka:9092"
    topic: "security-events"
    encoding:
      codec: CEF
      cef:
        deviceVendor: "MyCompany"
        deviceProduct: "k8s-security"
        deviceVersion: "2.0"

Или задайте значения по умолчанию глобально в ClusterSecurityEventConfig:

apiVersion: security.deckhouse.io/v1alpha1
kind: ClusterSecurityEventConfig
metadata:
  name: default
spec:
  defaultSeverityThreshold: Low
  destinations:
    - siem-kafka
  cef:
    deviceVendor: "MyCompany"
    deviceProduct: "k8s-security"
    deviceVersion: "2.0"

Переопределения в encoding.cef назначения имеют приоритет над значениями по умолчанию в spec.cef CSEC.