Стадия жизненного цикла модуля: Общедоступная версия
У модуля есть требования для установки
Модуль 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 объявлен устаревшим, его хранилище переезжает сюда. Миграцию инициируете вы, порядок шагов фиксирован, и передача происходит только когда обе стороны к ней готовы.
-
Включите встроенное хранилище в ModuleConfig
observability, как показано выше. Пока ничего не разворачивается: модуль публикует сигнал готовности и ждёт, потому что запуск второго Loki на том же томе привёл бы к конфликту с первым.Если в ModuleConfig
lokiзаданыnodeSelectorилиtolerations, на этом же шаге перенесите их вsettings.loki.nodeSelectorиsettings.loki.tolerations. Встроенное хранилище не читает настройки модуляloki: без них его поды размещаются автоматически, а приWithDataVolumeна локальном томе узла под, который не допускает taint этого узла, останется вPending. То же касается модуляloki, автоматически размещённого на выделенных узлах: он выбирает узлы с меткойnode-role.deckhouse.io/lokiи допускает taintdedicated.deckhouse.io=loki, а встроенное хранилище ищет узлыobservabilityиsystem. Если на узлах Loki есть такие метка или taint, задайте под нихsettings.loki.nodeSelectorиsettings.loki.tolerations. -
Дождитесь алерта
LokiModuleSupersededByObservability. Он подтверждает, чтоobservabilityготов принять хранилище. -
Решите, что делать с уже собранными данными, и задайте
migrateToObservabilityLokiв ModuleConfigloki:apiVersion: deckhouse.io/v1alpha1 kind: ModuleConfig metadata: name: loki spec: settings: migrateToObservabilityLoki: WithDataVolumeЗначение Результат WithDataVolumeСуществующий том перехватывается, и уже собранные логи остаются доступны для запросов SimpleНовое хранилище стартует пустым, старый том остаётся в кластере нетронутым При
storageClass: falseперехватывать нечего, иWithDataVolumeведёт себя какSimple. -
Модуль
lokiперестаёт разворачивать свои ресурсы,observabilityподхватывает хранилище, и оно снова начинает работать. ПриWithDataVolumeтом перепривязывается, а не копируется, поэтому объём данных не влияет на длительность операции. -
Дождитесь алерта
LokiModuleHandoverCompletedи удалите ModuleConfigloki— из кластера и из 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, поэтому пока модуль его создаёт, том не может занять кто-то другой.