Flux GitOps Deployment Guide

Flux is a GitOps continuous delivery tool for Kubernetes that automatically keeps your clusters in sync with sources of configuration (like Git repositories) and automates updates to configuration when there are new commits. This guide will help you understand Flux and set up your first GitOps deployment.

Quick Start for Beginners

If you're new to Flux, here's a simple example to get you started:

Install Flux in your Kubernetes cluster
Bootstrap Flux with your Git repository
Watch Flux sync your application automatically

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

# Bootstrap Flux with your repository
flux bootstrap github \
  --owner=your-username \
  --repository=your-repo \
  --branch=main \
  --path=./clusters/my-cluster

What is Flux

Flux provides:

GitOps Workflow: Uses Git as the single source of truth
Automatic Synchronization: Continuously monitors and syncs applications
Multi-Environment Support: Deploy to multiple clusters and namespaces
Helm Integration: Native support for Helm charts
Kustomize Support: Built-in Kustomize support
Image Automation: Automatically updates images when new versions are available

Flux vs ArgoCD vs GitLab CI

Feature	Flux	ArgoCD	GitLab CI
GitOps	✅ Native	✅ Native	❌ CI/CD focused
Web UI	✅ Flux UI	✅ Rich UI	✅ GitLab UI
CLI	✅ Flux CLI	✅ ArgoCD CLI	✅ GitLab CLI
Helm Support	✅ Native	✅ Native	✅ Via runners
Image Automation	✅ Built-in	❌ External tools	✅ Via CI/CD
Multi-cluster	✅ Native	✅ Native	✅ Via runners
Installation	Simple	Moderate	Complex

Flux Architecture

Core Components

1. Source Controller

Monitors Git repositories and Helm repositories
Provides artifacts for other controllers
Handles authentication and access control

2. Kustomize Controller

Applies Kustomize overlays to Kubernetes clusters
Manages Kustomization resources
Handles dependency management

3. Helm Controller

Manages Helm releases
Handles Helm chart deployments
Supports Helm repository sources

4. Image Automation Controller

Monitors container image repositories
Automatically updates image tags
Triggers Git commits with new image tags

5. Notification Controller

Sends notifications about Flux events
Integrates with Slack, Discord, Microsoft Teams
Provides webhook support

Installation

Using Flux CLI (Recommended)

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

# Verify installation
flux version

# Check prerequisites
flux check --pre

Bootstrap Flux

# Bootstrap with GitHub
flux bootstrap github \
  --owner=my-username \
  --repository=my-repo \
  --branch=main \
  --path=./clusters/my-cluster

# Bootstrap with GitLab
flux bootstrap gitlab \
  --owner=my-username \
  --repository=my-repo \
  --branch=main \
  --path=./clusters/my-cluster

Manual Installation

# Install Flux components
kubectl apply -f https://github.com/fluxcd/flux2/releases/latest/install.yaml

# Verify installation
kubectl get pods -n flux-system

Basic Concepts

GitRepository

A GitRepository resource tells Flux where to find your Git repository and how to access it.

apiVersion: source.toolkit.fluxcd.io/v1beta2
kind: GitRepository
metadata:
  name: my-app
  namespace: flux-system
spec:
  interval: 1m
  url: https://github.com/example/my-app
  ref:
    branch: main
  secretRef:
    name: github-credentials

Kustomization

A Kustomization resource tells Flux how to apply your Kubernetes manifests.

apiVersion: kustomize.toolkit.fluxcd.io/v1beta2
kind: Kustomization
metadata:
  name: my-app
  namespace: flux-system
spec:
  interval: 5m
  sourceRef:
    kind: GitRepository
    name: my-app
  path: "./k8s"
  prune: true
  wait: true

HelmRelease

A HelmRelease resource tells Flux how to deploy Helm charts.

apiVersion: helm.toolkit.fluxcd.io/v2beta1
kind: HelmRelease
metadata:
  name: my-app
  namespace: default
spec:
  interval: 5m
  chart:
    spec:
      chart: my-app
      version: "1.0.0"
      sourceRef:
        kind: HelmRepository
        name: my-charts
  values:
    image:
      tag: "v1.0.0"

Repository Structure

Recommended Structure

my-repo/
├── clusters/
│   └── my-cluster/
│       ├── flux-system/
│       │   ├── gotk-components.yaml
│       │   ├── gotk-sync.yaml
│       │   └── kustomization.yaml
│       └── apps/
│           ├── base/
│           ├── production/
│           └── staging/
├── apps/
│   └── my-app/
│       ├── k8s/
│       │   ├── deployment.yaml
│       │   ├── service.yaml
│       │   └── kustomization.yaml
│       └── helm/
│           └── Chart.yaml
└── README.md

Common Use Cases

1. Simple Application Deployment

# GitRepository
apiVersion: source.toolkit.fluxcd.io/v1beta2
kind: GitRepository
metadata:
  name: web-app
  namespace: flux-system
spec:
  interval: 1m
  url: https://github.com/example/web-app
  ref:
    branch: main

---
# Kustomization
apiVersion: kustomize.toolkit.fluxcd.io/v1beta2
kind: Kustomization
metadata:
  name: web-app
  namespace: flux-system
spec:
  interval: 5m
  sourceRef:
    kind: GitRepository
    name: web-app
  path: "./k8s"
  prune: true
  wait: true

2. Multi-Environment Setup

# Staging Environment
apiVersion: kustomize.toolkit.fluxcd.io/v1beta2
kind: Kustomization
metadata:
  name: app-staging
  namespace: flux-system
spec:
  interval: 5m
  sourceRef:
    kind: GitRepository
    name: my-app
  path: "./apps/staging"
  prune: true

---
# Production Environment
apiVersion: kustomize.toolkit.fluxcd.io/v1beta2
kind: Kustomization
metadata:
  name: app-production
  namespace: flux-system
spec:
  interval: 10m
  sourceRef:
    kind: GitRepository
    name: my-app
  path: "./apps/production"
  prune: true
  wait: true

3. Helm Chart Deployment

# Helm Repository
apiVersion: source.toolkit.fluxcd.io/v1beta2
kind: HelmRepository
metadata:
  name: bitnami
  namespace: flux-system
spec:
  interval: 1h
  url: https://charts.bitnami.com/bitnami

---
# Helm Release
apiVersion: helm.toolkit.fluxcd.io/v2beta1
kind: HelmRelease
metadata:
  name: nginx
  namespace: default
spec:
  interval: 5m
  chart:
    spec:
      chart: nginx
      version: "13.2.0"
      sourceRef:
        kind: HelmRepository
        name: bitnami
  values:
    service:
      type: ClusterIP
    replicaCount: 2

4. Image Automation

# Image Repository
apiVersion: image.toolkit.fluxcd.io/v1beta2
kind: ImageRepository
metadata:
  name: my-app
  namespace: flux-system
spec:
  image: ghcr.io/example/my-app
  interval: 1m

---
# Image Policy
apiVersion: image.toolkit.fluxcd.io/v1beta2
kind: ImagePolicy
metadata:
  name: my-app
  namespace: flux-system
spec:
  imageRepositoryRef:
    name: my-app
  policy:
    semver:
      range: ">=1.0.0 <2.0.0"

---
# Image Update Automation
apiVersion: image.toolkit.fluxcd.io/v1beta1
kind: ImageUpdateAutomation
metadata:
  name: my-app
  namespace: flux-system
spec:
  interval: 1m
  sourceRef:
    kind: GitRepository
    name: my-app
  git:
    checkout:
      ref:
        branch: main
    commit:
      author:
        email: flux@example.com
        name: flux
      messageTemplate: "Update image: {{range .Updated.Images}}{{println .}}{{end}}"
  update:
    path: "./k8s"
    strategy: Setters

Flux CLI Usage

Common Commands

# Check Flux status
flux get all

# Check specific resources
flux get sources git
flux get kustomizations
flux get helmreleases

# Suspend/Resume resources
flux suspend kustomization my-app
flux resume kustomization my-app

# Create resources
flux create source git my-app \
  --url=https://github.com/example/my-app \
  --branch=main

flux create kustomization my-app \
  --source=my-app \
  --path="./k8s" \
  --prune=true

# Export resources
flux export source git my-app > git-repo.yaml
flux export kustomization my-app > kustomization.yaml

Troubleshooting Commands

# Check events
flux get events

# Check logs
flux logs --level=error

# Verify installation
flux check

# Check prerequisites
flux check --pre

Best Practices

1. Repository Organization

my-repo/
├── clusters/
│   └── production/
│       ├── flux-system/
│       └── apps/
├── apps/
│   ├── frontend/
│   ├── backend/
│   └── database/
└── infrastructure/
    ├── monitoring/
    └── logging/

2. Use Kustomize for Environment Management

# base/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - deployment.yaml
  - service.yaml

---
# staging/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../base
patchesStrategicMerge:
  - deployment-patch.yaml

---
# production/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../base
patchesStrategicMerge:
  - deployment-patch.yaml
  - service-patch.yaml

3. Implement Proper Health Checks

apiVersion: kustomize.toolkit.fluxcd.io/v1beta2
kind: Kustomization
metadata:
  name: my-app
  namespace: flux-system
spec:
  interval: 5m
  sourceRef:
    kind: GitRepository
    name: my-app
  path: "./k8s"
  prune: true
  wait: true
  timeout: 5m
  healthChecks:
    - apiVersion: apps/v1
      kind: Deployment
      name: my-app
      namespace: default

4. Use Image Automation

apiVersion: image.toolkit.fluxcd.io/v1beta1
kind: ImageUpdateAutomation
metadata:
  name: my-app
  namespace: flux-system
spec:
  interval: 1m
  sourceRef:
    kind: GitRepository
    name: my-app
  git:
    checkout:
      ref:
        branch: main
    commit:
      author:
        email: flux@example.com
        name: flux
      messageTemplate: "Update image: {{range .Updated.Images}}{{println .}}{{end}}"
  update:
    path: "./k8s"
    strategy: Setters

Troubleshooting

Common Issues

1. Git Repository Access Issues

# Check GitRepository status
flux get sources git

# Check events
kubectl describe gitrepository my-app -n flux-system

# Verify credentials
kubectl get secret github-credentials -n flux-system -o yaml

2. Kustomization Failures

# Check Kustomization status
flux get kustomizations

# Check events
kubectl describe kustomization my-app -n flux-system

# Check logs
flux logs --kind=Kustomization --name=my-app

3. Helm Release Issues

# Check HelmRelease status
flux get helmreleases

# Check Helm repository
flux get sources helm

# Check events
kubectl describe helmrelease my-app -n default

Debug Tips

Check Resource Status: Use flux get all to see overall status
Review Events: Check Kubernetes events for detailed error messages
Validate Manifests: Ensure your Kubernetes manifests are valid
Check Git Access: Verify Flux can access your Git repository
Review Logs: Use flux logs to see detailed logs

Common Beginner Mistakes

1. Incorrect Git Repository URL

# ❌ Wrong - using SSH URL without proper setup
spec:
  url: git@github.com:example/repo.git

# ✅ Correct - use HTTPS URL
spec:
  url: https://github.com/example/repo

2. Missing Source Reference

# ❌ Wrong - missing sourceRef
apiVersion: kustomize.toolkit.fluxcd.io/v1beta2
kind: Kustomization
spec:
  path: "./k8s"

# ✅ Correct - include sourceRef
apiVersion: kustomize.toolkit.fluxcd.io/v1beta2
kind: Kustomization
spec:
  sourceRef:
    kind: GitRepository
    name: my-app
  path: "./k8s"

3. Wrong Path Configuration

# ❌ Wrong - path doesn't exist in repository
spec:
  path: "./non-existent-path"

# ✅ Correct - use actual path in repository
spec:
  path: "./k8s"

Beginner Tips

Start Simple: Begin with basic Kustomizations before complex setups
Use Flux UI: The Flux web interface helps visualize your setup
Test Locally: Validate your Kubernetes manifests locally before committing
Monitor Status: Always check if resources are syncing correctly
Use Image Automation: Automate image updates to reduce manual work
Read Documentation: Flux has excellent official documentation

Flux vs ArgoCD Comparison

When to Choose Flux

Simple Setup: Easier to get started
Image Automation: Built-in image update automation
GitOps Native: Designed from the ground up for GitOps
Lightweight: Smaller resource footprint

When to Choose ArgoCD

Rich UI: More comprehensive web interface
Enterprise Features: Better RBAC and multi-tenancy
Application Management: Better application lifecycle management
Ecosystem: Larger community and ecosystem

Resources

This documentation provides a comprehensive guide to Flux GitOps deployment. For advanced configurations and enterprise features, refer to the official Flux documentation.

Quick Start for Beginners​

What is Flux​

Flux vs ArgoCD vs GitLab CI​

Flux Architecture​

Core Components​

1. Source Controller​

2. Kustomize Controller​

3. Helm Controller​

4. Image Automation Controller​

5. Notification Controller​

Installation​

Using Flux CLI (Recommended)​

Bootstrap Flux​

Manual Installation​

Basic Concepts​

GitRepository​

Kustomization​

HelmRelease​

Repository Structure​

Recommended Structure​

Common Use Cases​

1. Simple Application Deployment​

2. Multi-Environment Setup​

3. Helm Chart Deployment​

4. Image Automation​

Flux CLI Usage​

Common Commands​

Troubleshooting Commands​

Best Practices​

1. Repository Organization​

2. Use Kustomize for Environment Management​

3. Implement Proper Health Checks​

4. Use Image Automation​

Troubleshooting​

Common Issues​

1. Git Repository Access Issues​

2. Kustomization Failures​

3. Helm Release Issues​

Debug Tips​

Common Beginner Mistakes​

1. Incorrect Git Repository URL​

2. Missing Source Reference​

3. Wrong Path Configuration​

Beginner Tips​

Flux vs ArgoCD Comparison​

When to Choose Flux​

When to Choose ArgoCD​

Resources​