Flux (Beta)
all tiers

Flux is a GitOps tool that helps you manage your Kubernetes clusters. You can use Flux to:

  • Keep your clusters in sync with your Git repositories.
  • Reconcile code changes with your deployments.
  • Manage your Flux installation itself with a bootstrap.

You can use the agent for Kubernetes with Flux to:

  • Trigger immediate Git repository reconciliation.

To get started, see the Flux installation documentation.

Support for Flux is in Beta.

Bootstrap installation

Use the Flux command bootstrap gitlab to configure a Kubernetes cluster to manage itself from a Git repository.

You must authenticate your installation with either:

Some Flux features like automated image updates require write access to the source repositories.

GitOps repository structure

You should organize your repositories to meet the needs of your team. For detailed recommendations, see the Flux repository structure documentation.

Immediate Git repository reconciliation

Introduced in GitLab 16.1.

Usually, the Flux source controller reconciles Git repositories at configured intervals. This can cause delays between a git push and the reconciliation of the cluster state, and results in unnecessary pulls from GitLab.

The agent for Kubernetes automatically detects Flux GitRepository objects that reference GitLab projects in the instance the agent is connected to, and configures a Receiver for the instance. When the agent for Kubernetes detects a git push, the Receiver is triggered and Flux reconciles the cluster with any changes to the repository.

To use immediate Git repository reconciliation, you must have a Kubernetes cluster that runs:

  • The agent for Kubernetes.
  • Flux source-controller and notification-controller.

Immediate Git repository reconciliation can reduce the time between a push and reconciliation, but it doesn’t guarantee that every git push event is received. You should still set GitRepository.spec.interval to an acceptable duration.

Custom webhook endpoints

When the agent for Kubernetes calls the Receiver webhook, the agent defaults to http://webhook-receiver.flux-system.svc.cluster.local, which is also the default URL set by a Flux bootstrap installation. To configure a custom endpoint, set flux.webhook_receiver_url to a URL that the agent can resolve. For example:

flux:
  webhook_receiver_url: http://webhook-receiver.another-flux-namespace.svc.cluster.local

There is special handing for service proxy URLs configured in this format: /api/v1/namespaces/[^/]+/services/[^/]+/proxy. For example:

flux:
  webhook_receiver_url: /api/v1/namespaces/flux-system/services/http:webhook-receiver:80/proxy

In these cases, the agent for Kubernetes uses the available Kubernetes configuration and context to connect to the API endpoint. You can use this if you run an agent outside a cluster and you haven’t configured an Ingress for the Flux notification controller.

caution
You should configure only trusted service proxy URLs. When you provide a service proxy URL, the agent for Kubernetes sends typical Kubernetes API requests which include the credentials necessary to authenticate with the API service.