GitOps Setup with Flux in K3s

Before diving in, make sure you have:

• A running K3s cluster
• kubectl installed and configured
• A GitHub account

Step 1: Install Flux CLI

Getting Flux installed is straightforward. Just run:

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

That's it! You're ready to move forward.

Step 2: Bootstrap Flux in Your K3s Cluster

First, let's talk about how to organize your repository. A clean structure makes everything easier to maintain:

<REPOSITORY-NAME>/
├── apps/                     # Your application manifests
│   ├── . ../
│   └── homepage/
├── clusters/                 # Cluster-specific configuration
│   └── <CLUSTER-NAME>/
│       └── flux-system/
│           └── kustomization.yaml
└── README. md

Now, let's bootstrap Flux. You'll need a GitHub Personal Access Token first:

1. Head to GitHub → Settings → Developer settings → Personal access tokens (tokens classic)
2. Click "Generate new token"
3. Grant it repo and write:packages scopes
4. Save your token somewhere safe — you'll need it in a moment

Next, set up your environment variables and bootstrap:

export GITHUB_TOKEN=<your-personal-access-token>
export GITHUB_USER=<your-github-username>

# This command bootstraps Flux and creates the flux-system namespace
flux bootstrap github \
  --owner=$GITHUB_USER \
  --repo=<REPOSITORY-NAME> \
  --branch=main \
  --path=./clusters/<CLUSTER-NAME> \
  --personal

Give it a moment to settle in, then verify everything is running:

# Check if Flux components are ready
flux get all --all-namespaces

# Or take a closer look at the flux-system namespace
kubectl get pods -n flux-system
# Tip: k9s is great for this if you prefer a TUI

Step 3: Set Up Kustomizations for Your Apps

Let's create a Kustomization for your applications. Start with your app directory structure. For example, here's what the homepage application looks like in apps/homepage/kustomization.yaml:

apiVersion: kustomize.config.k8s.io/v1beta1
kind:  Kustomization
namespace: homepage
resources:
  - namespace.yaml
  - deployment.yaml
  - service.yaml
  - ingress.yaml
  - configmap.yaml
  # Add other resource files as needed

Now create a corresponding cluster-level Kustomization in clusters/<CLUSTER-NAME>/homepage.yaml:

apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: homepage
  namespace: flux-system
spec:
  interval: 10m0s
  sourceRef: 
    kind: GitRepository
    name: flux-system
  path: ./apps/homepage
  prune: false  # Pro tip: Keep this false until all your manifests are in Git
  wait:  true

Step 4: Commit, Push, and Sync

Time to get everything into Git and let Flux do its thing:

git add .
git commit -m "Add homepage application with Flux Kustomization"
git push origin main

# Manually sync Flux (optional, but useful if you're utterly impatient!)
flux reconcile source git flux-system -n flux-system
flux reconcile kustomization homepage

Step 5: Keep an Eye on Things

Want to check in on your deployments? Here are some handy commands:

# See the status of all your Kustomizations
flux get kustomizations

# Watch the logs as things deploy
flux logs --all-namespaces --follow

That's it! Your GitOps workflow is now up and running. Any changes you push to your Git repository will automatically sync to your cluster.

Pro tips:

• Start with prune: false until you're confident everything is in Git
• Use flux logs frequently when troubleshooting
• Consider setting up notifications so you know when deployments succeed or fail