Guide to Setting Up Flux on Kubernetes

techhadoop Flux, kubernetes

Setting up Flux on Kubernetes is a straightforward process, but you will need a few prerequisites before you start. Flux operates via a CLI that interacts with your cluster and bootstraps itself directly into your Git repository.

Here is the step-by-step guide to installing and setting up Flux.

Prerequisites

Before running any commands, ensure you have:

  1. A Kubernetes cluster (Minikube, EKS, GKE, KIND, etc.) and your kubectl context pointed to it.
  2. A Git Provider account (GitHub, GitLab, Bitbucket) and a Personal Access Token (PAT) with repository read/write permissions.

Step 1: Install the Flux CLI

The Flux CLI is used to bootstrap the cluster and manage your GitOps pipeline.

On macOS / Linux (via Homebrew):

Bash

brew install fluxcd/tap/flux
On Linux (via Bash script):

Bash

curl -s https://fluxcd.io/install.sh | sudo bash
On Windows (via Chocolatey):

DOS

choco install flux

Verify the installation by running:

Bash

flux --version

Step 2: Pre-check Your Cluster

Before installing Flux on your cluster, verify that your Kubernetes environment meets all requirements (like the correct version and API permissions):

Bash

flux check --pre

If everything returns a green checkmark, you are ready to bootstrap!

Step 3: Bootstrap Flux

The bootstrap command is where the magic happens. It performs several actions simultaneously:

  1. Creates a private Git repository if it doesn’t exist (or uses an existing one).
  2. Generates the Flux control plane manifests (deployments, CRDs, etc.).
  3. Commits those manifests to your Git repository.
  4. Configures the cluster to watch that exact folder in Git.
Example for GitHub:

First, export your GitHub personal access token so the CLI can authenticate:

Bash

export GITHUB_TOKEN=ghp_your_actual_token_here

Now, run the bootstrap command:

Bash

flux bootstrap github \
  --owner=your-github-username \
  --repository=fleet-infra \
  --branch=main \
  --path=./clusters/my-cluster \
  --personal
What just happened?
  • Flux created a repository named fleet-infra on your GitHub account.
  • It installed components like the source-controller and kustomize-controller inside a new namespace called flux-system in your cluster.
  • It configured your cluster to continuously sync with ./clusters/my-cluster in that repository.

Step 4: Verify the Installation

To ensure Flux is up and running inside your cluster, run:

Bash

flux check

You can also use standard kubectl to see the running pods:

Bash

kubectl get pods -n flux-system

Step 5: Deploying Your First App (The GitOps Way)

Now that Flux is watching your repository, never use kubectl apply manually again. To deploy an application, you simply push a manifest to your Git repo.

  1. Clone your newly created repository to your local machine:Bashgit clone https://github.com/your-github-username/fleet-infra.git cd fleet-infra
  2. Create a Kubernetes deployment manifest inside the watched directory (./clusters/my-cluster/podinfo.yaml):YAMLapiVersion: apps/v1 kind: Deployment metadata: name: podinfo namespace: default spec: replicas: 2 selector: matchLabels: app: podinfo template: metadata: labels: app: podinfo spec: containers: - name: podinfo image: ghcr.io/stefanprodan/podinfo:6.0.0 ports: - containerPort: 9898
  3. Commit and push the file:Bashgit add . git commit -m "Add podinfo deployment" git push origin main

Within 5 minutes (or immediately if you run flux reconcile kustomization flux-system), Flux will detect the change and deploy podinfo to your cluster.

Flux uses a dedicated Notification Controller to offload its events natively to external systems. The process works by pairing a Provider (where the alert goes, e.g., Slack/Discord Webhook) with an Alert (which specific cluster actions trigger the notification).

Here is how to set it up for either platform.

Step 1: Create a Kubernetes Secret for your Webhook

First, you need to grab the Webhook URL from your platform:

  • Slack: Create an app in the Slack API console, enable Incoming Webhooks, and create a webhook for your channel.
  • Discord: Go to Channel Settings → Integrations → Webhooks → Create Webhook, and copy the URL.

Once you have the URL, create a Kubernetes secret in the flux-system namespace. Choose one option below:

Option A: For Slack
kubectl create secret generic slack-webhook-url \
  --namespace=flux-system \
  --from-literal=address=https://hooks.slack.com/services/T0000/B0000/XXXXXX
Option B: For Discord
kubectl create secret generic discord-webhook-url \
  --namespace=flux-system \
  --from-literal=address=https://discord.com/api/webhooks/123456/XXXXXX

Step 2: Define the Flux Provider

The Provider object points directly to the secret you just created and identifies the backend type. Choose the YAML corresponding to your platform and add it to your cluster (or commit it to your Git repository directory).

Option A: Slack Provider (provider-slack.yaml)
apiVersion: notification.toolkit.fluxcd.io/v1beta3
kind: Provider
metadata:
  name: slack-provider
  namespace: flux-system
spec:
  type: slack
  channel: '#devops-alerts' # Optional: overrides default webhook channel
  secretRef:
    name: slack-webhook-url
Option B: Discord Provider (provider-discord.yaml)
apiVersion: notification.toolkit.fluxcd.io/v1beta3
kind: Provider
metadata:
  name: discord-provider
  namespace: flux-system
spec:
  type: discord
  secretRef:
    name: discord-webhook-url

Step 3: Define the Flux Alert

The Alert object links your Git repositories and applications to the Provider. It controls what triggers an alert. You can listen for errors only, or all information events.

Create an alert.yaml manifest that references your provider (adjust name: slack-provider to name: discord-provider if needed):

apiVersion: notification.toolkit.fluxcd.io/v1beta3
kind: Alert
metadata:
  name: cluster-alert
  namespace: flux-system
spec:
  # 1. Reference the provider you made in Step 2
  providerRef:
    name: slack-provider # Or discord-provider
  
  # 2. Filter severity: choose 'info' for all updates, or 'error' for failures only
  eventSeverity: info 
  
  # 3. Choose which resources to listen to ('*' means all resources of this type)
  eventSources:
    - kind: GitRepository
      name: '*'
    - kind: Kustomization
      name: '*'
    - kind: HelmRelease
      name: '*'

Apply your chosen provider and alert manifests using kubectl apply -f <filename>.yaml (or push them to Git if you are following standard GitOps flow).

Step 4: Test the Setup

To verify everything works and force an immediate sync event to trigger a chat alert, tell Flux to manually reconcile:

flux reconcile kustomization flux-system --with-source

Within a few seconds, you should see a richly formatted message appear in your chat channel outlining the commit hash, the status, and what components synchronized successfully.

Leave a Reply