Flux GitOps CLI

Flux CLI cheatsheet — bootstrap, reconcile, check sources and kustomizations. flux bootstrap, flux get all, flux reconcile kustomization, flux logs. GitOps for Kubernetes.

8 min read

What it is

Flux is a set of continuous and progressive delivery solutions for Kubernetes that are open and extensible. The Flux CLI is the command-line interface for interacting with and managing Flux installations. You reach for it when you need to automate Kubernetes deployments from Git repositories.

Installation

Linux

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

macOS

brew install flux

Windows

winget install fluxcd.flux

Core Concepts

  • Source Controller: Reconciles Git repositories (and other sources like Helm repositories or S3 buckets) into Kubernetes resources. This is how Flux pulls your desired state from external sources.
  • Kustomize Controller: Reconciles Kustomizations, applying kustomization.yaml files to your cluster. This is how Flux applies your application manifests, often using Kustomize for templating.
  • Helm Controller: Reconciles Helm Releases, managing Helm chart deployments. This is Flux’s way of handling Helm-based deployments.
  • Notification Controller: Handles events from other controllers and sends notifications to external services like Slack or Microsoft Teams.
  • Image Reflector Controller & Image Automation Controller: Used for automatically updating container images based on policies and image registry scanning.

Commands / Usage

Bootstrapping Flux

Initialize Flux in a Kubernetes cluster and connect it to a Git repository.

  • Bootstrap Flux in a cluster:

    flux bootstrap git \
  --url=https://github.com/fluxcd/flux2-kustomize-example \
  --branch=main \
  --path=./cluster/production \
  --token-auth

    Initializes Flux on the current Kubernetes context and configures it to reconcile resources from the specified Git repository branch and path.

  • Bootstrap with a specific provider (e.g., GitHub):

    flux bootstrap github \
  --owner=fluxcd \
  --repository=flux2-kustomize-example \
  --branch=main \
  --path=./cluster/production \
  --personal

    Bootstraps Flux using GitHub as the Git provider, creating a new repository if it doesn’t exist and setting up the necessary webhook.

  • Bootstrap with a private Git repository (SSH):

    flux bootstrap git \
  --url=ssh://git@github.com/your-username/your-repo.git \
  --branch=main \
  --path=./clusters/my-cluster \
  --private-key-file=/path/to/your/ssh/private/key

    Bootstraps Flux using SSH authentication for a private Git repository.

Managing Sources

Define and manage external sources like Git repositories.

  • Create a GitRepository source:

    flux create source git my-git-repo \
  --url=https://github.com/fluxcd/flux2-kustomize-example \
  --branch=main \
  --interval=1h

    Creates a GitRepository custom resource named my-git-repo that polls the specified URL every hour.

  • Create a HelmRepository source:

    flux create source helm my-helm-repo \
  --interval=1h \
  --url=https://charts.bitnami.com/bitnami

    Creates a HelmRepository custom resource named my-helm-repo pointing to the Bitnami Helm chart repository.

  • List all sources:

    flux get sources git
flux get sources helm
flux get sources all

    Lists all GitRepository, HelmRepository, or all types of sources.

  • Suspend a source:

    flux suspend source git my-git-repo

    Stops Flux from reconciling changes from the my-git-repo Git repository.

  • Resume a source:

    flux resume source git my-git-repo

    Resumes reconciliation for the my-git-repo Git repository.

  • Recreate a source:

    flux recreate source git my-git-repo

    Forces a reconciliation of the my-git-repo Git repository.

Managing Kustomizations

Define and manage Kustomizations, which apply manifests from a source.

  • Create a Kustomization from a GitRepository:

    flux create kustomization my-app-kustomization \
  --source=my-git-repo \
  --path="./apps/my-app/overlays/production" \
  --prune=true \
  --interval=5m

    Creates a Kustomization resource named my-app-kustomization that applies manifests from the ./apps/my-app/overlays/production path within the my-git-repo source, enabling pruning of deleted resources and reconciling every 5 minutes.

  • Create a Kustomization from a HelmRepository (using HelmRelease):

    flux create helmrelease my-helm-app \
  --interval=10m \
  --chart-name=nginx \
  --chart-version="1.16.10" \
  --release-name=my-nginx \
  --namespace=default \
  --source=my-helm-repo \
  --values-file=./helm/my-app-values.yaml

    Creates a HelmRelease resource named my-helm-app to deploy the Nginx chart from my-helm-repo, using specified values and deploying every 10 minutes.

  • List all Kustomizations:

    flux get kustomizations

    Lists all Kustomization resources in the current namespace.

  • List all Helm Releases:

    flux get helmreleases

    Lists all HelmRelease resources in the current namespace.

  • Suspend a Kustomization:

    flux suspend kustomization my-app-kustomization

    Stops Flux from applying changes for the my-app-kustomization.

  • Resume a Kustomization:

    flux resume kustomization my-app-kustomization

    Resumes applying changes for the my-app-kustomization.

  • Recreate a Kustomization:

    flux recreate kustomization my-app-kustomization

    Forces a reconciliation of the my-app-kustomization.

Image Update Automation

Automated image updates based on Git commit.

  • Create an ImageRepository:

    flux create image repository my-app-image \
  --image=ghcr.io/fluxcd/flagger-operator \
  --interval=10m

    Creates an ImageRepository resource to scan the specified container image registry for new image tags every 10 minutes.

  • Create an ImagePolicy:

    flux create image policy my-app-policy \
  --image-repository=my-app-image \
  --policy=semver \
  --pattern='v([0-9]+.[0-9]+.[0-9]+)' \
  --semver-prerelease='alpha'

    Creates an ImagePolicy that selects image tags matching the semantic versioning pattern, including pre-release tags.

  • Create an ImageUpdateAutomation:

    flux create image update automation my-app-automation \
  --git-repo=my-git-repo \
  --git-branch=main \
  --kustomization-name=my-app-kustomization \
  --image-policy=my-app-policy \

{% raw %} –commit-message="chore: update image to {{range .Result}}{{.Image}}@{{.Tag}}{{end}}"
{% endraw %} –author-name="Flux Bot"
--author-email="flux@example.com" ``` Creates an ImageUpdateAutomation resource that automatically commits image tag updates to the specified Git repository and branch, updating the my-app-kustomization.

  • List image update automations:
    flux get image update automations
    Lists all ImageUpdateAutomation resources.

Notifications

Configure event notifications.

  • Create a Notification Provider (Slack):

    flux create notification provider slack \
  --channel="my-channel" \
  --secret-ref="slack-secret"

    Creates a Provider resource for Slack notifications, referencing a Kubernetes Secret containing the webhook URL.

  • Create a Notification Controller:

    flux create notification controller \
  --event-severity="info" \
  --event-sources=".*" \
  --provider="slack" \
  --match="."

    Creates a Controller resource that forwards events from all sources to the configured Slack provider.

Other Useful Commands

  • Check Flux installation:

    flux check

    Verifies that Flux components are running correctly in the cluster.

  • Get Flux components:

    flux get kustomizations flux-system -n flux-system
flux get helmreleases flux-system -n flux-system

    Shows the status of Flux’s own components within the flux-system namespace.

  • Install Flux CLI plugins:

    flux install --components=notification-controller

    Installs additional Flux controllers if they were not installed during bootstrap.

  • Uninstall Flux:

    flux uninstall --namespace=flux-system

    Removes Flux components from the cluster.

Common Patterns

Deploying an application from a Git repository using Kustomize

  1. Ensure your Git repository is added as a source:
    flux create source git apps-repo \
  --url=https://github.com/your-username/your-app-repo.git \
  --branch=main \
  --interval=5m
  2. Create a Kustomization to apply your app manifests:
    flux create kustomization my-app \
  --source=apps-repo \
  --path="./deploy/production" \
  --prune=true \
  --interval=10m

Deploying a Helm chart from a Helm repository

  1. Ensure your Helm repository is added as a source:
    flux create source helm bitnami \
  --interval=1h \
  --url=https://charts.bitnami.com/bitnami
  2. Create a HelmRelease to deploy the chart:
    flux create helmrelease prometheus \
  --source=bitnami \
  --chart-name=prometheus \
  --chart-version="15.0.0" \
  --release-name=prometheus \
  --namespace=monitoring \
  --values-file=./helm/prometheus-values.yaml \
  --interval=15m

Automating image updates for a deployment

  1. Define the image you want to track:
    flux create image repository my-app-image \
  --image=docker.io/myorg/my-app \
  --interval=1h
  2. Define the policy for selecting image tags:
    flux create image policy my-app-policy \
  --image-repository=my-app-image \
  --policy=semver \
  --pattern='v[0-9]+.[0-9]+.[0-9]+$'
  3. Configure automation to update Git and Kustomization:
    flux create image update automation my-app-auto \
  --git-repo=<your-git-repo-url> \
  --git-branch=main \
  --kustomization-name=my-app-kustomization \
  --image-policy=my-app-policy \

{% raw %} –commit-message="ci: update image to {{.Image@Tag}}"
{% endraw %} –author-name="CI Bot"
--author-email="ci@example.com" ```

Gotchas

  • Namespace for Flux Components: By default, Flux installs its core components into the flux-system namespace. Be mindful of this when creating resources like Secrets for Git credentials, as they need to be accessible by the controllers.
  • Service Account Permissions: Ensure the Flux controllers have the necessary RBAC permissions to manage the resources they are responsible for. The bootstrap process typically sets this up, but custom configurations might require manual adjustments.
  • Git Credentials: When working with private Git repositories, Flux needs appropriate credentials. For SSH, the private key must be provided via a Kubernetes Secret. For HTTPS, a username/password or token can be used, also via a Secret. The flux bootstrap command helps set this up, but manual creation might be needed for existing sources.
  • --path in flux bootstrap: The path specified during bootstrap (--path=./cluster/production) refers to the directory within the Git repository that Flux should reconcile.
  • Pruning: The --prune=true flag on flux create kustomization is powerful but can be dangerous. It will delete any Kubernetes resources managed by the Kustomization that are no longer present in the Git repository. Use with caution.
  • Image Update Automation Commit Signing: If your Git repository requires signed commits, you’ll need to configure GPG signing for the Flux bot’s commits, which involves more advanced setup with Kubernetes Secrets and potentially custom configurations.
  • Resource Dependencies: Flux reconciles sources and then applies Kustomizations/HelmReleases. If you have inter-application dependencies, you might need to define dependsOn in your Kustomization or HelmRelease resources to ensure correct ordering.