Tutorial: Set up Flux for GitOps

This tutorial teaches you how to set up Flux for GitOps. You’ll set up a sample project, complete a bootstrap Flux installation, and authenticate your installation with a project access token.

You can find the fully configured tutorial project in this GitLab repository. It works in conjunction with this repository, which contains the example Kubernetes manifests.

To set up Flux with a project access token:

  1. Create the Flux repository
  2. Create the Kubernetes manifest repository
  3. Configure Flux to sync your manifests
  4. Verify your configuration

Prerequisites:

  • On GitLab SaaS, you must have the Premium or Ultimate tier to use a project access token. On self-managed instances, you can have any tier.
  • Not recommended. You can authenticate with a personal or group access token in all tiers.
  • You must have a Kubernetes cluster running.

Create the Flux repository

To start, create a Git repository, install Flux, and authenticate Flux with your repo:

  1. Make sure your kubectl is configured to access your cluster.
  2. Install the Flux CLI.
  3. In GitLab, create a new empty project called flux-config.

  4. In the flux-config project, create a project access token with the following settings:

    • From the Select a role dropdown list, select Maintainer.
    • Under Select scopes, select the API and write_repository checkboxes.

    Name the project token flux-project-access-token.

  5. From your shell, export a GITLAB_TOKEN environment variable with the value of your project access token. For example, export GITLAB_TOKEN=<flux-project-access-token>.

  6. Run the bootstrap command. The exact command depends on whether you are creating the Flux repository under a GitLab user, group, or subgroup. For more information, see the Flux bootstrap documentation.

    In this tutorial, you’re working with a public project in a subgroup. The bootstrap command looks like this: 

    flux bootstrap gitlab \
  --owner=gitlab-org/configure/examples/flux \
  --repository=flux-config \
  --branch=main \
  --path=clusters/my-cluster

    This command installs Flux on the Kubernetes cluster and configures it to manage itself from the repository flux-config.

Great work! You now have a repository, a project access token, and a Flux bootstrap installation authenticated to your repo. Any updates to your repo are automatically synced to the cluster.

Create the Kubernetes manifest repository

Next, create a repository for your Kubernetes manifests:

  1. In GitLab, create a new repository called web-app-manifests.

  2. Add a file to web-app-manifests named nginx-deployment.yaml with the following contents: 

    apiVersion: apps/v1

kind: Deployment

metadata:
  name: nginx-deployment
  labels:
    app: nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.14.2
        ports:
        - containerPort: 80
  3. In the new repository, create a deploy token with only the read_repository scope.
  4. Store your deploy token username and password somewhere safe.

  5. In Flux CLI, create a secret with your deploy token and point the secret to the new repository. For example: 

    flux create secret git flux-deploy-authentication \
         --url=https://gitlab.com/gitlab-org/configure/examples/flux/web-app-manifests \
         --namespace=default \
         --username=<token-user-name> \
         --password=<token-password>

  6. To check if your secret was generated successfully, run: 

    kubectl -n default get secrets flux-deploy-authentication -o yaml

    Under data, you should see base64-encoded values associated with your token username and password.

Congratulations! You now have a manifest repository, a deploy token, and a secret generated directly on your cluster.

Configure Flux to sync your manifests

Next, tell flux-config to sync with the web-app-manifests repository.

To do so, create a GitRepository resource:

  1. Clone the flux-config repo to your machine.

  2. In your local clone of flux-config, add the GitRepository file clusters/my-cluster/web-app-manifests-source.yaml: 

    ---
apiVersion: source.toolkit.fluxcd.io/v1beta2
kind: GitRepository
metadata:
  name: web-app-manifests
  namespace: default
spec:
  interval: 1m0s
  ref:
    branch: main
  secretRef:
    name: flux-deploy-authentication
  url: https://gitlab.com/gitlab-org/configure/examples/flux/web-app-manifests

    This file uses secretRef to refer back to the deploy token secret you created in the last step.

  3. In your local clone of flux-config, add the GitRepository file clusters/my-cluster/web-app-manifests-kustomization.yaml: 

    ---
apiVersion: kustomize.toolkit.fluxcd.io/v1beta2
kind: Kustomization
metadata:
  name: nginx-source-kustomization
  namespace: default
spec:
  interval: 1m0s
  path: ./
  prune: true
  sourceRef:
    kind: GitRepository
    name: web-app-manifests
    namespace: default
  targetNamespace: default

    This file adds a Kustomization resource that tells Flux to sync the manifests from web-app-manifests with kustomize.

  4. Commit the new files and push.

Verify your configuration

You should see a newly created nginx-deployment pod in your cluster.

To check whether the nginx-deployment pod is running in the default namespace, run the following: 

kubectl -n default get pods -n default

If you want to see the deployment sync again, try updating the number of replicas in the nginx-deployment.yaml file and push to your main branch. If all is working well, it should sync to the cluster.

Excellent work! You’ve successfully set up a complete Flux project.