Tharindu Kalhara

2025-12-27

Getting Started with GitOps/FluxCD on Kubernetes

gitopsfluxcdkubernetes

Getting Started with GitOps using FluxCD on Kubernetes

Hi Cloud Natives,

I recently started working with Kubernetes, and one of the challenges I encountered was manually deploying applications to a Kubernetes cluster (unless a complete CI/CD pipeline was already configured).

The solution is GitOps.

There are several GitOps tools available, with ArgoCD being one of the most popular. However, I found FluxCD to be a lightweight yet powerful alternative that integrates seamlessly with Kubernetes. :contentReference[oaicite:0]

Note: This guide uses an Azure Kubernetes Service (AKS) cluster. The same process can be followed on AWS EKS, Google GKE, or any Kubernetes cluster with only minor changes.

What is GitOps?

GitOps is an operational framework that uses a Git repository as the single source of truth for infrastructure and application configurations.

Instead of manually applying Kubernetes manifests using kubectl apply, all changes are committed to Git. FluxCD continuously monitors the repository and automatically synchronizes your Kubernetes cluster whenever changes are detected. :contentReference[oaicite:1]

Project Structure

After bootstrapping FluxCD, your repository structure should look similar to the following.

.
├── README.md
└── clusters/
    └── terra_k8s_cluster-terra-v2/
        ├── flux-system/
        │   ├── gotk-components.yaml
        │   ├── gotk-sync.yaml
        │   └── kustomization.yaml
        │
        ├── nginx/
        │   ├── deployment.yaml
        │   ├── namespace.yaml
        │   └── service.yaml
        │
        └── tk-namespace/
            └── namespace.yaml

Note: The nginx and tk-namespace directories are simply example Kubernetes resources created after installing FluxCD. They are not part of the Flux installation itself.

Prerequisites

Before starting, ensure you have:

  • A running Kubernetes cluster (AKS, EKS, GKE, Minikube, etc.)
  • kubectl installed
  • A GitHub account
  • A GitHub Personal Access Token (PAT)
  • Flux CLI

Step 1 - Provision a Kubernetes Cluster

I already had a Kubernetes cluster provisioned using Terragrunt.

You can provision yours using:

  • Terraform
  • Terragrunt
  • Azure Portal
  • AWS Console
  • Google Cloud Console

Any Kubernetes cluster will work.

Step 2 - Install kubectl

Install the Kubernetes CLI.

curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"

chmod +x kubectl

sudo mv kubectl /usr/local/bin/

Verify the installation.

kubectl version --client

Step 3 - Install Flux CLI

Install Flux using the official installation script.

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

Verify the installation.

flux --version

Step 4 - Create a GitHub Personal Access Token

Flux requires a GitHub Personal Access Token (PAT) to interact with your GitHub repository.

Navigate to:

GitHub
→ Settings
→ Developer Settings
→ Personal Access Tokens
→ Classic Tokens

Create a token with the required repository permissions.

Export it as an environment variable.

export GITHUB_TOKEN=<your-github-token>

Step 5 - Connect to Your AKS Cluster

Login to Azure.

az login

Download the Kubernetes credentials.

az aks get-credentials \
  --resource-group terra-v2 \
  --name terra_k8s_cluster-terra-v2 \
  --overwrite-existing \
  --admin

Verify the connection.

kubectl get nodes

Step 6 - Bootstrap Flux

This single command installs Flux into your cluster and connects it to your GitHub repository.

flux bootstrap github \
  --token-auth \
  --owner=tharinduk001 \
  --repository=tharinduk-gitops \
  --branch=main \
  --path=clusters/terra_k8s_cluster-terra-v2 \
  --personal

During the bootstrap process, Flux automatically:

  • Installs Flux controllers
  • Creates the flux-system namespace
  • Generates Flux manifests
  • Pushes them to GitHub
  • Configures synchronization between GitHub and Kubernetes

After completion, you'll notice a new directory.

clusters/
└── terra_k8s_cluster-terra-v2/
    └── flux-system/
        ├── gotk-components.yaml
        ├── gotk-sync.yaml
        └── kustomization.yaml

Step 7 - Deploy Applications

Now simply add your Kubernetes manifests to the repository.

Example:

nginx/
├── deployment.yaml
├── service.yaml
└── namespace.yaml

Commit and push them.

git add .

git commit -m "Deploy nginx"

git push

Flux automatically detects the new commit and deploys the resources into your Kubernetes cluster.

No manual deployment is required.

What Happens Behind the Scenes?

Many people assume that Git controls the Kubernetes cluster.

That isn't exactly how Flux works.

The actual workflow is:

Developer
      │
      ▼
 Git Repository
      ▲
      │
 FluxCD continuously watches Git
      │
      ▼
 Kubernetes Cluster

The Kubernetes cluster continuously monitors the Git repository.

Whenever a new commit is pushed:

  1. Flux detects the change.
  2. Flux compares the desired state with the cluster.
  3. Any differences are reconciled.
  4. Kubernetes resources are updated automatically.

This is known as the reconciliation loop. :contentReference[oaicite:2]

Troubleshooting

If your manifests aren't being deployed, first inspect the Flux controllers.

List all running pods.

kubectl get pods -A

Locate the Kustomize Controller pod.

Then stream its logs.

kubectl logs -f <pod-name> -n flux-system

Any deployment or reconciliation errors will appear here.

A useful approach is to keep one terminal open for live logs while working in another terminal.

Force Immediate Synchronization

Normally Flux waits for the next reconciliation interval.

If you want to synchronize immediately, run:

flux reconcile source git \
  -n flux-system \
  flux-system

This forces Flux to pull the latest Git changes instantly.

Conclusion

FluxCD provides an elegant GitOps workflow for Kubernetes by making Git the single source of truth for deployments.

Once configured, developers only need to commit and push Kubernetes manifests. Flux continuously watches the repository and automatically reconciles the cluster with the desired state, eliminating manual deployments and reducing operational overhead. :contentReference[oaicite:3]

Key Takeaways

  • Lightweight GitOps solution for Kubernetes
  • Git becomes the single source of truth
  • Automatic synchronization between Git and the cluster
  • Eliminates manual kubectl apply
  • Simple installation using a single bootstrap command
  • Built-in reconciliation and drift detection
  • Works with AKS, EKS, GKE, Minikube, and other Kubernetes distributions