Отладка Flux reconciliation: полевой справочник

Published: 2026-05-17

Flux декларативен и eventually consistent. Когда реконсиляция не проходит, ошибка всегда видна — нужно просто знать, где смотреть. В этом посте — типичные сценарии отказов и способы быстро их диагностировать.

Быстрый обзор

bash# Посмотреть всё, чем управляет Flux, во всех namespace
flux get all -A

# То же самое, только сбои
flux get all -A | grep -v "True\|Unknown"

Столбец READY показывает True, False или Unknown. False — активная ошибка. Unknown — Flux ожидает (например, зависимость).

Kustomization не готова

bashflux get kustomizations -A
# dev   dev-apps   False   kustomize build failed: ...

Получить полную ошибку:

bashkubectl describe kustomization dev-apps -n dev | tail -30

Ошибка `load-restrictor`

Файл Kustomize ссылается на что-то за пределами своей директории:

Error: accumulating resources: accumulation err='merging resources from
'../../../base/app': must build at directory

Решение: не использовать пути ../ в resources:. Ссылаться только на директории, содержащие собственный kustomization.yaml.

Отсутствующий CRD

no matches for kind "HelmRelease" in version "helm.toolkit.fluxcd.io/v2"

Решение: добавить dependsOn, чтобы Kustomization ждала чарт, который устанавливает CRD.

Ошибка валидации YAML

error: error validating data: ValidationError(Deployment.spec.template...)

Решение: запустить kubectl kustomize fluxcd/projects/dev/kustomization/hub/ локально, воспроизвести ошибку и исправить манифест.

HelmRelease не готов

bashflux get helmreleases -A
# dev   elasticsearch   False   Helm upgrade failed: ...

Полная ошибка Helm:

bashkubectl describe helmrelease elasticsearch -n dev
# Смотреть Status.Conditions → поле Message

Remediation застряла

Если предыдущий апгрейд упал и Helm оставил релиз в состоянии failed, последующие повторные попытки тоже падают:

bashflux suspend helmrelease elasticsearch -n dev
helm rollback elasticsearch -n dev   # или helm uninstall если rollback невозможен
flux resume helmrelease elasticsearch -n dev

Ошибка рендеринга values

Секрет valuesFrom не существует или содержит неверный ключ:

unable to get values: secret "apm-es-credentials" not found

Решение: проверить статус ExternalSecret и убедиться, что секрет существует в namespace.

Версия чарта не найдена

chart version ">=1.0.0 <2.0.0" not found

Решение:

bashflux reconcile source helm prometheus-community -n flux-system
flux get source helm -A

Source не синхронизируется

bashflux get source git -A
# flux-system   flux-system   False   failed to checkout and determine revision

bashkubectl describe gitrepository flux-system -n flux-system

Типичные причины:

SSH-ключ ротирован в GitLab, но не обновлён в секрете flux-system
Сетевая проблема: под Flux не может достучаться до GitLab
Изменилось имя ветки

Исправление после ротации SSH-ключа:

bashkubectl create secret generic flux-system \
  --from-file=identity=~/.ssh/flux_ed25519 \
  --from-file=identity.pub=~/.ssh/flux_ed25519.pub \
  --from-literal=known_hosts="$(ssh-keyscan github.com)" \
  -n flux-system --dry-run=client -o yaml | kubectl apply -f -

Принудительный reconcile

bash# Форсировать reconcile Kustomization (сначала обновит source)
flux reconcile kustomization dev-apps -n dev --with-source --timeout=5m

# Форсировать reconcile HelmRelease
flux reconcile helmrelease elasticsearch -n dev --timeout=10m

# Форсировать повторное скачивание git source
flux reconcile source git flux-system -n flux-system

--with-source сначала запускает реконсиляцию GitRepository (скачивает из git), затем Kustomization. Без этого флага Flux использует кэшированный source.

Suspend и resume

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

bash# Приостановить реконсиляцию
flux suspend kustomization dev-apps -n dev
flux suspend helmrelease elasticsearch -n dev

# Сделать ручные изменения...
kubectl edit deployment elasticsearch-master -n dev

# Возобновить
flux resume kustomization dev-apps -n dev
flux resume helmrelease elasticsearch -n dev

Без suspend Flux откатит ручные изменения на следующей итерации реконсиляции.

Поток событий

bash# Смотреть события Flux в реальном времени
flux events --watch -A

# Только ошибки реконсиляции через kubectl
kubectl get events -n dev --watch --field-selector reason=ReconciliationFailed

Kustomization `flux-system`

Это корневая Kustomization, которая бутстрапит всё остальное. Если она падает — реконсиляция останавливается во всех кластерах. Она применяет fluxcd/kustomization.yaml, регистрирующий все environment Kustomizations.

Если добавить файл с синтаксической ошибкой в fluxcd/kustomization.yaml — упадёт вся корневая Kustomization. Всегда тестируйте локально:

bashkubectl kustomize fluxcd/ --dry-run=client

Полезные однострочники

bash# Все HelmRelease, которые не готовы
flux get helmreleases -A | grep -v "True"

# Сводка условий по всем Kustomization
kubectl get kustomization -A -o custom-columns='NAMESPACE:.metadata.namespace,NAME:.metadata.name,READY:.status.conditions[0].status,MSG:.status.conditions[0].message'

# HelmRelease в управлении Kustomization
kubectl get helmrelease -n dev -o yaml | grep "kustomize.toolkit.fluxcd.io/name"

weblog