Install Flux CD on Kubernetes: Set Up GitOps with GitLab

With flux bootstrap gitlab, you install Flux CD on your Kubernetes cluster and connect it to a GitLab project from which Flux then reads the desired state of the cluster. After that, you roll out a sample application by Git commit only, and when someone makes changes directly in the cluster, Flux resets them to the state in Git at the next reconciliation. At the end, you remove Flux and the example completely and know what remains afterwards.

This guide uses Flux 2.9.6, released October 1, 2026, for Kubernetes 1.34 to 1.36 and Flux 2.8.8 for Kubernetes 1.33 (as of October 9, 2026). Flux reads the GitLab project through a read-only deploy token. According to the Flux documentation, the procedure applies to gitlab.com and to self-managed GitLab instances. This article is part of the series on CI/CD on Kubernetes: How CI jobs run as pods in your cluster is shown in Install GitLab Runner on Kubernetes. For Argo CD, there is a separate tutorial.

What is Flux CD?

Flux CD is an open and extensible continuous delivery tool for Kubernetes that reads the desired state of a cluster from a Git repository and uses specialized controllers to make sure the cluster matches that state.

Technically, Flux consists of the GitOps Toolkit, a set of specialized controllers and composable APIs. These APIs are Kubernetes custom resources. A GitRepository describes where the desired state comes from. A Kustomization defines which manifests from it are applied in the cluster. A HelmRelease manages Helm releases. According to the Flux docs, you list all Flux resources in the cluster with kubectl get fluxcd -A.

The difference from deploying out of a pipeline lies in the direction. The pipeline doesn't write to the cluster with kubectl apply; instead, Flux pulls the desired state from Git. According to the Flux docs, after the bootstrap all changes to the cluster, including upgrades of Flux itself, can be made via Git push, without connecting to the cluster directly.

graph LR
  G["GitLab project"] -->|"reads via deploy token"| S["source-controller with GitRepository"]
  S -->|"provides artifact"| K["kustomize-controller with Kustomization"]
  K -->|"applies manifests and corrects drift"| C["Objects in the cluster"]

Flux is a project of the Cloud Native Computing Foundation (CNCF). It was accepted there on July 15, 2019, and reached the Graduated maturity level on November 30, 2022.

Flux CD or Argo CD: What is the difference?

Flux CD and Argo CD are both declarative GitOps tools for Kubernetes, but according to their documentation they differ in their architecture, in how you operate them, and in how you install them.

The table only compares features that the respective project documentation names itself (as of October 9, 2026):

This does not imply a ranking. Argo CD makes sense if your team mainly wants to track and sync deployments in the built-in web interface described in the Argo CD docs. Flux makes sense if you want the bootstrap to also put installation and upgrades of the tool under Git control and your work runs through the command line and commits. Both approaches follow the same principle: Git is the source of the desired state.

Prerequisites

• Kubernetes cluster, for example a centron Managed Kubernetes cluster, running a version from the table below. According to the Flux docs, you need cluster admin permissions on the target cluster.
• kubectl with access to the cluster. If you don't have kubectl yet, the tutorial Install and use kubectl to manage Kubernetes clusters helps. The flux commands use the same current context of your kubeconfig; use --context to select a different one.
• Linux or macOS with curl (or wget) and sha256sum (or shasum). According to its source code, the installation script of the Flux CLI supports these two operating systems on amd64, arm64, and arm.
• GitLab account on gitlab.com or on your own GitLab instance. According to the Flux docs, you must be Owner of the project or have admin permissions in the GitLab group. The project doesn't have to exist yet; Flux creates it as a private project during the bootstrap.
• Git on your machine to clone the project and push changes.
• Outbound HTTPS access from the cluster to your GitLab instance and to the image registries. By default, the Flux controllers come from ghcr.io/fluxcd, and the sample image nginx:1.30.5 comes from Docker Hub.

Choose the right Flux version

First, read the Kubernetes version of your cluster. The Server Version line is what counts:

$ kubectl version

Then choose the Flux version according to the compatibility tables in the release notes of Flux 2.9.0 and Flux 2.8.0:

Two edge cases: Kubernetes 1.34.0 is below the minimum of both series (1.34.1 in each case), so upgrade the cluster to a newer patch first. Kubernetes 1.37 is not listed in either table (as of October 9, 2026).

According to its release documentation, the Flux project supports the last three minor versions of Flux and does not test against Kubernetes versions whose upstream support has ended. According to the Kubernetes project, Kubernetes 1.33 reached the end of upstream support on June 28, 2026, and Kubernetes 1.34 reaches it on October 27, 2026. For such versions, the Flux project does not commit to future Flux releases still working. The 2.8.8 path is therefore an interim solution. Plan the move to a maintained minor version as soon as one is available for your cluster. All commands in this guide are the same for 2.9.6 and 2.8.8; the flags of flux bootstrap gitlab are defined identically in the source code of both versions.

Create a GitLab token

For the bootstrap, the CLI needs a personal access token (PAT) with full read and write access to the GitLab API. In GitLab, this corresponds to the api scope. According to the GitLab documentation, you create it as follows (documentation as of October 9, 2026; menu names may differ on older self-managed instances):

1. In the upper-right corner, select your avatar and choose Edit profile.
2. In the left sidebar, open Access > Personal access tokens.
3. In the Generate token menu, choose Legacy token.
4. Enter a name, for example flux-bootstrap, and set an expiration date in the near future under Expiration date. If you don't specify one, GitLab sets the expiration date to 365 days from today.
5. Select the api scope and select Generate token. Store the token securely right away, because GitLab no longer shows it once you leave the page.

A short expiration date limits the risk if the token falls into the wrong hands. With the --deploy-token-auth option from the section after next, Flux doesn't store this PAT in the cluster, but a separate deploy token.

Install the Flux CLI and check the cluster

You install the Flux CLI in exactly the version that matches your cluster according to the table, and then use flux check --pre to check whether the cluster meets the minimum requirement of the CLI.

Set the version as a variable. For a cluster running Kubernetes 1.33, enter 2.8.8 here:

$ export FLUX_VERSION=2.9.6
$ curl -s https://fluxcd.io/install.sh | bash

The installation script reads the FLUX_VERSION variable and then downloads exactly this release instead of the latest one. It also downloads the checksum file of the release and aborts if the SHA-256 checksum of the downloaded archive doesn't match. In its output, it names the version used in the line containing as release. The binary ends up in /usr/local/bin/flux. If that directory isn't writable for you, the script calls sudo itself for this one step. The Flux docs show the call with sudo bash. Here, bash runs without sudo, because depending on its configuration, sudo doesn't pass environment variables through.

If you open a new shell later, FLUX_VERSION is no longer set there. You don't need the variable for the remaining steps; for a reinstallation, set it again.

Now check the cluster:

$ flux check --pre

The pre-check reads the Kubernetes version of the cluster and compares it with the minimum requirement of the CLI. According to the Flux docs, it ends with prerequisites checks passed on success.

Important for choosing the version: In both 2.9.6 and 2.8.8, flux check --pre accepts any Kubernetes version from 1.33.0 onward (source code check.go of both versions). So a passed check doesn't mean that your Kubernetes version is in the compatibility table of the installed Flux version. The table above is what counts.

With 2.8.8, flux check additionally reports a line with the note new CLI version is available, please upgrade. According to the source code, this does not abort the check. For a cluster running Kubernetes 1.33, you still stay on 2.8.8. 2.9.6 shows the same note as soon as a newer Flux version is released. In that case, check its compatibility table first before you upgrade.

Bootstrap Flux with GitLab

During the bootstrap, the Flux CLI installs the controllers in the flux-system namespace, stores their manifests in your GitLab project, and sets up Flux so that it then updates itself from this project.

Provide the token

The CLI reads the PAT from the GITLAB_TOKEN environment variable. If it isn't set, flux bootstrap gitlab prompts for the token interactively at startup. That is the simplest way to keep the token out of your shell history. If you want to set the variable anyway, for example because you run the command several times:

$ export GITLAB_TOKEN=<gitlab-pat>

Replace <gitlab-pat> with the token from the prerequisites. This way, it ends up in plain text in your shell history. Don't write it into scripts or into the repository, and remove it from the session with unset GITLAB_TOKEN after the bootstrap.

Bootstrap for a project in your user account

$ flux bootstrap gitlab \
  --deploy-token-auth \
  --owner=<gitlab-user> \
  --repository=<project> \
  --branch=main \
  --path=clusters/<cluster-name> \
  --personal

The placeholders:

• <gitlab-user>: your GitLab username.
• <project>: the name of the GitLab project in which Flux stores its manifests. If it doesn't exist yet, Flux creates it as a private project.
• <cluster-name>: a name of your choice for this cluster, for example staging. Flux only syncs this path, so a project can later contain several clusters in separate directories.

The flags in detail, according to the CLI reference and the bootstrap guide for GitLab:

Other defaults you don't need to set here: --visibility is private, --hostname is gitlab.com, and --interval, the interval at which the GitRepository flux-system checks the project for new commits, is one minute.

What the command does:

1. It installs the controllers source-controller, kustomize-controller, helm-controller, and notification-controller in the flux-system namespace.
2. It commits their manifests to the specified branch, under clusters/<cluster-name>/flux-system/.
3. It creates the deploy token and stores it as a Secret in the cluster.
4. It sets up a GitRepository and a Kustomization, both named flux-system, which reconcile the path clusters/<cluster-name> from the project.

According to the Flux docs, the bootstrap is idempotent. If the controllers are already in the cluster, running it again performs an upgrade if needed. For every later run of flux bootstrap gitlab, you need a valid PAT again, because the command reads it at every start.

Why --deploy-token-auth instead of --token-auth: According to the source code (bootstrap_gitlab.go, tag v2.9.6), with --token-auth the CLI writes the PAT itself as the password into the Secret flux-system. A token with full API access would then sit in the cluster. The CLI rejects both options together. According to the GitLab docs, the deploy token is not tied to your user account and doesn't expire if no expiration date is set. Because it can only read, image automation that writes changes back to Git doesn't work with it. For that, the Flux docs describe a deploy key with write permissions.

Variant: project in a GitLab group

If the project belongs to a group, leave out --personal and specify the group as the owner. Separate subgroups with a slash, so <gitlab-group>/<subgroup>:

$ flux bootstrap gitlab \
  --deploy-token-auth \
  --owner=<gitlab-group> \
  --repository=<project> \
  --branch=main \
  --path=clusters/<cluster-name>

Variant: self-managed GitLab instance

For a self-managed instance, add --hostname with the hostname of your instance, for example gitlab.example.com:

$ flux bootstrap gitlab \
  --deploy-token-auth \
  --hostname=<gitlab-host> \
  --owner=<gitlab-group> \
  --repository=<project> \
  --branch=main \
  --path=clusters/<cluster-name>

If your instance uses a self-signed certificate, pass the path to the CA file with --ca-file=<ca-file>. The CLI then also adds the certificate to the Secret flux-system.

For Git servers other than GitLab, the Flux installation docs describe separate bootstrap variants and a generic procedure for any Git server.

Check that Flux is running

You can tell whether the bootstrap worked in four places, namely the installation check of the CLI, the status of the source and the Kustomization, the pods in the flux-system namespace, and the new files in the GitLab project.

$ flux check
$ flux get sources git
$ flux get kustomizations
$ kubectl -n flux-system get pods

How to recognize success:

• flux check checks the Kubernetes version, controllers, and CRDs and ends with all checks passed on success. For each controller, it lists the container image. According to the release notes, for Flux 2.9.6 these include source-controller and kustomize-controller in version v1.9.6 and helm-controller in v1.6.5.
• flux get sources git shows the GitRepository named flux-system, with True in the READY column.
• flux get kustomizations shows the Kustomization flux-system with READY set to True and SUSPENDED set to False. The MESSAGE column names the applied revision from the main branch.
• kubectl -n flux-system get pods lists the pods of the four controllers with status Running.
• The GitLab project contains the directory clusters/<cluster-name>/flux-system/. According to the Flux docs, it contains the files gotk-components.yaml, gotk-sync.yaml, and kustomization.yaml. Under Settings > Repository > Deploy tokens, you see the active deploy token.

How does Flux deploy an application from Git?

Flux deploys an application from Git by having a Flux Kustomization point to a directory in the repository, where the kustomize-controller builds, validates, and applies the manifests to the cluster at the configured interval.

The example is a small web server named gitops-demo in its own namespace. The manifests live under apps/gitops-demo/, and the Flux Kustomization that applies them lives under clusters/<cluster-name>/. The project then looks like this:

apps/
  gitops-demo/
    namespace.yaml
    deployment.yaml
clusters/
  <cluster-name>/
    flux-system/
    gitops-demo.yaml

First, clone the project using your usual Git access. For a project in your user account on gitlab.com:

$ git clone https://gitlab.com/<gitlab-user>/<project>.git
$ cd <project>
$ mkdir -p apps/gitops-demo

For a group or a self-managed instance, adjust the host and path in the URL.

Create the file apps/gitops-demo/namespace.yaml:

apiVersion: v1
kind: Namespace
metadata:
  name: gitops-demo

Create the file apps/gitops-demo/deployment.yaml. It starts two replicas of nginx:1.30.5:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: gitops-demo
  namespace: gitops-demo
  labels:
    app.kubernetes.io/name: gitops-demo
spec:
  replicas: 2
  selector:
    matchLabels:
      app.kubernetes.io/name: gitops-demo
  template:
    metadata:
      labels:
        app.kubernetes.io/name: gitops-demo
    spec:
      containers:
        - name: nginx
          image: nginx:1.30.5
          ports:
            - containerPort: 80

The namespace is a separate manifest in the same directory. This makes it part of the Kustomization, and Flux removes it together with the Deployment during cleanup. You don't need a kustomization.yaml in apps/gitops-demo/. If it's missing, the kustomize-controller generates one for all manifests in the directory. For this to work, every YAML file there must be a valid Kubernetes manifest.

Now create the Flux Kustomization in clusters/<cluster-name>/gitops-demo.yaml:

apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: gitops-demo
  namespace: flux-system
spec:
  interval: 10m
  sourceRef:
    kind: GitRepository
    name: flux-system
  path: ./apps/gitops-demo
  prune: true
  wait: true
  timeout: 2m

The fields according to the Kustomization specification (kustomize-controller v1.9.6):

The file intentionally contains no suspend field. More on that in the next section.

Why two levels: The Kustomization flux-system only reconciles the path clusters/<cluster-name>. It finds the new file gitops-demo.yaml there and creates the Kustomization gitops-demo in the cluster. That Kustomization then applies the manifests from apps/gitops-demo/.

Commit and push the three files:

$ git add apps/gitops-demo clusters/<cluster-name>/gitops-demo.yaml
$ git commit -m "add gitops-demo"
$ git push

Without further action, Flux picks up the commit as soon as the GitRepository has fetched it within its interval of one minute. To avoid waiting, trigger the reconciliation yourself. --with-source first fetches the new state from GitLab, and the command waits until the reconciliation is complete:

$ flux reconcile kustomization flux-system --with-source
$ flux get kustomizations --watch

With --watch, you follow the status continuously until you stop it with Ctrl+C. As soon as the Kustomization gitops-demo shows True in the READY column, check the Deployment:

$ kubectl -n gitops-demo get deployment gitops-demo

The READY column shows 2/2.

Roll out changes via Git and watch drift

From now on, you change the application only through Git, and Flux makes sure the cluster matches the state in the repository, even if someone intervenes directly with kubectl.

Change by commit

In apps/gitops-demo/deployment.yaml, change the replicas value from 2 to 3, commit and push the change, and trigger the reconciliation. Here, too, --with-source first fetches the new commit from the source flux-system:

$ git commit -am "gitops-demo: 3 replicas"
$ git push
$ flux reconcile kustomization gitops-demo --with-source
$ kubectl -n gitops-demo get deployment gitops-demo

The Deployment now shows 3/3.

Let Flux revert drift

Now change the Deployment directly in the cluster, bypassing Git:

$ kubectl -n gitops-demo scale deployment gitops-demo --replicas=1
$ kubectl -n gitops-demo get deployment gitops-demo

Shortly afterwards, only one replica is running. According to the Kustomization specification, Flux reverts changes made with kubectl to managed objects to the state in Git at the next reconciliation. That happens at the next run in the configured interval of ten minutes, or immediately if you trigger the reconciliation yourself:

$ flux reconcile kustomization gitops-demo
$ kubectl -n gitops-demo get deployment gitops-demo

The Deployment is back at three replicas.

Pause and resume reconciliation

Sometimes you want to deliberately try something out in the cluster without Flux reverting it right away. For that, you suspend the Kustomization:

$ flux suspend kustomization gitops-demo
$ flux get kustomizations
$ kubectl -n gitops-demo scale deployment gitops-demo --replicas=1

The SUSPENDED column now shows True for gitops-demo. As long as the Kustomization is suspended, Flux neither applies new commits nor corrects drift, so the single replica stays. Use resume to lift the suspension. The command triggers a reconciliation immediately and waits until it is complete:

$ flux resume kustomization gitops-demo
$ kubectl -n gitops-demo get deployment gitops-demo

The Deployment is back at the state from Git, so at three replicas.

That is why gitops-demo.yaml contains no suspend field: According to the Kustomization specification, a suspend: false set in Git would override a suspension made via the CLI at the next reconciliation, because the state declared in Git wins. If the field is absent, flux suspend stays in effect.

Troubleshooting

Most problems show up in three commands: flux get kustomizations, flux get sources git, and flux events. The following error patterns come from the Flux documentation and the source code of the CLI.

flux check --pre rejects the Kubernetes version

If the pre-check reports Kubernetes version … does not match >=1.33.0-0, the cluster is older than 1.33. This guide doesn't cover such clusters. Upgrade the cluster to a minor version from the table in the prerequisites first.

Bootstrap aborts with a token or permission error

Check the following in order:

• Scope: The PAT needs full read and write access to the API, so the api scope. A token that only has read_api or read_repository doesn't cover that.
• Expiration date: According to the GitLab docs, expired tokens can't be reactivated. Create a new one.
• Permissions: You must be Owner of the project or have admin permissions in the group.
• --personal: If the project is in your user account, the flag is required. If it's in a group, it must be omitted. Without --personal, the CLI looks for the owner as a group.
• Project name: If the CLI reports is an invalid project name for gitlab, the name contains invalid characters. According to the error message, letters, digits, emojis, _, ., hyphens, and spaces are allowed. The name must start with a letter, a digit, an emoji, or _.
• Both auth options set: --token-auth and --deploy-token-auth are mutually exclusive.

Kustomization doesn't become ready

If flux get kustomizations shows False in READY for gitops-demo, the events tell you why:

$ flux events --for Kustomization/gitops-demo
$ kubectl -n flux-system describe kustomization gitops-demo

flux events shows the events of the Kustomization in the flux-system namespace and those of its source. Common causes according to the Kustomization specification:

• Wrong path: The message contains kustomization path not found. Check path in gitops-demo.yaml against the directory in the repository, including upper and lower case.
• Build fails: A file under apps/gitops-demo/ isn't a valid Kubernetes manifest, for example because of an indentation error.
• Readiness check fails: With wait: true, Flux waits until the Deployment has rolled out. If the cluster can't pull the image, for example because outbound access to Docker Hub is missing, the check ends with an error after the timeout. kubectl -n gitops-demo get pods shows the cause.
• Namespace missing: If you set the targetNamespace field in the Kustomization instead of metadata.namespace, the namespace must exist beforehand or be included as a manifest in the same Kustomization. The kustomize-controller doesn't create it itself.

According to the specification, Flux keeps retrying the reconciliation after an error, at increasing intervals, until it succeeds. After a fix in Git, trigger it immediately with flux reconcile kustomization gitops-demo --with-source.

The flux-system source isn't ready

If flux get sources git shows False in READY for flux-system, Flux can't read the project. Check whether the cluster can reach your GitLab instance over HTTPS and whether the deploy token is still active under Settings > Repository > Deploy tokens. flux events --for GitRepository/flux-system provides details.

Remove Flux and the example

Remove the sample application through Git first and only then Flux itself, because flux uninstall leaves objects that Flux applied in the cluster.

Remove the sample application through Git

Delete the manifests and the Kustomization from the repository:

$ git rm -r apps/gitops-demo clusters/<cluster-name>/gitops-demo.yaml
$ git commit -m "remove gitops-demo"
$ git push
$ flux reconcile kustomization flux-system --with-source

Because the file gitops-demo.yaml has disappeared from the reconciled path, Flux deletes the Kustomization gitops-demo. Since it works with prune: true, Flux removes all objects it applied in the process, that is, the Deployment and the namespace. This happens in the background and can take a moment. Check the result:

$ flux get kustomizations
$ kubectl get namespace gitops-demo

The Kustomization gitops-demo no longer appears, and kubectl reports that the namespace was not found.

Uninstall Flux

With --dry-run, you first see which objects would be deleted. Then uninstall Flux:

$ flux uninstall --dry-run
$ flux uninstall
$ kubectl get namespace flux-system

Without --silent, the command asks for confirmation first. The last command checks the result: kubectl reports that the namespace flux-system was not found. If it's still Terminating, wait a moment and repeat the command.

According to the Flux docs, flux uninstall deletes the controllers and their services, the network policies of Flux, the RBAC objects, the finalizers of the Flux resources, the CRDs with all custom resources, and the flux-system namespace. Don't uninstall Flux by deleting the Deployments and the namespace with kubectl. The Flux project doesn't support that.

Revoke access in GitLab

1. Deploy token: In the project, under Settings > Repository > Deploy tokens, in the Active Deploy Tokens area, select Revoke next to the token. This requires the Maintainer or Owner role in the project.
2. PAT: Avatar > Edit profile > Access > Personal access tokens, then next to the token choose Revoke from the three-dot menu and confirm. According to the GitLab docs, a revoked token is invalid immediately.

What remains

• The GitLab project with the directory clusters/<cluster-name>/flux-system/ and the entire commit history. Delete it in GitLab if you no longer need it, or keep it for a later bootstrap.
• Objects in the cluster that Flux applied and that you didn't remove through Git beforehand. flux uninstall leaves them untouched.
• The Flux CLI under /usr/local/bin/flux and your local clone of the project. If needed, remove the CLI with sudo rm /usr/local/bin/flux.
• The tokens, as long as you haven't revoked them as described above. The PAT expires on its expiration date; a deploy token without an expiration date doesn't.

Next steps

• Images from the pipeline: To produce new versions of your application, a CI pipeline builds the images. The foundation for this is described in Install GitLab Runner on Kubernetes. You then enter the new image tag in deployment.yaml with a commit, and Flux rolls it out.
• Secrets: According to the Kustomization specification, credentials don't belong in a Git repository, neither in plain text nor base64-encoded. For this, Flux decrypts Secrets that are encrypted with SOPS. How Secrets work in the cluster in general is shown in Create and use Kubernetes Secrets.
• Alternative: If your team prefers a built-in web interface for deployments, take a look at Install and secure Argo CD on Kubernetes.
• Basics: Terms like namespace, Deployment, and controller are explained in the glossary entry Kubernetes.

Beyond that, Flux can roll out Helm charts via HelmRelease, send notifications, and use image automation to write new image tags to Git itself. For the latter, Flux needs write access to the repository; the read-only deploy token from this guide isn't enough for that.