How to Set Up GitOps Workflow with Flux

How to Set Up GitOps Workflow with Flux

GitOps is an operational framework where your entire infrastructure and application configuration lives in Git. Flux is a CNCF-graduated tool that automatically synchronizes your Kubernetes cluster state with declarations stored in a Git repository, making Git the single source of truth for your Breeze-hosted workloads.

Prerequisites

Before setting up Flux on your Breeze instance, ensure you have:

• A running Kubernetes cluster (k3s, kubeadm, or similar)
• kubectl configured and connected to your cluster
• A Git repository (GitHub, GitLab, or Gitea) for your manifests
• A personal access token with repo permissions

Installing Flux CLI

# Install the Flux CLI
curl -s https://fluxcd.io/install.sh | sudo bash

# Verify installation
flux --version

# Check cluster prerequisites
flux check --pre

Bootstrapping Flux

Bootstrap installs Flux components into your cluster and connects it to your Git repository:

# Set your GitHub token
export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

# Bootstrap with GitHub
flux bootstrap github \
  --owner=your-org \
  --repository=breeze-gitops \
  --path=clusters/production \
  --personal \
  --branch=main

This creates the repository if it does not exist, pushes Flux manifests to it, and installs Flux controllers into the flux-system namespace.

Repository Structure

Organize your GitOps repository for clarity:

breeze-gitops/
├── clusters/
│   └── production/
│       ├── flux-system/          # Auto-generated by bootstrap
│       ├── apps.yaml             # Kustomization for apps
│       └── infrastructure.yaml   # Kustomization for infra
├── apps/
│   ├── web-app/
│   │   ├── deployment.yaml
│   │   ├── service.yaml
│   │   └── kustomization.yaml
│   └── api-service/
│       ├── deployment.yaml
│       ├── service.yaml
│       └── kustomization.yaml
└── infrastructure/
    ├── cert-manager/
    ├── ingress-nginx/
    └── monitoring/

Defining Sources and Kustomizations

Tell Flux where to find your manifests and how to apply them:

# clusters/production/apps.yaml
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: apps
  namespace: flux-system
spec:
  interval: 10m
  sourceRef:
    kind: GitRepository
    name: flux-system
  path: ./apps
  prune: true
  healthChecks:
    - apiVersion: apps/v1
      kind: Deployment
      name: web-app
      namespace: default

Automating Image Updates

Flux can automatically update container image tags when new versions are pushed:

# Create an image repository scanner
flux create image repository web-app \
  --image=registry.example.com/web-app \
  --interval=5m

# Create an image update policy
flux create image policy web-app \
  --image-ref=web-app \
  --select-semver='>=1.0.0'

# Create an image update automation
flux create image update web-app-auto \
  --git-repo-ref=flux-system \
  --branch=main \
  --author-name=flux \
  --author-email=flux@example.com \
  --commit-template="chore: update web-app to {{range .Updated.Images}}{{println .}}{{end}}"

Monitoring and Troubleshooting

# Check Flux component status
flux check

# View all Flux resources
flux get all

# Watch reconciliation events
flux events --watch

# Manually trigger a reconciliation
flux reconcile kustomization apps --with-source

# Suspend updates during maintenance
flux suspend kustomization apps
flux resume kustomization apps

Best Practices

• Protect the main branch — require pull request reviews before merging changes
• Use Kustomize overlays — manage environment-specific configuration without duplication
• Enable pruning — set prune: true so Flux removes resources deleted from Git
• Add health checks — ensure Flux verifies deployments are healthy after applying
• Use SOPS or Sealed Secrets — encrypt secrets stored in Git

GitOps with Flux gives your Breeze infrastructure a reliable, auditable, and automated deployment pipeline anchored in Git.