GitOps with Flux on Kubernetes: Installation and First Steps

Introduction to GitOps and Flux

GitOps has emerged as a powerful paradigm for managing Kubernetes infrastructure and application deployments. At its core, GitOps promotes the idea that Git repositories should be the single source of truth for your infrastructure, with automated systems handling the synchronization between your declared state in Git and the actual state in your clusters.

Flux is an open-source tool that embodies these principles, providing a comprehensive GitOps solution for Kubernetes environments. Flux continuously monitors your Git repositories and automatically applies changes to your cluster, ensuring that your infrastructure stays in sync with your desired configuration.

In this guide, I’ll walk you through:

1. Installing the Flux CLI tool
2. Bootstrapping Flux on your Kubernetes cluster
3. Setting up your first Git repository for GitOps
4. Creating and applying basic Flux resources
5. Implementing common GitOps workflows with Flux

Prerequisites

Before getting started, make sure you have:

• A running Kubernetes cluster (v1.29.0 or newer)
• kubectl configured to communicate with your cluster
• Git installed on your local machine
• A GitHub/GitLab/BitBucket account for hosting your repositories

Installing the Flux CLI

The first step is to install the Flux command-line interface (CLI), which will help us interact with Flux and bootstrap it on our cluster.

On Linux

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

Verify the installation with:

flux --version

Checking Cluster Compatibility

Before proceeding with the Flux installation, let’s make sure our cluster meets all the requirements:

flux check --pre

This command verifies:

• kubectl connectivity to your cluster
• Kubernetes version compatibility
• Required cluster permissions

Bootstrapping Flux on Your Cluster

Now we’ll bootstrap Flux on our Kubernetes cluster. This will install all the necessary Flux components and configure them to watch a specific Git repository.

Prepare Your Git Repository

First, create a new repository on GitHub (or GitLab/BitBucket) that will serve as the source of truth for your cluster configuration.

Bootstrap Flux

To bootstrap Flux with GitHub, run:

flux bootstrap github \
  --owner=<your-github-username> \
  --repository=fleet-infra \
  --branch=main \
  --path=./clusters/my-cluster \
  --personal

This command:

1. Creates a repository if it doesn’t exist
2. Adds Flux component manifests
3. Deploys Flux components to your cluster
4. Configures Flux to synchronize with the specified Git repository path

You’ll be prompted to provide a personal access token with repo permissions during this process.

If you prefer to use ssh authentication, you can use the following command:

flux bootstrap git \
  --url=ssh://git@<host>/<org>/<repository> \
  --branch=main \
  --private-key-file=<path/to/private.key> \
  --path=clusters/my-cluster

You will see output similar to this:

► cloning branch "main" from Git repository "ssh://[email protected]/TalhaJuikar/flux-demo"
✔ cloned repository
► generating component manifests
✔ generated component manifests
✔ committed component manifests to "main" ("0403efdbc4fd77de82de6ffcae58e4c89a0b3427")
► pushing component manifests to "ssh://[email protected]/TalhaJuikar/flux-demo"
► installing components in "flux-system" namespace
✔ installed components
✔ reconciled components
► determining if source secret "flux-system/flux-system" exists
► generating source secret
✔ public key: ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIBVaj940CWHjIqMXJYfBaLqPGG8scCHrLmFoGYjSmYuC
Please give the key access to your repository: y
► applying source secret "flux-system/flux-system"
✔ reconciled source secret
► generating sync manifests
✔ generated sync manifests
✔ committed sync manifests to "main" ("b2f9a12bd54142fd340869e870cd2321b622d166")
► pushing sync manifests to "ssh://[email protected]/TalhaJuikar/flux-demo"
► applying sync manifests
✔ reconciled sync configuration
◎ waiting for GitRepository "flux-system/flux-system" to be reconciled
✔ GitRepository reconciled successfully
◎ waiting for Kustomization "flux-system/flux-system" to be reconciled
✔ Kustomization reconciled successfully
► confirming components are healthy
✔ helm-controller: deployment ready
✔ kustomize-controller: deployment ready
✔ notification-controller: deployment ready
✔ source-controller: deployment ready
✔ all components are healthy

This output indicates that Flux has been successfully bootstrapped, and the necessary components are now running in your cluster. Check the status of the Flux components with:

kubectl get pods -n flux-system

NAME                                       READY   STATUS    RESTARTS   AGE
helm-controller-b6767d66-gczfc             1/1     Running   0          65s
kustomize-controller-57c7ff5596-4xlxq      1/1     Running   0          65s
notification-controller-58ffd586f7-7hm5s   1/1     Running   0          65s
source-controller-6ff87cb475-x9c42         1/1     Running   0          65s

Verifying the Installation

To ensure that Flux is correctly installed and configured, you can run the following command:

flux check

Also in your Git repository, you should see a new directory structure like this:

repo-name/
├── clusters
    └── my-cluster
        └── flux-system
            ├── gotk-components.yaml
            ├── gotk-sync.yaml
            └── kustomization.yaml

Understanding the Core Flux Components

After bootstrapping, several key components are running in your cluster:

• Source Controller: Manages Git, Helm, and Bucket repositories
• Kustomize Controller: Reconciles Kustomizations and applies them to the cluster
• Helm Controller: Reconciles Helm releases against HelmRepository sources
• Notification Controller: Handles events and alerts from other controllers

These components work together to ensure that your cluster state matches the desired state defined in your Git repository.

Creating Your First GitOps Resources

Let’s create some basic Flux resources to demonstrate how GitOps works in practice. We will deploy a simple podinfo application from a Git repository.

1. Define a Git Repository Source

Create a file named podinfo-repository.yaml:

apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
  name: podinfo
  namespace: flux-system
spec:
  interval: 1m
  ref:
    branch: master
  url: https://github.com/stefanprodan/podinfo

2. Create a Kustomization to Deploy from the Repository

Next, create podinfo-kustomization.yaml:

apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: podinfo
  namespace: flux-system
spec:
  interval: 30m0s
  path: ./kustomize
  prune: true
  retryInterval: 2m0s
  sourceRef:
    kind: GitRepository
    name: podinfo
  targetNamespace: default
  timeout: 3m0s
  wait: true

3. Commit and Push to Your Repository

Add these files to your repository under the path you specified during bootstrap (e.g., ./clusters/my-cluster/):

git add .
git commit -m "Add demo application GitOps configuration"
git push

Your Git repository should now look like this:

repo-name/
├── clusters
    └── my-cluster
        └── flux-system
        |   ├── gotk-components.yaml
        |   ├── gotk-sync.yaml
        |   ├── kustomization.yaml
        ├── podinfo-repository.yaml
        └── podinfo-kustomization.yaml

Flux will automatically detect these changes and create the corresponding resources in your cluster.

Monitoring the Reconciliation

Wait until Flux reconciles the new resources. You can manually trigger a reconciliation with:

flux reconcile source git all

You can check the status of your GitOps resources with:

flux get sources git
flux get kustomizations

Watch the status of the reconciliation:

flux get kustomizations --watch

You should see the podinfo application running in your cluster:

kubectl get pods -n default

Conclusion: Just the Beginning with Flux

In this post, we’ve covered the basics of getting started with Flux for GitOps on Kubernetes, including installation, bootstrapping, and basic deployments. However, this only scratches the surface of Flux’s capabilities.

In upcoming posts, we’ll explore more advanced Flux features such as:

• Kustomization: Advanced customization techniques for managing configuration variants across different environments
• Helm Releases: Deep dive into managing Helm charts with Flux, including chart repositories, values management, and release strategies
• Notifications: Setting up comprehensive notification systems for your GitOps workflows to alert on failures, successes, and events
• Image Automation: Automating updates when new container images become available, including policy-based automation and security scanning integration

By adopting GitOps with Flux, you’re already on the path to:

• Better visibility into your infrastructure changes
• Proper change management with Git-based workflows
• Automated deployments with reduced manual intervention
• Easy rollbacks to previous states when needed
• Improved cluster security through policy enforcement

As you continue your GitOps journey, explore the extensive Flux documentation for more advanced use cases and integrations. The Flux ecosystem continues to grow, providing increasingly powerful tools for Kubernetes operators and developers alike.

Are you using Flux or another GitOps tool in your environment? I’d love to hear about your experiences in the comments below!