Tutorial: Set up Flux for GitOps

This tutorial teaches you how to set up Flux for GitOps. You’ll complete a bootstrap installation, install agentk in your cluster, and deploy a simple nginx application.

For an overview of an example Flux configuration, see Flux bootstrap and manifest synchronization with GitLab.

To set up Flux for GitOps:

  1. Create a personal access token
  2. Complete a bootstrap installation
  3. Register agentk
  4. Install agentk
  5. Deploy an example project

Prerequisites:

  • You must have a Kubernetes cluster you can access locally with kubectl.
  • You must install the Flux CLI. Be sure to install Flux v2 or higher.

Create a personal access token

To authenticate with the Flux CLI, create a personal access token with the api scope:

  1. On the left sidebar, select your avatar.
  2. Select Edit profile.
  3. On the left sidebar, select Access Tokens.
  4. Enter a name and optional expiry date for the token.
  5. Select the api scope.
  6. Select Create personal access token.

You can also use a project or group access token with the api scope.

Complete a bootstrap installation

In this section, you’ll bootstrap Flux into an empty GitLab repository with the flux bootstrap command.

To bootstrap a Flux installation:

  • Run the flux bootstrap gitlab command. For example:

    flux bootstrap gitlab \
--owner=example-org \
--repository=my-repository \
--branch=master \
--path=clusters/testing \
--deploy-token-auth

The bootstrap script does the following:

  1. Creates a deploy token and saves it as a Kubernetes secret.
  2. Creates an empty GitLab project, if the project specified by --repository doesn’t exist.
  3. Generates Flux definition files for your project.
  4. Commits the definition files to the specified branch.
  5. Applies the definition files to your cluster.

After you run the script, Flux will be ready to manage itself and any other resources you add to the GitLab project and path.

The rest of this tutorial assumes your path is clusters/testing.

Upgrade Flux

You might need to upgrade Flux some time after you install it. To do so:

  • Rerun the flux bootstrap gitlab command.

Register agentk

You must register agentk before you install it in your cluster.

To register agentk:

  1. On the left sidebar, select Search or go to and find your project. If you have an agent configuration file, it must be in this project. Your cluster manifest files should also be in this project.
  2. Select Operate > Kubernetes clusters.
  3. Select Connect a cluster (agent).
    • If you want to create a configuration with CI/CD defaults, type a name.
    • If you already have an agent configuration file, select it from the list.
  4. Select Register an agent.
  5. Securely store the agent access token and kasAddress for later.

The agent is registered for your project. You don’t need to run any commands yet.

In the next step, you’ll use Flux to install agentk in your cluster.

Install agentk

Next, use Flux to create a namespace for agentk and install it in your cluster.

This tutorial uses the namespace gitlab for agentk.

To install agentk:

  1. Commit and push the following file to clusters/testing/namespace-gitlab.yaml:

    apiVersion: v1
kind: Namespace
metadata:
  name: gitlab

  2. Create a file called secret.yaml that contains your agent access token as a secret:

    apiVersion: v1
kind: Secret
metadata:
  name: gitlab-agent-token
type: Opaque
stringData:
   token: "<your-token-here>"

  3. Apply secret.yaml to your cluster:

    kubectl apply -f secret.yaml -n gitlab

    Although this step does not follow GitOps principles, it simplifies configuration for new Flux users. For a proper GitOps setup, you should use a secret management solution. See the Flux documentation.

  4. Commit and push the following file to clusters/testing/agentk.yaml, replacing the values of .spec.values.config.kasAddress and .spec.values.config.secretName with your saved kas address and secret name:

    ---
apiVersion: source.toolkit.fluxcd.io/v1beta2
kind: HelmRepository
metadata:
  labels:
    app.kubernetes.io/component: agentk
    app.kubernetes.io/created-by: gitlab
    app.kubernetes.io/name: agentk
    app.kubernetes.io/part-of: gitlab
  name: gitlab-agent
  namespace: gitlab
spec:
  interval: 1h0m0s
  url: https://charts.gitlab.io
---
apiVersion: helm.toolkit.fluxcd.io/v2beta1
kind: HelmRelease
metadata:
  name: gitlab-agent
  namespace: gitlab
spec:
  chart:
    spec:
      chart: gitlab-agent
      sourceRef:
        kind: HelmRepository
        name: gitlab-agent
        namespace: gitlab
  interval: 1h0m0s
  values:
    config:
      kasAddress: "wss://kas.gitlab.com"  
      secretName: gitlab-agent-token

    The Helm release uses the secret from the previous step.

  5. To verify that agentk is installed and running in the cluster, run the following command:

    kubectl -n gitlab get pods

Great work! You’ve successfully set up Flux with agentk. You can repeat the steps from this section to deploy more applications from this project. In the next section, we’ll discuss how to scale Flux across projects.

Deploy an example project

You can scale Flux deployments across multiple GitLab projects by adding a Flux GitRepository and Kustomization that points to another project. You can use this feature to store manifests related to a particular GitLab group in that group.

To demonstrate, deploy an nginx application and point Flux at it:

  1. Commit and push the following file to clusters/testing/example-nginx-app.yaml:

    ---
apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
  name: example-nginx-app
  namespace: flux-system
spec:
  interval: 1m0s
  ref:
    branch: main
  url: https://gitlab.com/gitlab-examples/ops/gitops-demo/example-mini-flux-deployment.git
---
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: example-nginx-app
  namespace: flux-system
spec:
  interval: 10m0s
  path: ./manifests
  prune: true
  sourceRef:
    kind: GitRepository
    name: example-nginx-app

  2. To verify that the application was deployed correctly and agentk is running, run the following command:

    kubectl -n example-nginx get pods

This tutorial deploys an application from a public project. If you want to add a non-public project, you should create a project deploy token and save it as a Flux secret. Be sure to save the namespace and secret name.

Congratulations! You have successfully scaled Flux to multiple groups and projects.