From 2b0aecb63d3e8fabf24c4e4252a1a49a31b59586 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Corentin=20N=C3=A9au?= <tan.neau@suse.com>
Date: Fri, 17 Oct 2025 16:17:54 +0200
Subject: [PATCH] Document propagation of resources downstream

This adds a new page for the new experimental feature exposing
propagation of secrets and config maps to downstream clusters.
---
 docs/enableexperimental.md                |  6 ++-
 docs/experimental-downstream-resources.md | 50 +++++++++++++++++++++++
 docs/gitrepo-content.md                   | 11 ++++-
 sidebars.js                               |  3 +-
 4 files changed, 66 insertions(+), 4 deletions(-)
 create mode 100644 docs/experimental-downstream-resources.md

diff --git a/docs/enableexperimental.md b/docs/enableexperimental.md
index 944cb9a29..f1826416e 100644
--- a/docs/enableexperimental.md
+++ b/docs/enableexperimental.md
@@ -8,8 +8,10 @@ See also "[Configure Fleet Install Options in Rancher](./ref-configuration#confi
 
 ## Available experimental features
 
-Fleet currently supports the following experimental features:
+Fleet currently supports the following experimental features, toggled through their respective environment variables:
 * Scheduling: [`EXPERIMENTAL_SCHEDULES`](./scheduling.md)
+* Automated propagation of resources to downstream clusters:
+[`EXPERIMENTAL_COPY_RESOURCES_DOWNSTREAM`](./experimental-downstream-resources.md)
 
 ## Enabling an experimental feature
 
@@ -33,4 +35,4 @@ The parameters are the same, but you have to add the `fleet.` prefix.
 ```
 --set-string fleet.extraEnv[0].name=EXPERIMENTAL_SCHEDULES \
 --set-string fleet.extraEnv[0].value=true \
-```
\ No newline at end of file
+```
diff --git a/docs/experimental-downstream-resources.md b/docs/experimental-downstream-resources.md
new file mode 100644
index 000000000..a74d34453
--- /dev/null
+++ b/docs/experimental-downstream-resources.md
@@ -0,0 +1,50 @@
+# Automatically copying resources to downstream clusters
+
+:::warning
+This is an experimental feature.
+:::
+
+From Fleet v0.14.0 onwards, Fleet supports propagating external resources to downstream clusters.
+
+This simplifies dealing with dependencies of charts, such as values coming from external resources.
+See also [valuesFrom](gitrepo-content#using-valuesfrom).
+
+## How it works
+
+HelmOps support a new `downstreamResource` field, which can be used to reference resources by kind and name.
+Those resources must:
+* Be either secrets or config maps. No other kinds are currently supported.
+* Live in the same namespace as the HelmOp referencing them.
+
+Example:
+```yaml
+apiVersion: fleet.cattle.io/v1alpha1
+kind: HelmOp
+[...] # metadata
+spec:
+  helm:
+    [...] # Helm options
+  downstreamResources:
+    - kind: Secret
+      name: my-secret
+    - kind: ConfigMap
+      name: my-config
+```
+
+This instructs the Fleet controller to copy those resources to each targeted downstream cluster, before deploying the
+workload (in this case specified through a Helm chart) to said downstream cluster.
+
+When a cluster is not targeted anymore, the Fleet agent will delete those resources from the cluster as well. They will
+remain on the upstream cluster, though.
+
+:::note
+If resources referenced through `downstreamResources` should stay on downstream clusters even after they are no longer
+targeted, [keepResources](./ref-bundle) should be set to `true` on the HelmOp.
+:::
+
+
+## Limitations
+
+Fleet does not monitor resources referenced by downstreamResources for changes.
+This means that changes to secrets and config maps referenced for downstream copy will only be applied when a HelmOp is updated.
+
diff --git a/docs/gitrepo-content.md b/docs/gitrepo-content.md
index 5da392a26..29bce7a34 100644
--- a/docs/gitrepo-content.md
+++ b/docs/gitrepo-content.md
@@ -286,7 +286,16 @@ The recommended and safer approach is to use `valuesFrom`, which references Kube
 
 ### Using ValuesFrom
 
-These examples showcase the style and format for using `valuesFrom`. ConfigMaps and Secrets should be created in *downstream clusters*.
+These examples showcase the style and format for using `valuesFrom`.
+
+:::note **Propagating ConfigMaps and Secrets to downstream clusters**
+ConfigMaps and Secrets should generally be created directly in *downstream clusters*.
+
+However, from Fleet v0.14.0 onwards, they can also be referenced through a HelmOp's `downstreamResources` field to be
+automatically propagated to targeted downstream clusters.
+
+See [this page](experimental-downstream-resources.md) for more details.
+:::
 
 Example [ConfigMap](https://kubernetes.io/docs/concepts/configuration/configmap/):
 
diff --git a/sidebars.js b/sidebars.js
index 85a9bf41b..a714f781b 100644
--- a/sidebars.js
+++ b/sidebars.js
@@ -110,7 +110,8 @@ module.exports = {
       items:[
         'enableexperimental',
         'scheduling',
-        'ref-schedule'
+        'ref-schedule',
+        'experimental-downstream-resources',
       ],
     },
   ],