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.

Do not commit your <GitHub-Personal-Access-Token> or any credentials into your Git repository. Treat them as sensitive data.

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

Set --prune=false if you want to retain orphaned resources. Adjust --interval to control reconciliation frequency.

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

Resource Type	Controller	Use Case
OCIRepository	Source Controller	Static YAML, images, configs
Kustomization	Kustomize Controller	Apply kustomized manifests
HelmRepository	Source Controller	OCI-packaged Helm charts
HelmRelease	Helm Controller	Automated Helm chart deployment

GitOps Overview

Flux Overview

Source and Kustomize Controller

Helm Controller and OCI Registry

Image Automation Controller

Secret Management & Sign Verification

Notification Controller

Monitoring & User Interface

Source Controller OCI Repository

Prerequisites

1. Create the OCI Secret

2. Register the OCI Repository as a Source

3. Apply Manifests with Kustomization

4. Fetching OCI-Hosted Helm Charts

4.1 Register the Helm Repository

4.2 Deploy the Helm Chart

Comparison of OCI vs. Helm Sources

Links and References

Watch Video

​Prerequisites

​1. Create the OCI Secret

​2. Register the OCI Repository as a Source

​3. Apply Manifests with Kustomization

​4. Fetching OCI-Hosted Helm Charts

​4.1 Register the Helm Repository

​4.2 Deploy the Helm Chart

​Comparison of OCI vs. Helm Sources

​Links and References

Watch Video

Prerequisites

1. Create the OCI Secret

2. Register the OCI Repository as a Source

3. Apply Manifests with Kustomization

4. Fetching OCI-Hosted Helm Charts

4.1 Register the Helm Repository

4.2 Deploy the Helm Chart

Comparison of OCI vs. Helm Sources

Links and References