stackitcloud · craigvanaman · Nov 10, 2025 · Nov 11, 2025 · Nov 13, 2025 · Nov 13, 2025
diff --git a/README.md b/README.md
@@ -28,10 +28,14 @@ Please find more information regarding the extensibility concepts and a detailed
 <!-- markdown-toc end -->
 
 # What does this package provide?
-The general idea of this controller is to install the [fluxcd](https://fluxcd.io/) controllers together with a [flux gitrepository resource](https://fluxcd.io/docs/components/source/gitrepositories/) and a [flux kustomization resource](https://fluxcd.io/docs/components/kustomize/kustomization/) into newly created shoot clusters.
-In consequence, your fresh shoot cluster will be reconciled to the state defined in the Git repository by the fluxcd controllers.
+The general idea of this controller is to install the [fluxcd](https://fluxcd.io/) controllers together with a flux source resource ([GitRepository](https://fluxcd.io/docs/components/source/gitrepositories/) or [OCIRepository](https://fluxcd.io/flux/components/source/ocirepositories/)) and a [flux kustomization resource](https://fluxcd.io/docs/components/kustomize/kustomization/) into newly created shoot clusters.
+In consequence, your fresh shoot cluster will be reconciled to the state defined in the source repository (Git or OCI) by the fluxcd controllers.
 Thus, this extension provides a general approach to install addons to shoot clusters.
 
+**Source Types**:
+- **Git Repository**: Use traditional Git repositories (GitHub, GitLab, etc.) to store your Kubernetes manifests
+- **OCI Repository**: Use OCI-compliant container registries (ghcr.io, Docker Hub, etc.) to store pre-built manifests as OCI artifacts. This is particularly useful when using code generators like CUE, Jsonnet, or KCL in CI pipelines.
+
 ## Example use case
 Let's say you have a CI-workflow which needs a kubernetes cluster with some basic components, such as [cert-manager](https://cert-manager.io/) or [minio](https://min.io/).
 Thus, your CI-workflow creates a `Shoot` on which you perform all your actions.
@@ -58,6 +62,65 @@ Like the other resources (flux installation) provisioned by this configMap is no
 from the shoot cluster. This behaviour is intentional to keep the flux installation intact and allow the user to remove
 it in a controlled manner. Please be aware that the `configMap` is no longer updated when the extension is no longer active.
 
+## Source Configuration Format Migration
+
+**IMPORTANT:** The source configuration format has changed to support both Git and OCI repositories.
+
+### Old Format (Deprecated, but still supported)
+
+```yaml
+source:
+  template:
+    apiVersion: source.toolkit.fluxcd.io/v1
+    kind: GitRepository
+    spec:
+      url: https://github.com/example/repo
+      ref:
+        branch: main
+  secretResourceName: my-git-credentials
+```
+
+### New Format (Recommended)
+
+For **Git repositories**:
+```yaml
+source:
+  gitRepository:
+    template:
+      apiVersion: source.toolkit.fluxcd.io/v1
+      kind: GitRepository
+      spec:
+        url: https://github.com/example/repo
+        ref:
+          branch: main
+    secretResourceName: my-git-credentials
+```
+
+For **OCI repositories**:
+```yaml
+source:
+  ociRepository:
+    template:
+      apiVersion: source.toolkit.fluxcd.io/v1beta2
+      kind: OCIRepository
+      spec:
+        url: oci://ghcr.io/example/manifests
+        ref:
+          tag: latest
+    secretResourceName: my-oci-credentials  # optional
+```
+
+### Migration
+
+The extension automatically migrates old format configurations to the new format during processing. However, **you should update your configurations** to use the new format to avoid deprecation warnings. The old format will be removed in a future version.
+
+**What changed:**
+- Old: `source.template` and `source.secretResourceName` at the root level
+- New: Nested under `source.gitRepository` or `source.ociRepository`
+
+**Why the change:**
+This change enables support for multiple source types (Git and OCI) while maintaining a clear, explicit configuration structure.
+
 # How to...
 
 ## Use it as a gardener operator

diff --git a/example/extension.yaml b/example/extension.yaml
@@ -13,16 +13,33 @@ spec:
       registry: ghcr.io/fluxcd
       namespace: flux-system
     source:
-      template:
-        apiVersion: source.toolkit.fluxcd.io/v1
-        kind: GitRepository
-        spec:
-          ref:
-            branch: main
-          # secretRef:
-          #  name: flux-system
-          url: https://github.com/fluxcd/flux2-kustomize-helm-example
-      # secretResourceName: flux-ssh-secret
+      gitRepository:
+        template:
+          apiVersion: source.toolkit.fluxcd.io/v1
+          kind: GitRepository
+          spec:
+            ref:
+              branch: main
+            # secretRef:
+            #  name: flux-system
+            url: https://github.com/fluxcd/flux2-kustomize-helm-example
+        # secretResourceName: flux-ssh-secret
+
+      # Alternatively, use an OCI repository:
+      # ociRepository:
+      #   template:
+      #     apiVersion: source.toolkit.fluxcd.io/v1
+      #     kind: OCIRepository
+      #     spec:
+      #       url: oci://ghcr.io/example/manifests
+      #       ref:
+      #         semver: '>= 1.0.0'
+      #         # or use tag: v1.0.0
+      #         # or use digest: sha256:abcd1234...
+      #       interval: 10m
+      #     # secretRef:
+      #     #   name: flux-system
+      #   # secretResourceName: oci-credentials
     kustomization:
       template:
         apiVersion: kustomize.toolkit.fluxcd.io/v1

diff --git a/hack/api-reference/api.md b/hack/api-reference/api.md
@@ -184,6 +184,57 @@ Defaults to &ldquo;flux-system&rdquo;.</p>
 </tr>
 </tbody>
 </table>
+<h3 id="flux.extensions.gardener.cloud/v1alpha1.GitRepositorySource">GitRepositorySource
+</h3>
+<p>
+(<em>Appears on:</em>
+<a href="#flux.extensions.gardener.cloud/v1alpha1.Source">Source</a>)
+</p>
+<p>
+<p>GitRepositorySource configures a GitRepository source for bootstrapping.</p>
+</p>
+<table>
+<thead>
+<tr>
+<th>Field</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>
+<code>template</code></br>
+<em>
+<a href="https://fluxcd.io/flux/components/source/api/v1/#source.toolkit.fluxcd.io/v1.GitRepository">
+source.toolkit.fluxcd.io/v1.GitRepository
+</a>
+</em>
+</td>
+<td>
+<p>Template is a partial GitRepository object in API version source.toolkit.fluxcd.io/v1.
+Required fields: spec.ref.*, spec.url.
+The following defaults are applied to omitted fields:
+- metadata.name is defaulted to &ldquo;flux-system&rdquo;
+- metadata.namespace is defaulted to &ldquo;flux-system&rdquo;
+- spec.interval is defaulted to &ldquo;1m&rdquo;</p>
+</td>
+</tr>
+<tr>
+<td>
+<code>secretResourceName</code></br>
+<em>
+string
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>SecretResourceName references a resource under Shoot.spec.resources.
+The secret data from this resource is used to create the GitRepository&rsquo;s credentials secret
+(GitRepository.spec.secretRef.name) if specified in Template.</p>
+</td>
+</tr>
+</tbody>
+</table>
 <h3 id="flux.extensions.gardener.cloud/v1alpha1.Kustomization">Kustomization
 </h3>
 <p>
@@ -221,14 +272,14 @@ The following defaults are applied to omitted field:
 </tr>
 </tbody>
 </table>
-<h3 id="flux.extensions.gardener.cloud/v1alpha1.Source">Source
+<h3 id="flux.extensions.gardener.cloud/v1alpha1.OCIRepositorySource">OCIRepositorySource
 </h3>
 <p>
 (<em>Appears on:</em>
-<a href="#flux.extensions.gardener.cloud/v1alpha1.FluxConfig">FluxConfig</a>)
+<a href="#flux.extensions.gardener.cloud/v1alpha1.Source">Source</a>)
 </p>
 <p>
-<p>Source configures how to bootstrap a Flux source object.</p>
+<p>OCIRepositorySource configures an OCIRepository source for bootstrapping.</p>
 </p>
 <table>
 <thead>
@@ -242,15 +293,15 @@ The following defaults are applied to omitted field:
 <td>
 <code>template</code></br>
 <em>
-<a href="https://fluxcd.io/flux/components/source/api/v1/#source.toolkit.fluxcd.io/v1.GitRepository">
-source.toolkit.fluxcd.io/v1.GitRepository
+<a href="https://fluxcd.io/flux/components/source/api/v1/#source.toolkit.fluxcd.io/v1.OCIRepository">
+source.toolkit.fluxcd.io/v1.OCIRepository
 </a>
 </em>
 </td>
 <td>
-<p>Template is a partial GitRepository object in API version source.toolkit.fluxcd.io/v1.
-Required fields: spec.ref.*, spec.url.
-The following defaults are applied to omitted field:
+<p>Template is a partial OCIRepository object in API version source.toolkit.fluxcd.io/v1.
+Required fields: spec.ref, spec.url.
+The following defaults are applied to omitted fields:
 - metadata.name is defaulted to &ldquo;flux-system&rdquo;
 - metadata.namespace is defaulted to &ldquo;flux-system&rdquo;
 - spec.interval is defaulted to &ldquo;1m&rdquo;</p>
@@ -266,8 +317,93 @@ string
 <td>
 <em>(Optional)</em>
 <p>SecretResourceName references a resource under Shoot.spec.resources.
-The secret data from this resource is used to create the GitRepository&rsquo;s credentials secret
-(GitRepository.spec.secretRef.name) if specified in Template.</p>
+The secret data from this resource is used to create the OCIRepository&rsquo;s credentials secret
+(OCIRepository.spec.secretRef.name) if specified in Template.</p>
+</td>
+</tr>
+</tbody>
+</table>
+<h3 id="flux.extensions.gardener.cloud/v1alpha1.Source">Source
+</h3>
+<p>
+(<em>Appears on:</em>
+<a href="#flux.extensions.gardener.cloud/v1alpha1.FluxConfig">FluxConfig</a>)
+</p>
+<p>
+<p>Source configures how to bootstrap a Flux source object.
+For new configurations, use either GitRepository or OCIRepository.</p>
+<p>MIGRATION: Old configurations using &lsquo;template&rsquo; and &lsquo;secretResourceName&rsquo; fields
+are automatically migrated to the new &lsquo;gitRepository&rsquo; format during API processing.
+The old fields will be cleared after migration. Users should update their configs
+to use the new structure:</p>
+<pre><code>Old:  source: { template: {...}, secretResourceName: &quot;...&quot; }
+New:  source: { gitRepository: { template: {...}, secretResourceName: &quot;...&quot; } }
+</code></pre>
+</p>
+<table>
+<thead>
+<tr>
+<th>Field</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>
+<code>gitRepository</code></br>
+<em>
+<a href="#flux.extensions.gardener.cloud/v1alpha1.GitRepositorySource">
+GitRepositorySource
+</a>
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>GitRepository configures a GitRepository source.</p>
+</td>
+</tr>
+<tr>
+<td>
+<code>ociRepository</code></br>
+<em>
+<a href="#flux.extensions.gardener.cloud/v1alpha1.OCIRepositorySource">
+OCIRepositorySource
+</a>
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>OCIRepository configures an OCIRepository source.</p>
+</td>
+</tr>
+<tr>
+<td>
+<code>template</code></br>
+<em>
+<a href="https://fluxcd.io/flux/components/source/api/v1/#source.toolkit.fluxcd.io/v1.GitRepository">
+source.toolkit.fluxcd.io/v1.GitRepository
+</a>
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>DEPRECATED: Use GitRepository.Template instead.
+Template is a partial GitRepository object in API version source.toolkit.fluxcd.io/v1.
+This field is automatically migrated to GitRepository.Template during defaulting.</p>
+</td>
+</tr>
+<tr>
+<td>
+<code>secretResourceName</code></br>
+<em>
+string
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>DEPRECATED: Use GitRepository.SecretResourceName instead.
+SecretResourceName references a resource under Shoot.spec.resources.
+This field is automatically migrated to GitRepository.SecretResourceName during defaulting.</p>
 </td>
 </tr>
 </tbody>