Skip to content

Flux Bridge

This example demonstrates how to integrate ConfigHub with FluxCD using a custom bridge. With this integration, you can manage your Kubernetes configurations in ConfigHub while using Flux's GitOps reconciliation engine to apply them to your clusters.

Overview

What is a Bridge?

A Bridge is a piece of software that connects ConfigHub to live resources in Kubernetes, AWS, Azure, GCP, or other systems. Bridges translate ConfigHub operations (Apply, Destroy, Refresh, Import) into the appropriate API calls for the target platform. They run inside Workers, which handle all communication with ConfigHub.

ConfigHub provides a standard Worker with built-in bridges for common platforms like the Kubernetes API. However, you can also build custom bridges for specialized integrations—like this Flux Bridge.

Why use Flux with ConfigHub?

The standard ConfigHub worker applies configurations directly to the Kubernetes API. The Flux Bridge takes a different approach: instead of applying resources directly, it creates Flux ExternalArtifact resources that point to ConfigHub units. Flux then handles the actual reconciliation.

This approach gives you:

  • Flux's reconciliation model: Flux continuously reconciles the desired state, automatically correcting drift
  • ConfigHub's configuration management: Hierarchical config, clone upgrades, bulk operations, and change tracking
  • Unified tooling: Teams already using Flux can adopt ConfigHub without changing their deployment model

How it works

  1. You manage configuration in ConfigHub units as usual
  2. When you apply a unit, the Flux Bridge creates an ExternalArtifact resource pointing to the unit's configuration
  3. The Flux Bridge also creates a Kustomization resource that references the ExternalArtifact
  4. Flux's kustomize-controller fetches the configuration from the artifact and applies it to the cluster
  5. Flux continuously reconciles, ensuring the cluster matches the desired state
graph LR
    ConfigHub -->|manages| Unit
    Unit -->|apply via| FluxBridge[Flux Bridge]
    FluxBridge -->|creates| EA[ExternalArtifact]
    FluxBridge -->|creates| Kustomization
    Kustomization -->|references| EA
    EA -->|points to| Unit
    Flux[Flux Controller] -->|fetches from| EA
    Flux -->|reconciles| Cluster

Setup

Before you begin

Make sure you have completed the prerequisites. This example does not require cloning the examples repo—the Flux Bridge configuration is hosted in its own repository.

For these instructions we will use a local Kind cluster. You can easily adapt them to a cluster of your own.

Create a cluster

kind create cluster --name flux-bridge-dev

Install Flux

Install Flux v2.7.0 or greater:

flux install

Enable the ExternalArtifact feature

The ExternalArtifact source controller is behind a feature flag, so we need to enable it:

kubectl -n flux-system patch deployment kustomize-controller \
    --type='json' \
    -p='[{"op": "add", "path": "/spec/template/spec/containers/0/args/-", "value": "--feature-gates=ExternalArtifact=true"}]'

Deploy the Flux Bridge configuration

Create the Flux Bridge custom worker config in ConfigHub from the base config in the repository:

cub unit create flux-bridge-config \
    https://raw.githubusercontent.com/confighub/flux-bridge/refs/heads/main/manifests/base.yaml

Then apply it to the cluster:

cub unit get flux-bridge-config --data-only | kubectl apply -f -

Managing ConfigHub infrastructure with ConfigHub

While you could apply the worker manifests directly to the cluster, storing them in ConfigHub gives you the same benefits you get for any other configuration: full revision history, easy rollback, the ability to clone and customize for different environments, and bulk operations across multiple clusters. It's ConfigHub all the way down.

Create the Worker entity

Create the Worker entity in ConfigHub:

cub worker create flux-bridge

Install the Worker secret

Apply the Custom Worker secret resource to the Kind cluster:

cub worker install flux-bridge --export-secret-only | kubectl apply -f -

The Flux Bridge worker config depends on this secret and will not reconcile until the secret is applied. Once applied, the Flux Bridge Worker should boot successfully and connect to ConfigHub.

Verify the connection

Verify that the worker has connected:

cub worker list

You should see output like:

NAME           CONDITION       SPACE          LAST-SEEN
flux-bridge    Ready           default        2025-10-31 20:37:53

Demo: Deploy a Helm chart via Flux Bridge

Now let's deploy something through the Flux Bridge to see it in action. We'll use the reloader Helm chart as an example.

Render the Helm chart into ConfigHub

cub helm install reloader stakater/reloader \
    --repo https://stakater.github.io/stakater-charts \
    --namespace reloader

Set the target to the Flux Bridge

cub unit update reloader --target flux-bridge

Apply the unit

cub unit apply reloader

Verify in ConfigHub

cub unit list reloader

Verify in Flux

kubectl get kustomizations -A

You should see a Kustomization created for the reloader unit, and Flux will reconcile it to the cluster.

Next steps