Source Controller OCI Repository

In this guide, we’ll show you how to use the Flux Source Controller to fetch resources from an OCI artifacts repository. This approach works with any compliant OCI registry—such as GitHub Container Registry (GHCR), Docker Hub, or cloud‐hosted registries—by leveraging the OCI Artifacts API.

Prerequisites

• A running Kubernetes cluster with Flux installed in the flux-system namespace
• An OCI registry account (e.g., GitHub Container Registry)
• A personal access token (PAT) or registry credentials with pull permissions

1. Create the OCI Secret

First, store your registry credentials in a Flux Secret of type OCI. This will allow Flux to authenticate when fetching artifacts.

flux create secret oci ghcr-auth \
  --url ghcr.io \
  --username sidd-harth \
  --password <<GitHub-Personal-Access-Token>>
# oci secret 'ghcr-auth' created in 'flux-system' namespace

2. Register the OCI Repository as a Source

Point Flux to your OCI‐hosted image or artifact by creating an OCIRepository source.

flux create source oci nginx \
  --url oci://ghcr.io/sidd-harth/nginx \
  --tag 1.0.0 \
  --secret-ref ghcr-auth \
  --provider generic
# applying OCIRepository
# OCIRepository updated
# waiting for OCIRepository reconciliation
# OCIRepository reconciliation completed
# fetched revision: 1b31558/235b486df4a38f99336712

3. Apply Manifests with Kustomization

Once the OCIRepository is ready, deploy its manifests into your cluster via a Kustomization.

flux create kustomization kust-nginx-oci \
  --source OCIRepository/nginx \
  --target-namespace default \
  --interval 10s \
  --prune=false \
  --health-check="Deployment/nginx.default"
# generating Kustomization
# applying Kustomization
# Kustomization updated
# waiting for Kustomization reconciliation
# Kustomization kust-nginx-oci is ready
# applied revision 1b31558/235b486df4a38f99336712

4. Fetching OCI-Hosted Helm Charts

Flux’s Kustomize Controller cannot process Helm charts directly. To deploy charts stored in an OCI registry, register the same registry as a Helm source.

4.1 Register the Helm Repository

flux create source helm chart-oci \
  --url oci://ghcr.io/sidd-harth/chart \
  --secret-ref ghcr-auth
# generating HelmRepository source
# applying HelmRepository source
# HelmRepository source updated
# waiting for HelmRepository source reconciliation
# HelmRepository source reconciliation completed

4.2 Deploy the Helm Chart

Create a HelmRelease to instruct Flux’s Helm Controller to fetch and install the chart.

flux create helmrelease chart-oci-release \
  --source HelmRepository/chart-oci \
  --target-namespace nginx \
  --chart nginx \
  --chart-version 0.1.0
# generating HelmRelease
# applying HelmRelease
# HelmRelease chart-oci-release created
# waiting for HelmRelease reconciliation
# HelmRelease chart-oci-release is ready
# applied revision 0.1.0

This will trigger the Helm Controller to pull chart artifacts from your OCI registry and perform automated releases.

Comparison of OCI vs. Helm Sources

Links and References

• Flux CD Documentation
• OCI Artifacts Specification
• Kustomize Controller
• Helm Controller
• GitHub Container Registry