Flux Installation

Flux is a set of continuous and progressive delivery tools for Kubernetes, powered by the GitOps Toolkit. It automates deployments by continuously reconciling your cluster state with the desired state defined in Git.

What is Flux?

Flux is a CNCF graduated project that implements GitOps for Kubernetes. It consists of:

Source Controller - Manages Git repositories, Helm repositories, and OCI artifacts
Kustomize Controller - Applies Kustomize overlays
Helm Controller - Manages Helm releases
Image Automation Controllers - Automates image updates

graph TB A[Git Repository] --> B[Source Controller] B --> C[GitRepository CRD] C --> D[Kustomize Controller] C --> E[Helm Controller] D --> F[Kubernetes Resources] E --> F G[Container Registry] --> H[Image Repository] H --> I[Image Policy] I --> J[Image Update Automation] J --> A style B fill:#e1f5ff style D fill:#e8f5e9 style E fill:#fff4e1 style H fill:#f3e5f5

Prerequisites

Before installing Flux, ensure you have:

Kubernetes cluster (v1.20+)
kubectl configured and able to access your cluster
Cluster admin permissions (for installation)
Git repository (for storing manifests)
Git credentials (for repository access)

Installation Methods

Method 1: Bootstrap (Recommended)

The bootstrap method is the easiest way to install Flux. It:

Installs Flux components in your cluster
Configures Git repository access
Creates the necessary Git repository structure

Basic Bootstrap

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

# Bootstrap Flux
flux bootstrap github \
  --owner=your-org \
  --repository=flux-config \
  --branch=main \
  --path=clusters/production \
  --personal

This command:

Creates a Git repository (if it doesn’t exist)
Installs Flux components in the cluster
Configures Flux to watch the repository
Commits the Flux configuration to Git

Bootstrap with Existing Repository

flux bootstrap github \
  --owner=your-org \
  --repository=kubernetes-manifests \
  --branch=main \
  --path=clusters/production \
  --personal

Bootstrap to Different Git Provider

GitLab:

flux bootstrap gitlab \
  --owner=your-group \
  --repository=flux-config \
  --branch=main \
  --path=clusters/production \
  --token-auth

Generic Git:

flux bootstrap git \
  --url=https://github.com/your-org/flux-config \
  --branch=main \
  --path=clusters/production

Method 2: Manual Installation

For more control, install Flux components manually.

Install Flux CLI

macOS:

brew install fluxcd/tap/flux

Linux:

curl -s https://fluxcd.io/install.sh | sudo bash

Windows:

# Using Chocolatey
choco install flux

# Or download from GitHub releases

Install Flux Components

# Install Flux controllers
flux install \
  --components=source-controller,kustomize-controller,helm-controller \
  --namespace=flux-system

# Or install all components
flux install --namespace=flux-system

Verify Installation

# Check Flux components
kubectl get pods -n flux-system

# Check Flux version
flux --version
flux check

Method 3: Using Helm

Install Flux using Helm charts:

# Add Flux Helm repository
helm repo add fluxcd https://fluxcd-community.github.io/helm-charts
helm repo update

# Install Source Controller
helm install source-controller fluxcd/flux2 \
  --namespace flux-system \
  --create-namespace \
  --set components.source-controller.enabled=true

# Install Kustomize Controller
helm install kustomize-controller fluxcd/flux2 \
  --namespace flux-system \
  --set components.kustomize-controller.enabled=true

# Install Helm Controller
helm install helm-controller fluxcd/flux2 \
  --namespace flux-system \
  --set components.helm-controller.enabled=true

Bootstrap Process Explained

The bootstrap process performs several operations:

sequenceDiagram participant CLI as Flux CLI participant Git as Git Repository participant K8s as Kubernetes participant Flux as Flux Controllers CLI->>Git: 1. Create/Verify Repository CLI->>K8s: 2. Create flux-system Namespace CLI->>K8s: 3. Install Flux Components K8s->>Flux: 4. Start Controllers CLI->>Git: 5. Commit Flux Config CLI->>K8s: 6. Create GitRepository Flux->>Git: 7. Clone Repository Flux->>K8s: 8. Apply Manifests

What Bootstrap Creates

Namespace - flux-system namespace
CRDs - Custom Resource Definitions for Flux
Controllers - Flux component deployments
GitRepository - Points to your Git repository
Kustomization - Applies manifests from Git
RBAC - Service accounts and permissions

Bootstrap Output Structure

After bootstrap, your Git repository will have:

flux-config/
├── clusters/
│   └── production/
│       ├── flux-system/
│       │   ├── gotk-components.yaml
│       │   ├── gotk-sync.yaml
│       │   └── kustomization.yaml
│       └── flux-system.yaml
└── README.md

Post-Installation Verification

Check Flux Status

# Check Flux components
flux check

# Expected output:
# ✓ Kubernetes 1.20+ >= 1.20.0
# ✓ controllers 0.x.x >= 0.x.x
# ✓ kustomize >= v3.5.0
# ✓ helm >= v3.0.0-rc.1

Verify Pods

# Check all Flux pods are running
kubectl get pods -n flux-system

# Expected output:
# NAME                                      READY   STATUS    RESTARTS   AGE
# helm-controller-xxx                       1/1     Running   0          5m
# kustomize-controller-xxx                  1/1     Running   0          5m
# source-controller-xxx                      1/1     Running   0          5m

Verify GitRepository

# Check GitRepository status
kubectl get gitrepository -n flux-system

# Get detailed status
kubectl describe gitrepository flux-system -n flux-system

Verify Kustomization

# Check Kustomization status
kubectl get kustomization -n flux-system

# Get detailed status
kubectl describe kustomization flux-system -n flux-system

Configuring Git Access

After installation, configure Git repository access.

Using SSH Key

# Generate SSH key
ssh-keygen -t ed25519 -C "flux" -f ~/.ssh/flux

# Add public key to Git provider (GitHub, GitLab, etc.)

# Create secret in cluster
kubectl create secret generic flux-git-key \
  --from-file=identity=/path/to/flux \
  --namespace=flux-system

# Update GitRepository to use SSH
kubectl patch gitrepository flux-system -n flux-system \
  --type=json \
  -p='[{"op": "replace", "path": "/spec/url", "value": "ssh://[email protected]/your-org/repo.git"}]'

Using HTTPS with Token

# Create secret with token
kubectl create secret generic flux-git-credentials \
  --from-literal=username=your-username \
  --from-literal=password=your-token \
  --namespace=flux-system

# Update GitRepository
kubectl patch gitrepository flux-system -n flux-system \
  --type=json \
  -p='[{"op": "add", "path": "/spec/secretRef", "value": {"name": "flux-git-credentials"}}]'

Using Existing Secret

If you already have a secret:

apiVersion: source.toolkit.fluxcd.io/v1beta2
kind: GitRepository
metadata:
  name: flux-system
  namespace: flux-system
spec:
  url: https://github.com/your-org/repo
  secretRef:
    name: git-credentials
  interval: 1m0s
  ref:
    branch: main

Upgrading Flux

Check Current Version

# Check installed version
flux --version

# Check components version
kubectl get deployment -n flux-system -o jsonpath='{.items[*].spec.template.spec.containers[*].image}'

Upgrade Flux CLI

# macOS
brew upgrade fluxcd/tap/flux

# Linux
curl -s https://fluxcd.io/install.sh | sudo bash

Upgrade Flux Components

# Upgrade to latest version
flux upgrade

# Upgrade to specific version
flux upgrade --version=0.40.0

Verify Upgrade

# Check version after upgrade
flux check

# Verify pods are running
kubectl get pods -n flux-system

Uninstallation

Remove Flux Components

# Uninstall Flux
flux uninstall --namespace=flux-system

# Or manually
kubectl delete -f https://github.com/fluxcd/flux2/releases/latest/download/install.yaml

Clean Up Resources

# Delete namespace (removes all Flux resources)
kubectl delete namespace flux-system

# Delete CRDs
kubectl delete crd -l app.kubernetes.io/part-of=flux

Troubleshooting

Pods Not Starting

# Check pod status
kubectl get pods -n flux-system

# Check pod logs
kubectl logs -n flux-system deployment/source-controller
kubectl logs -n flux-system deployment/kustomize-controller

# Check events
kubectl describe pod -n flux-system <POD_NAME>

GitRepository Not Syncing

# Check GitRepository status
kubectl get gitrepository -n flux-system
kubectl describe gitrepository flux-system -n flux-system

# Check source controller logs
kubectl logs -n flux-system deployment/source-controller

# Verify Git credentials
kubectl get secret -n flux-system

Kustomization Not Applying

# Check Kustomization status
kubectl get kustomization -n flux-system
kubectl describe kustomization flux-system -n flux-system

# Check kustomize controller logs
kubectl logs -n flux-system deployment/kustomize-controller

# Verify GitRepository is ready
kubectl get gitrepository -n flux-system

Permission Issues

# Check service account permissions
kubectl get serviceaccount -n flux-system
kubectl describe serviceaccount kustomize-controller -n flux-system

# Check RBAC
kubectl get clusterrole | grep flux
kubectl get clusterrolebinding | grep flux

Best Practices

1. Use Bootstrap for Initial Setup

Bootstrap is the recommended method for initial installation as it sets up everything correctly.

2. Store Flux Config in Git

Always store Flux configuration (GitRepository, Kustomization) in Git for version control.

3. Use Separate Repositories

Consider separate repositories for:

Flux configuration
Application manifests
Infrastructure code

4. Secure Git Credentials

Use SSH keys when possible
Rotate credentials regularly
Use separate credentials per repository
Store secrets in external secret management

5. Monitor Flux Status

Set up monitoring for:

GitRepository sync status
Kustomization apply status
Controller health
Reconciliation errors

Next Steps

After installing Flux:

Configure GitRepository - Set up access to your Git repository
Create Kustomization - Define what to deploy from Git
Set Up Image Automation - Automate image updates
Configure Multi-Tenancy - Set up tenant isolation

See the GitOps Toolkit guide to learn about Flux components and how they work together.