Skip to content

GitOps Flow

HomeKube uses a pull-based GitOps model: the cluster continuously pulls its desired state from Git, rather than having CI/CD push changes into the cluster.

How a Change Propagates

sequenceDiagram
    participant Dev as Developer
    participant Git as GitHub
    participant Flux as FluxCD (source-controller)
    participant KS as kustomize-controller
    participant HC as helm-controller
    participant K8s as Kubernetes API

    Dev->>Git: git push (e.g. bump chart version)
    Note over Git: New commit on main

    Flux->>Git: poll every 1h (or manual reconcile)
    Git-->>Flux: new artifact (git SHA)

    Flux->>KS: notify: new revision available
    KS->>K8s: kustomize build → kubectl apply
    K8s-->>KS: applied ✅

    Flux->>HC: notify: HelmRelease changed
    HC->>K8s: helm upgrade
    K8s-->>HC: upgraded ✅

Image Automation Flow

Flux also closes the loop for container image updates automatically — no manual tag edits required.

sequenceDiagram
    participant CI as GitHub Actions
    participant Reg as ghcr.io
    participant IR as image-reflector-controller
    participant IA as image-automation-controller
    participant Git as GitHub (flux/image-updates)
    participant Flux as FluxCD

    CI->>Reg: push image :42 (run number tag)
    IR->>Reg: poll every 5m
    Reg-->>IR: new tag :42 detected
    IR->>IA: ImagePolicy matched :42
    IA->>Git: commit updated tag in deployment.yaml
    Git-->>Flux: PR merged to main
    Flux->>Flux: normal reconcile → rolls out new image

Tag bumps are pushed to the flux/image-updates branch for review before landing on main.

Reconciliation Interval

Resource Interval Meaning
GitRepository auto (event-driven) Pulls on push if using webhook; otherwise polls
HelmRepository 24h Checks for new chart versions daily
Kustomization 1h Re-applies even if no Git change (drift correction)
HelmRelease 30m Re-reconciles HelmRelease spec
ImageRepository 5m Polls container registry for new tags
ImageUpdateAutomation 5m Commits updated tags to Git when policy matches

Drift Correction

If someone manually edits a resource with kubectl edit, Flux will revert it on the next reconciliation interval. This enforces Git as the only source of truth.

# To temporarily prevent Flux from overwriting a change:
flux suspend ks infrastructure-controllers

# Resume when done:
flux resume ks infrastructure-controllers

Force Immediate Sync

# Pull latest Git changes immediately
flux reconcile source git flux-system

# Re-apply a specific Kustomization immediately
flux reconcile ks infrastructure-controllers --with-source

# Re-apply a specific HelmRelease immediately
flux reconcile hr cert-manager -n cert-manager

How to Make a Change

  1. Edit the relevant YAML file locally
  2. git add . && git commit -m "..." && git push
  3. Either wait for the 1h interval, or run flux reconcile source git flux-system
  4. Watch with flux get ks -A --watch

This is the only correct way to change cluster state in a GitOps setup.