Flux Cluster Sync Configuration

The FluxInstance resource can be configured to instruct the operator to generate a Flux source (GitRepository, OCIRepository or Bucket) and a Flux Kustomization to sync the cluster state with the source repository.

The Flux objects are created in the same namespace where the FluxInstance is deployed using the namespace name as the Flux source and Kustomization name. The naming convention matches the one used by flux bootstrap to ensure compatibility with upstream, and to allow transitioning a bootstrapped cluster to a FluxInstance managed one.

Sync from a Git Repository

To sync the cluster state from a Git repository, add the .spec.sync configuration to the FluxInstance:

apiVersion: fluxcd.controlplane.io/v1
kind: FluxInstance
metadata:
  name: flux
  namespace: flux-system
spec:
  distribution:
    version: "2.8.x"
    registry: "ghcr.io/fluxcd"
  sync:
    kind: GitRepository
    url: "https://gitlab.com/my-org/my-fleet.git"
    ref: "refs/heads/main"
    path: "clusters/my-cluster"
    pullSecret: "flux-system"

If the source repository is private, the Kubernetes secret must be created in the flux-system namespace and should contain the credentials to clone the repository:

echo $GITLAB_TOKEN | flux-operator create secret basic-auth flux-system \
  --namespace=flux-system \
  --username=git \
  --password-stdin

Sync from a Git Repository using GitHub App auth

To sync the cluster state from a GitHub repository using GitHub App authentication:

apiVersion: fluxcd.controlplane.io/v1
kind: FluxInstance
metadata:
  name: flux
  namespace: flux-system
spec:
  distribution:
    version: "2.8.x"
    registry: "ghcr.io/fluxcd"
  sync:
    kind: GitRepository
    provider: github
    url: "https://github.com/my-org/my-fleet.git"
    ref: "refs/heads/main"
    path: "clusters/my-cluster"
    pullSecret: "flux-system"

The Kubernetes secret must be created in the flux-system namespace and should contain the GitHub App private key:

flux-operator create secret githubapp flux-system \
  --namespace=flux-system \
  --app-id=1 \
  --app-installation-owner=my-org \
  --app-private-key-file=./path/to/private-key-file.pem

Sync from an Azure DevOps Repository using AKS Workload Identity

To sync the cluster state from Azure DevOps using AKS Workload Identity:

apiVersion: fluxcd.controlplane.io/v1
kind: FluxInstance
metadata:
  name: flux
  namespace: flux-system
spec:
  distribution:
    version: "2.8.x"
    registry: "ghcr.io/fluxcd"
  sync:
    kind: GitRepository
    provider: azure
    url: "https://dev.azure.com/my-org/_git/my-fleet"
    ref: "refs/heads/main"
    path: "clusters/my-cluster"
  kustomize:
    patches:
    - patch: |-
        apiVersion: v1
        kind: ServiceAccount
        metadata:
          name: source-controller
          annotations:
            azure.workload.identity/client-id: <AZURE_CLIENT_ID>
            azure.workload.identity/tenant-id: <AZURE_TENANT_ID>
      target:
        kind: ServiceAccount
        name: source-controller
    - patch: |-
        apiVersion: apps/v1
        kind: Deployment
        metadata:
          name: source-controller
        spec:
          template:
            metadata:
              labels:
                azure.workload.identity/use: "true" 
      target:
        kind: Deployment
        name: source-controller

Sync from a Container Registry

To sync the cluster state from a container registry where the Kubernetes manifests are pushed as OCI artifacts using flux push artifact:

apiVersion: fluxcd.controlplane.io/v1
kind: FluxInstance
metadata:
  name: flux
  namespace: flux-system
spec:
  distribution:
    version: "2.8.x"
    registry: "ghcr.io/fluxcd"
  sync:
    kind: OCIRepository
    url: "oci://ghcr.io/my-org/my-fleet-manifests"
    ref: "latest"
    path: "clusters/my-cluster"
    pullSecret: "flux-system"

If the container registry is private, the Kubernetes secret must be created in the same namespace where the FluxInstance is deployed, and be of type kubernetes.io/dockerconfigjson:

echo $GITHUB_TOKEN | flux-operator create secret registry flux-system \
  --namespace=flux-system \
  --server=ghcr.io \
  --username=flux \
  --password-stdin

Sync from a Container Registry using Workload Identity

To sync the cluster state from a managed container registry, for example, AWS ECR:

apiVersion: fluxcd.controlplane.io/v1
kind: FluxInstance
metadata:
  name: flux
  namespace: flux-system
spec:
  distribution:
    version: "2.8.x"
    registry: "ghcr.io/fluxcd"
  sync:
    kind: OCIRepository
    provider: aws
    url: "oci://<account>.dkr.ecr.<region>.amazonaws.com/fleet-manifests"
    ref: "latest"
    path: "clusters/my-cluster"

Note that you need to create an EKS Pod Identity association for the source-controller Service Account to allow it to pull images from the ECR repository.

The supported cloud providers are:

• aws for Amazon Elastic Container Registry (ECR)
• azure for Azure Container Registry (ACR)
• gcp for Google Artifact Registry (GAR)

Sync from a Container Registry using mTLS

To sync the cluster state from a container registry that requires mutual TLS authentication, reference the certificate secret with:

apiVersion: fluxcd.controlplane.io/v1
kind: FluxInstance
metadata:
  name: flux
  namespace: flux-system
spec:
  distribution:
    version: "2.8.x"
    registry: "ghcr.io/fluxcd"
  sync:
    kind: OCIRepository
    url: "oci://registry.my-org.com/my-fleet-manifests"
    ref: "latest"
    path: "clusters/my-cluster"
  kustomize:
    patches:
      - patch: |
          - op: add
            path: /spec/certSecretRef
            value: registry-tls
        target:
          kind: OCIRepository

The Kubernetes secret must be created in the flux-system namespace and should contain the client certificate, private key, and CA certificate:

flux-operator -n flux-system create secret tls registry-tls \
  --tls-crt-file=./tls.crt \
  --tls-key-file=./tls.key \
  --ca-crt-file=./ca.crt

Sync from a Bucket

To sync the cluster state from an S3 bucket where the Kubernetes manifests are stored as YAML files:

apiVersion: fluxcd.controlplane.io/v1
kind: FluxInstance
metadata:
  name: flux
  namespace: flux-system
spec:
  distribution:
    version: "2.8.x"
    registry: "ghcr.io/fluxcd"
  sync:
    kind: Bucket
    url: "minio.my-org.com"
    ref: "my-bucket-fleet"
    path: "clusters/my-cluster"
    pullSecret: "bucket-auth"

The Kubernetes secret must be created in the same namespace where the FluxInstance is deployed, with the following keys:

kubectl create secret generic bucket-auth \
  --namespace flux-system \
  --from-literal=accesskey=my-accesskey \
  --from-literal=secretkey=my-secretkey

To find out more about the available configuration options, refer to the FluxInstance API reference.