Skip to content

FluxCD

Fluxcd CLI

Schema dell’architettura fluxcd

1. Ispezione e Stato Generale

Comando Descrizione
flux check Verifica l'installazione e la compatibilità dei componenti nel cluster.
flux get all -A Visualizza tutte le risorse (Git, Helm, KS) in tutti i namespace.
flux stats Mostra statistiche sulle risorse e le performance dei controller.

2. Riconciliazione (Sync Forzato)

Comando Descrizione
flux reconcile source git <nome> Forza il pull immediato dei nuovi commit dal repository Git.
flux reconcile ks <nome> Forza l'applicazione immediata dei manifesti Kustomize.
flux reconcile hr <nome> Sincronizza i valori e aggiorna la HelmRelease specificata.

3. Debug e Troubleshooting

Comando Descrizione
flux logs --all-namespaces Streaming aggregato dei log di tutti i controller Flux.
flux events -n <ns> Mostra la cronologia degli eventi (errori di sync, pull falliti, ecc.).
flux trace <kind> <name> Ricostruisce la catena di dipendenze di una risorsa fino al commit Git.
flux get hr <nome> -o yaml Ispeziona lo stato (status) e i messaggi d'errore dettagliati di una release.

4. Gestione Ciclo di Vita (Maintenance)

Comando Descrizione
flux suspend ks <nome> Sospende la sincronizzazione (utile per modifiche manuali "hotfix").
flux resume ks <nome> Riprende la riconciliazione automatica.
flux suspend hr <nome> Blocca gli aggiornamenti automatici di un Helm Chart.
flux resume hr <nome> Riabilita gli aggiornamenti della HelmRelease.

5. Preview e Validazione Locale

Comando Descrizione
flux build ks <nome> --path ./percorso Renderizza localmente lo YAML finale (dry-run locale).
flux diff ks <nome> --path ./percorso Mostra le differenze tra Git e lo stato attuale del cluster.

6. Risorse Sorgente

Comando Descrizione
flux get sources git Elenca i GitRepository configurati e i relativi branch/commit.
flux get sources helm Elenca i repository Helm e lo stato degli indici (index.yaml).
flux get sources chart Mostra i chart scaricati e pronti per l'installazione.

Alias Rapidi (Shortcuts)

  • ks = kustomization
  • hr = helmrelease
  • git = source git
  • repo = source helm

Esempi

# HelmRelease Grafana con valori applicativi e rollback automatico

apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
  name: grafana
  namespace: monitoring
spec:
  interval: 1h # (1)!
  timeout: 10m # (5)!
  install:
    remediation:
      retries: 3 # (6)!
  upgrade:
    remediation:
      retries: 3 # (7)!
      strategy: rollback # (8)!
  chart:
    spec:
      chart: grafana
      version: ">= 10.5.15" # (2)!
      sourceRef:
        kind: HelmRepository
        name: grafana # (4)!
        namespace: flux-system
  values: # (3)!
    ingress:
      enabled: true
      ingressClassName: traefik
      annotations:
        traefik.ingress.kubernetes.io/router.entrypoints: web
      hosts:
        - test.com
    persistence:
      enabled: true
      storageClassName: local-path-retain
      size: 2Gi
  1. Intervallo di riconciliazione della HelmRelease.
  2. Vincolo di versione del chart Helm installabile dal controller.
  3. Parametri passati direttamente al chart Helm; validarli prima del rilascio con flux diff o render locale.
  4. Nome del HelmRepository Flux da cui recuperare il chart Grafana.
  5. Tempo massimo atteso per installazione o upgrade. Se le risorse non diventano pronte entro questa finestra, l'operazione viene considerata fallita.
  6. Numero di tentativi di remediation durante l'installazione iniziale della release.
  7. Numero di tentativi di remediation durante un upgrade fallito.
  8. Strategia di remediation dell'upgrade: Helm riporta la release alla revisione precedente se la nuova versione non diventa stabile.
# Rendering e dry-run HelmRelease Grafana

flux -n monitoring debug helmrelease grafana --show-values # (1)!
helm repo add grafana https://charts.example.internal/grafana # (2)!
helm template grafana grafana/grafana \
  --namespace monitoring \
  --version "10.5.15" \
  --values values.yaml \
  --dry-run # (3)!
  1. Mostra i valori finali della HelmRelease, inclusi eventuali merge da valuesFrom, ConfigMap o Secret.
  2. Registra localmente il repository Helm usato nell'esempio, cosi il chart puo essere renderizzato fuori dal cluster.
  3. Renderizza il chart senza installarlo, utile per validare manifest e valori prima del commit Git.
# Source chart Grafana fake

apiVersion: source.toolkit.fluxcd.io/v1
kind: HelmRepository
metadata:
  name: grafana # (1)!
  namespace: flux-system
spec:
  interval: 1h # (2)!
  url: https://charts.example.internal/grafana # (3)!
  1. Nome logico del repository Helm. Deve combaciare con sourceRef.name nella HelmRelease.
  2. Frequenza con cui il source-controller aggiorna l'indice del repository Helm.
  3. Endpoint fake del repository Helm Grafana usato nell'esempio; in produzione sostituirlo con l'URL reale del chart repository.
# Verifica della sorgente Helm prima della riconciliazione

flux get sources helm grafana -n flux-system # (1)!
flux reconcile source helm grafana -n flux-system # (2)!
flux get sources chart -A # (3)!
  1. Verifica lo stato del HelmRepository e l'ultimo indice scaricato dal source-controller.
  2. Forza l'aggiornamento immediato della sorgente Helm senza attendere il prossimo interval.
  3. Controlla quali chart sono stati risolti e resi disponibili ai controller Flux.
# Kustomization Flux che abilita il blocco applicativo Kubernetes

apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: apps
  namespace: flux-system
spec:
  interval: 5m # (1)!
  path: "./clusters/rke2-home/apps" # (2)!
  prune: true # (3)!
  sourceRef:
    kind: GitRepository
    name: flux-system # (4)!
  wait: true # (5)!
  timeout: 10m # (6)!
  1. Intervallo con cui Flux riconcilia il blocco applicativo.
  2. Directory Git che contiene il kustomization.yaml Kubernetes e le risorse applicative da abilitare.
  3. Rimuove dal cluster le risorse eliminate dal percorso Git gestito da questa Kustomization.
  4. Sorgente Git gia configurata dal bootstrap Flux.
  5. Attende che le risorse applicate risultino pronte prima di chiudere la riconciliazione.
  6. Tempo massimo di attesa prima di marcare la riconciliazione come fallita.
# Rendering dry-run della Kustomization Flux

flux -n flux-system build kustomization apps \
  --path ./clusters/rke2-home/apps \
  --kustomization-file ./clusters/rke2-home/apps.yaml # (1)!

kustomize build --load-restrictor=LoadRestrictionsNone ./clusters/rke2-home/apps \
  | kubectl apply --server-side --dry-run=server -f- # (2)!
  1. Renderizza localmente la Kustomization Flux usando il manifest della risorsa e il path dei manifest.
  2. Simula l'apply sul cluster con dry-run server-side, utile per intercettare errori API, CRD mancanti o campi non validi.
# clusters/rke2-home/apps/kustomization.yaml

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - namespaces # (1)!
  - monitoring # (2)!
  - ingress # (3)!
  - workloads # (4)!
  1. Abilita prima i namespace richiesti dalle applicazioni.
  2. Include le risorse di monitoring, ad esempio HelmRelease, HelmRepository e configurazioni dedicate.
  3. Include controller, route o manifest legati all'ingress.
  4. Include i workload applicativi gestiti tramite manifest Kubernetes o Kustomize.
# Rendering del kustomization.yaml Kubernetes

kustomize build ./clusters/rke2-home/apps # (1)!
kustomize build ./clusters/rke2-home/apps \
  | kubectl diff -f- # (2)!
kustomize build ./clusters/rke2-home/apps \
  | kubectl apply --dry-run=server -f- # (3)!
  1. Genera il manifest finale aggregando tutte le risorse elencate nel kustomization.yaml.
  2. Mostra le differenze tra manifest renderizzato e stato attuale del cluster.
  3. Esegue una validazione server-side senza applicare modifiche reali.