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 deploy 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 for GitOps:

  1. Create a personal access token
  2. Create the Flux repository
  3. Create the Kubernetes manifest repository
  4. Configure Flux to sync your manifests
  5. Verify your configuration

Prerequisites:

  • You must have a Kubernetes cluster running.

Create a personal access token

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

  1. In the upper-right corner, 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.

Create the Flux repository

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. You must install Flux v2 or higher.
  3. In GitLab, create a new empty project called flux-config.
  4. From your shell, export a GITLAB_TOKEN environment variable with the value of your personal access token. For example, export GITLAB_TOKEN=<personal-access-token>.

  5. 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
  --deploy-token-auth

    This command installs Flux on the Kubernetes cluster and configures it to manage itself from the repository flux-config. The command also automatically creates the project deploy token required to access the flux-config repository.

Great work! You now have a repository bootstrapped with a Flux configuration. Any updates to your repository 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.