Flux Troubleshooting

Sammlung bekannter Probleme und Lösungsansätze im Zusammenhang mit FluxCD.

Flux Operator

failed to list CRDs: no Flux CRDs found

Symptome

Fehler im Log des Flux Operators:

failed to list CRDs: no Flux CRDs found

Zusätzlich können Artefakte nicht mehr geladen werden:

pulling artifact oci://ghcr.io/controlplaneio-fluxcd/flux-operator-manifests failed:
Get "https://ghcr.io/v2/": context deadline exceeded

Analyse

Das Problem wird durch DNS-Auflösung innerhalb des Clusters verursacht.

Talos leitet DNS-Anfragen standardmäßig an den Host weiter.

Im Zusammenspiel mit Cilium und aktivierter BPF Masquerade können DNS-Anfragen verloren gehen.

CoreDNS zeigt dabei häufig Timeouts:

[ERROR] plugin/errors: 2 ghcr.io. AAAA:
read udp 10.244.0.109:47990->169.254.116.108:53:
i/o timeout

[ERROR] plugin/errors: 2 ghcr.io. A:
read udp 10.244.0.109:55627->169.254.116.108:53:
i/o timeout

Betroffen sind insbesondere:

  • Flux Operator

  • OCIRepository

  • HelmRepository

  • Alle Komponenten mit externen DNS-Abhängigkeiten

Prüfung

DNS-Auflösung innerhalb des Clusters testen:

kubectl run dns-test \
  --rm -it \
  --image=busybox:latest \
  --restart=Never -- nslookup ghcr.io

CoreDNS Logs prüfen:

kubectl -n kube-system logs deployment/coredns

Flux Operator Logs prüfen:

kubectl -n flux-system logs deployment/flux-operator

Lösung

Weiterleitung von Kubernetes DNS an den Talos Host deaktivieren:

machine:
  features:
    hostDNS:
      enabled: true
      forwardKubeDNSToHost: false

Nach Anpassung die Talos-Konfiguration erneut anwenden.

Referenzen

  • Talos Host DNS

  • Cilium BPF Masquerade

  • Flux Operator

OCIRepository

gzip: invalid header

Symptome

OCIRepository 'kube-system/traefik-crds' is not ready:

failed to extract layer contents from artifact:
requires gzip-compressed body:
gzip: invalid header

Ursache

Flux kann den OCI-Layer nicht korrekt identifizieren.

Insbesondere bei OCI-basierten Helm-Charts ist häufig ein expliziter Layer Selector erforderlich.

Lösung

Medientyp explizit konfigurieren:

apiVersion: source.toolkit.fluxcd.io/v1
kind: OCIRepository
metadata:
  name: traefik-crds

spec:
  layerSelector:
    mediaType: application/vnd.cncf.helm.chart.content.v1.tar+gzip
    operation: copy

Anschließend die Quelle erneut synchronisieren:

flux reconcile source oci traefik-crds

HelmRelease

data: Too long: may not be more than 1048576 bytes

Symptome

Helm install failed for release kube-system/traefik-crds:

Secret "sh.helm.release.v1.traefik-crds.v1" is invalid:
data: Too long:
may not be more than 1048576 bytes

Ursache

Das von Helm erzeugte Release-Secret überschreitet die von Kubernetes erlaubte Größe von 1 MiB.

Besonders häufig tritt das auf bei:

  • Großen CRD-Sammlungen

  • Operatoren mit vielen CRDs

  • Helm Charts mit eingebetteten Definitionen

Aktueller Stand

Aktuell ist keine direkte Lösung bekannt.

Mögliche Workarounds

CRDs getrennt von Helm installieren:

Kustomization
    |
    +-- CRDs
    |
    +-- HelmRelease

Alternativen:

  • CRDs per Kustomize deployen

  • Separate OCIRepository für CRDs verwenden

  • Helm Chart ohne CRDs installieren

  • Deployment auf mehrere Releases aufteilen

Betroffene Komponenten

Bekanntes Beispiel:

  • Traefik CRDs

Allgemeines Debugging

Status aller Flux-Komponenten

flux get all

Kustomizations prüfen

flux get kustomizations -A

Helm Releases prüfen

flux get helmreleases -A

Sources prüfen

flux get sources all -A

Ressourcen neu synchronisieren

Kustomization:

flux reconcile kustomization <name>

HelmRelease:

flux reconcile hr <name>

OCIRepository:

flux reconcile source oci <name>

GitRepository:

flux reconcile source git <name>