How do Flux Bucket and OCI sources work for non-Git artifact delivery?

Think of Flux sources like different mail delivery services for your Kubernetes manifests. GitRepository is like traditional mail — you go to the post office (Git server) and pick up your letters (manifests) from your mailbox (repository). Bucket sources are like a package locker system — manifests are stored as objects in a cloud storage bucket (S3, GCS, MinIO), and Flux checks the locker periodically for new packages. OCI sources are like receiving manifests via the same delivery network used for container images — your manifests are packaged as OCI artifacts and pushed to a container registry, and Flux pulls them just like it would pull a Docker image. Each delivery method has different strengths: Git excels for collaborative development, Buckets work well for CI pipeline artifacts and air-gapped environments, and OCI leverages existing container registry infrastructure for manifest distribution.

The Bucket source type tells the Flux source-controller to fetch manifests from an S3-compatible object storage endpoint. You configure the bucket name, endpoint URL, region, and optional credentials via a secretRef. The source-controller periodically lists objects in the bucket, computes a checksum of the contents, and downloads the artifacts when changes are detected. Bucket sources support S3-compatible APIs, which means they work with AWS S3, Google Cloud Storage (using the S3 compatibility layer), Azure Blob Storage (via S3-compatible gateway), MinIO, and any other S3-compatible storage system. The insecure field can be set to true for non-TLS endpoints in development environments. A key use case for Bucket sources is air-gapped environments where the Kubernetes cluster cannot access external Git repositories — instead, an external CI pipeline pushes manifests to an internal MinIO bucket, and Flux picks them up from there.

The OCIRepository source type enables Flux to pull manifests packaged as OCI (Open Container Initiative) artifacts from container registries. OCI artifacts are a standardized way to store arbitrary content in container registries alongside container images. You use the Flux CLI command flux push artifact to package a directory of manifests into an OCI artifact and push it to a registry with a specific tag. The OCIRepository resource specifies the registry URL, tag or semver range, and optional authentication credentials. The source-controller pulls the artifact, extracts the manifests, and makes them available to downstream Kustomizations or HelmReleases. OCI sources support semver-based tag selection, digest pinning for immutable references, and tag pattern filtering — similar to how ImagePolicy works for container images. This makes OCI artifacts particularly powerful for versioned manifest distribution where you want to treat your infrastructure configuration with the same rigor as your container images.

In production environments, teams choose between Bucket and OCI sources based on their infrastructure and workflow. Organizations with existing artifact management systems often prefer OCI because it reuses their container registry infrastructure (ECR, GCR, ACR, Harbor) and existing authentication mechanisms (IAM roles, service accounts). The CI pipeline builds the application, pushes the container image, and then pushes the corresponding manifests as an OCI artifact to the same registry. The shipping-service team, for example, might push their manifests to acme-corp.azurecr.io/manifests/shipping-service:v2.3.0 alongside the application image at acme-corp.azurecr.io/shipping-service:v2.3.0. Flux then pulls both — the OCI manifest artifact through the OCIRepository source and the container image through the normal Deployment spec. Bucket sources are more common in environments with strict network policies, regulated industries requiring artifact scanning before deployment, or legacy CI systems that output to S3 but cannot push OCI artifacts.

A critical gotcha with Bucket sources is that the source-controller downloads the entire bucket contents (or the filtered subset) on every reconciliation interval, which can be bandwidth-intensive for large artifact sets. Unlike Git, which efficiently computes diffs, S3 does not support delta transfers, so the controller must re-download everything to detect changes. Configuring a tight prefix filter to limit the scope of objects scanned is essential for performance. For OCI sources, a common pitfall is authentication configuration — different registries require different credential formats, and cloud-provider registries like ECR use short-lived tokens that must be refreshed. Flux supports automatic token refresh for AWS ECR, GCP GCR, and Azure ACR through the provider field on the OCIRepository, but misconfiguring this leads to intermittent authentication failures as tokens expire. Another important consideration is that OCI artifacts pushed by flux push artifact use a specific media type that Flux understands — pushing arbitrary OCI artifacts created by other tools like ORAS may not be compatible unless they follow the same media type conventions.