Sync OCI Artifacts into Kubernetes with Flux OCIRepository (2026)

Flux’s OCIRepository source controller lets you pull OCI (Open Container Initiative) artifacts, like Helm charts or container images, directly into your Kubernetes cluster.

Here’s how it works:

Imagine you have a Helm chart for your application stored in Oracle Cloud Infrastructure (OCI) Registry. Instead of manually pulling it and then applying it to your cluster, or using a separate CI/CD pipeline to push it to a different registry, Flux can directly watch that OCI repository. When you push a new version of your chart to OCI, Flux detects the change and automatically updates your Kubernetes deployment.

Let’s walk through a practical example.

First, you need to have Flux installed and running in your cluster. You’ll also need a Kubernetes secret that contains your OCI registry credentials.

apiVersion: v1
kind: Secret
metadata:
  name: oci-registry-credentials
  namespace: flux-system
type: kubernetes.io/dockerconfigjson
data:
  .dockerconfigjson: <base64-encoded-json-with-your-oci-credentials>

The .dockerconfigjson field should contain a JSON object like this, base64 encoded:

{
  "auths": {
    "oci.example.com": {
      "username": "your-oci-username",
      "password": "your-oci-password-or-token",
      "auth": "<base64-encoded-username:password>"
    }
  }
}

Now, you can define your OCIRepository custom resource. This tells Flux where to look for your OCI artifact.

apiVersion: source.toolkit.fluxcd.io/v1beta2
kind: OCIRepository
metadata:
  name: my-helm-chart
  namespace: flux-system
spec:
  interval: 5m
  url: oci://oci.example.com/my-repo/my-chart
  ref:
    semver: ">=1.0.0 <2.0.0" # Or specify a tag like "v1.2.3" or branch like "main"
  secretRef:
    name: oci-registry-credentials
  # For Helm charts, you'd typically use this to point to the chart archive
  # For container images, you'd omit this and use artifact.path

In this example:

interval: 5m means Flux will check for updates every 5 minutes.
url is the OCI registry path to your artifact.
ref specifies which version you’re interested in. Here, we’re using a semantic versioning range. You could also use tag: "v1.2.3" or branch: "main".
secretRef points to the Kubernetes secret containing your registry credentials.

Once Flux reconciles this OCIRepository, it will fetch the specified artifact. For Helm charts, this artifact will be made available for a HelmRelease resource to consume.

apiVersion: helm.toolkit.fluxcd.io/v1
kind: HelmRelease
metadata:
  name: my-app
  namespace: default
spec:
  interval: 10m
  chart:
    spec:
      chart: my-chart
      version: "1.2.3" # This should match a version found by the OCIRepository
      sourceRef:
        kind: OCIRepository
        name: my-helm-chart
        namespace: flux-system
  values:
    replicaCount: 3
    image:
      repository: oci.example.com/my-repo/my-app
      tag: "latest" # Flux can also manage container image tags

When you push a new Helm chart version (e.g., 1.2.4) to oci://oci.example.com/my-repo/my-chart that matches the semver constraint in your OCIRepository, Flux will detect it, download the new chart, and then the HelmRelease will pick it up and update your application.

The most surprising part is how seamlessly Flux can manage not just container images, but also other OCI-compliant artifacts like Helm charts, treating them with the same declarative, GitOps-driven approach. This means your entire application delivery pipeline, from build artifacts to deployment manifests, can be managed from a single source of truth, whether that’s a Git repository or an OCI registry.

Flux’s OCIRepository can also fetch container images directly. In this case, you wouldn’t typically specify a chart or version in the HelmRelease’s chart spec. Instead, you’d use the artifact.path within the OCIRepository to point to the image.

apiVersion: source.toolkit.fluxcd.io/v1beta2
kind: OCIRepository
metadata:
  name: my-app-image
  namespace: flux-system
spec:
  interval: 5m
  url: oci://oci.example.com/my-repo/my-app-image
  ref:
    tag: "v1.0.0" # Or semver, branch, etc.
  secretRef:
    name: oci-registry-credentials
  # For container images, you might specify the artifact path if needed
  # artifact:
  #   path: "oci.example.com/my-repo/my-app-image" # Often inferred from URL

Then, in your Deployment or StatefulSet, you’d reference this image, and Flux’s Image Automation Controller can be configured to update the ref.tag in your OCIRepository based on new image tags found in the registry.

The internal mechanism for OCIRepository involves Flux’s source controller pulling the OCI artifact and storing it in a cache within the cluster (often on persistent storage attached to the controller pod). This cached artifact is then made available to other Flux controllers (like Helm controller or Kustomize controller) via a Kubernetes Artifact object. This allows for efficient distribution and consumption of artifacts without needing to re-download them for every dependent resource.

The next step is often integrating this with Flux’s Image Update Automation to automatically update image tags or chart versions based on registry changes.