• Create a personal access token
• Complete a bootstrap installation
  • Upgrade Flux
• Register agentk
• Install agentk
• Deploy an example project

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 and the developer role.

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 \
  --hostname=gitlab.example.org \
  --owner=example-org \
  --repository=my-repository \
  --branch=master \
  --path=clusters/testing \
  --deploy-token-auth
  

The arguments of bootstrap are:

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 the --repository argument doesn’t exist.
3. Generates Flux definition files for your project in a folder specified by the --path argument.
4. Commits the definition files to the branch specified by the --branch argument.
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. Keep in mind it takes a few minutes for Flux to pick up and apply configuration changes defined in the repository.

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
     namespace: gitlab
   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.