Стадия жизненного цикла модуля: Общедоступная версия

У модуля есть требования для установки

Модуль observability умеет разворачивать собственное хранилище логов на базе Grafana Loki. Оно заменяет отдельный устаревший модуль loki.

Включается в ModuleConfig observability:

apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: observability
spec:
  version: 1
  settings:
    loki:
      enabled: true

Чтобы логи в него доставлялись, дополнительно должен быть включён модуль log-shipper.

Режимы и хранилища

mode storage.type Где лежат данные Как удаляются логи
Single Disk PersistentVolume По заполнению диска: первыми уходят самые старые логи
Single S3 S3-совместимый бакет По возрасту, после retentionPeriodHours
Distributed только S3 S3-совместимый бакет По возрасту, после retentionPeriodHours

Single разворачивает один экземпляр Loki и используется по умолчанию. Distributed разворачивает Loki в топологии Simple Scalable — раздельные компоненты write, read и backend, которые масштабируются независимо, — и требует storage.type: S3, поскольку компоненты используют общее хранилище. Хранилище настраивается один раз, в storage, независимо от режима.

Диск

У каждого stateful-пода Loki — loki в режиме Single, write и backend в режиме Distributed — есть диск, описанный параметрами storage.disk. Что на нём лежит, зависит от storage.type:

storage.type Что на диске Как выбирать размер Глубина хранения
Disk Чанки, индекс и write-ahead log Под период, заданный retentionPeriodHours По заполнению диска, см. LokiInsufficientDiskForRetention
S3 Write-ahead log, кэш индекса и рабочие файлы compactor Небольшой; значения по умолчанию достаточно По возрасту, силами compactor

С S3 диск по-прежнему PersistentVolume: в write-ahead log лежат логи, которые ingester принял, но ещё не сбросил в бакет, и на эфемерном диске вытеснение пода или отказ узла их потеряли бы. storage.disk.storageClass: false заменяет PersistentVolume на emptyDir в любом режиме.

Данные на диске

settings:
  loki:
    enabled: true
    mode: Single
    storage:
      type: Disk
      disk:
        storageClass: default
        sizeGigabytes: 50
    retentionPeriodHours: 168

При данных на диске retentionPeriodHours — это ориентир, а не ограничение. Loki удаляет данные только по мере заполнения диска, вытесняя самые старые логи. Если это происходит раньше, чем логи достигают заданного возраста, загорается алерт LokiInsufficientDiskForRetention — нужно либо увеличить диск, либо снизить ожидания по глубине хранения.

Объектное хранилище

settings:
  loki:
    enabled: true
    mode: Single
    storage:
      type: S3
      s3:
        endpoint: https://s3.example.com
        bucket: loki
        region: us-east-1
        accessKeyID: ...
        secretAccessKey: ...
        s3ForcePathStyle: true
    retentionPeriodHours: 720

С S3 параметр retentionPeriodHours соблюдается напрямую: compactor удаляет данные старше указанного срока независимо от того, сколько осталось места.

Масштабирование

settings:
  loki:
    enabled: true
    mode: Distributed
    storage:
      type: S3
      s3:
        endpoint: https://s3.example.com
        bucket: loki
        accessKeyID: ...
        secretAccessKey: ...
    distributed:
      write:
        replicas: 3
      read:
        replicas: 5
      backend:
        replicas: 2

Реплик write не может быть меньше трёх: кольцо настроено с фактором репликации 3.

Миграция с модуля loki

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

  1. Включите встроенное хранилище в ModuleConfig observability, как показано выше. Пока ничего не разворачивается: модуль публикует сигнал готовности и ждёт, потому что запуск второго Loki на том же томе привёл бы к конфликту с первым.

    Если в ModuleConfig loki заданы nodeSelector или tolerations, на этом же шаге перенесите их в settings.loki.nodeSelector и settings.loki.tolerations. Встроенное хранилище не читает настройки модуля loki: без них его поды размещаются автоматически, а при WithDataVolume на локальном томе узла под, который не допускает taint этого узла, останется в Pending. То же касается модуля loki, автоматически размещённого на выделенных узлах: он выбирает узлы с меткой node-role.deckhouse.io/loki и допускает taint dedicated.deckhouse.io=loki, а встроенное хранилище ищет узлы observability и system. Если на узлах Loki есть такие метка или taint, задайте под них settings.loki.nodeSelector и settings.loki.tolerations.

  2. Дождитесь алерта LokiModuleSupersededByObservability. Он подтверждает, что observability готов принять хранилище.

  3. Решите, что делать с уже собранными данными, и задайте migrateToObservabilityLoki в ModuleConfig loki:

    apiVersion: deckhouse.io/v1alpha1
    kind: ModuleConfig
    metadata:
      name: loki
    spec:
      settings:
        migrateToObservabilityLoki: WithDataVolume
    Значение Результат
    WithDataVolume Существующий том перехватывается, и уже собранные логи остаются доступны для запросов
    Simple Новое хранилище стартует пустым, старый том остаётся в кластере нетронутым

    При storageClass: false перехватывать нечего, и WithDataVolume ведёт себя как Simple.

  4. Модуль loki перестаёт разворачивать свои ресурсы, observability подхватывает хранилище, и оно снова начинает работать. При WithDataVolume том перепривязывается, а не копируется, поэтому объём данных не влияет на длительность операции.

  5. Дождитесь алерта LokiModuleHandoverCompleted и удалите ModuleConfig loki — из кластера и из Git-репозитория, если конфигурация управляется через GitOps.

Передача необратима: возврат migrateToObservabilityLoki к прежнему значению не вернёт хранилище модулю loki.

Что происходит с перехваченными данными

Данные, записанные старым Loki, используют индекс boltdb-shipper со схемой v11, которую Loki 3.x по-прежнему читает. Вместо конвертации модуль сохраняет этот период в схеме и добавляет современный период tsdb/v13, начиная со следующих суток после миграции. И старые, и новые логи доступны для запросов; старые со временем исчезают за счёт вытеснения по заполнению диска, которое всегда удаляет самые старые таблицы первыми.

День перехода записывается в аннотацию observability.deckhouse.io/tsdb-from на перехваченном PersistentVolumeClaim (d8-observability/storage-loki-0) и больше не пересчитывается. Не редактируйте и не удаляйте её: сдвиг границы приведёт к тому, что данные, уже записанные в tsdb, будут искаться в старом индексе и пропадут из результатов запросов.

До дня перехода Loki работает с выключенными structured metadata: пока активный период схемы — boltdb-shipper, с ними он отказывается запускаться. В день перехода модуль снимает ограничение, один раз перезапустив Loki.

Доставка логов во время передачи

log-shipper доставляет логи в Loki через ClusterLogDestination с именем d8-loki. При передаче модуль loki удаляет свой d8-loki, а этот модуль создаёт свой, когда хранилище готово принимать, — поэтому на время перехвата destination нет вовсе. Пока это так, log-shipper не отбрасывает логи, а перестаёт читать файлы контейнеров: позиции чтения хранятся на узле, и после появления destination чтение продолжается с того же места. Логи теряются только если kubelet успеет ротировать файл лога контейнера до возобновления чтения, поэтому проводите миграцию в период низкой нагрузки. При WithDataVolume окно длится, пока не завершится под старого Loki, а его grace period может растянуть это дольше часа.

Один неуспешный релиз observability во время передачи с ошибкой о том, что d8-loki принадлежит другому релизу, — ожидаемое явление: оба модуля ненадолго претендуют на одно имя. Следующее применение проходит само.

Размер диска и StorageClass во время миграции

При перехвате тома claim создаётся ровно на ёмкость существующего тома, а storage.disk.sizeGigabytes игнорируется: claim, запрашивающий больше, чем предоставляет том, никогда не привяжется. Чтобы увеличить диск, расширьте PersistentVolumeClaim после миграции, если StorageClass это допускает:

kubectl -n d8-observability patch pvc storage-loki-0 \
  -p '{"spec":{"resources":{"requests":{"storage":"100Gi"}}}}'

Не задавайте storage.disk.storageClass или укажите класс перехватываемого тома. При другом классе модуль пересоздаст StatefulSet и его claim, чтобы переехать на этот класс, — а к концу миграции тому уже возвращена исходная политика реклейма, обычно Delete, так что перехваченные данные уйдут вместе с claim.

Оставшиеся тома

PersistentVolumeClaim никогда не удаляется автоматически, поскольку логи на нём могут быть ещё нужны. Том остаётся при переключении на S3, при выключении хранилища и при передаче в режиме Simple. При переключении на S3 claim с данными storage-loki-0 не переиспользуется под write-ahead log: Loki получает новый wal-loki-0, а старый claim остаётся вместе с логами на нём. Такие тома показывает алерт LokiOrphanedPersistentVolumeClaim — как и claim-ы write-ahead log, чьи компоненты больше не работают на S3; найдите и удалите их, когда данные больше не нужны:

kubectl get pvc -A -l app=loki
kubectl get pvc -A -l observability.deckhouse.io/loki-wal

Восстановление застрявшей миграции

Перехват выполняется по одному шагу за проход, и на каждом проходе шаг определяется по состоянию тома и claim-ов, поэтому прерванная миграция продолжается сама. Если алерт LokiVolumeMigrationStalled не гаснет, посмотрите на те же объекты, по которым ориентируется модуль:

kubectl get pv -l observability.deckhouse.io/loki-volume=true -o yaml
kubectl get pvc -A -l app=loki

Метка обозначает перехватываемый том. Данные в безопасности в любом промежуточном состоянии: тому выставляется политика Retain, и переключение подтверждается наблюдением, прежде чем что-либо удаляется. Прежняя политика сохраняется в аннотации observability.deckhouse.io/original-reclaim-policy на самом томе, а последний шаг возвращает её и удаляет аннотацию — поэтому наличие аннотации и означает, что миграция ещё не закончена.

Состояние объектов показывает, на чём она остановилась:

Том и claim-ы Ожидается
Аннотации нет, политика реклейма не менялась Защита тома; пока не сделано ничего
Политика Retain, claim в d8-monitoring ещё существует Удаление этого claim, которому мешает под старого Loki
Claim в d8-monitoring удалён, claimRef всё ещё указывает на него Резервирование тома и создание нового claim
claimRef указывает на d8-observability/storage-loki-0, но не Bound Привязка, которой при WaitForFirstConsumer нужен под Loki
Аннотации нет, claim в состоянии Bound Ничего — миграция завершена

Чтобы перепривязать том вручную, сбросьте устаревшую привязку и укажите пространство имён модуля:

kubectl patch pv <name> --type merge \
  -p '{"spec":{"claimRef":{"apiVersion":"v1","kind":"PersistentVolumeClaim","namespace":"d8-observability","name":"storage-loki-0","uid":null,"resourceVersion":null}}}'

claimRef без UID помечает том как зарезервированный под ещё не существующий claim, поэтому пока модуль его создаёт, том не может занять кто-то другой.