docs: clarify writeConnectionSecretToRef removal is XR-only, not MR-level

ytsarev · ytsarev · commit cf1f19fc0202 · 2026-03-05T12:11:45.000+01:00
A common source of confusion when upgrading to v2 is assuming that the
removal of native XR connection details also affects managed resources.
This is not the case — writeConnectionSecretToRef on MRs is unchanged.

Add a tip callout to the upgrade guide's "Composite resource connection
details" section and expand the note in the connection details composition
guide to explicitly state that only the XR-level aggregation was removed,
while MR-level usage continues to work as before. Applied across all v2.x
versions and master.

Signed-off-by: Yury Tsarev &lt;yury@upbound.io&gt;
diff --git a/content/master/guides/connection-details-composition.md b/content/master/guides/connection-details-composition.md
@@ -17,7 +17,9 @@ resources and exposes them for the XR.
 
 {{<hint "note">}}
 Crossplane v1 included a feature that automatically created connection details
-for XRs.
+for XRs. **Crossplane v2 removed native XR connection details**—but `writeConnectionSecretToRef`
+on managed resources (MRs) still works as before. The function pipeline now controls
+XR level aggregation; compose the `Secret` explicitly for full control.
 
 To learn more about how to specify XR connection details in Crossplane v1, please see the
 [v1 connection details]({{<ref "../../v1.20/concepts/connection-details">}}) docs page.
diff --git a/content/master/guides/upgrade-to-crossplane-v2.md b/content/master/guides/upgrade-to-crossplane-v2.md
@@ -96,6 +96,17 @@ or [External Secrets Operator](https://external-secrets.io/latest/) before upgra
 ### Composite resource connection details
 **Removed**: composite resources no longer have native connection details support.
 
+{{<hint "tip">}}
+**This only affects XRs, not managed resources.**
+
+`writeConnectionSecretToRef` on managed resources (MRs) still works as
+before—use it directly on `spec.writeConnectionSecretToRef` in any MR spec.
+
+Only the _XR level_ built-in connection details aggregation changed. Crossplane
+v2 gives your composition function full control instead: you decide what goes in
+the secret, where it's created, and when.
+{{</hint>}}
+
 You can recreate this feature by composing your own connection details `Secret`
 as described in the [connection details composition guide]({{<ref "./connection-details-composition">}}).
 
diff --git a/content/v2.0/guides/connection-details-composition.md b/content/v2.0/guides/connection-details-composition.md
@@ -17,7 +17,9 @@ resources and exposes them for the XR.
 
 {{<hint "note">}}
 Crossplane v1 included a feature that automatically created connection details
-for XRs.
+for XRs. **Crossplane v2 removed native XR connection details**—but `writeConnectionSecretToRef`
+on managed resources (MRs) still works as before. The function pipeline now controls
+XR level aggregation; compose the `Secret` explicitly for full control.
 
 To learn more about how to specify XR connection details in Crossplane v1, please see the
 [v1 connection details]({{<ref "../../v1.20/concepts/connection-details">}}) docs page.
diff --git a/content/v2.0/guides/upgrade-to-crossplane-v2.md b/content/v2.0/guides/upgrade-to-crossplane-v2.md
@@ -96,6 +96,17 @@ or [External Secrets Operator](https://external-secrets.io/latest/) before upgra
 ### Composite resource connection details
 **Removed**: composite resources no longer have native connection details support.
 
+{{<hint "tip">}}
+**This only affects XRs, not managed resources.**
+
+`writeConnectionSecretToRef` on managed resources (MRs) still works as
+before—use it directly on `spec.writeConnectionSecretToRef` in any MR spec.
+
+Only the _XR level_ built-in connection details aggregation changed. Crossplane
+v2 gives your composition function full control instead: you decide what goes in
+the secret, where it's created, and when.
+{{</hint>}}
+
 You can recreate this feature by composing your own connection details `Secret`
 as described in the [connection details composition guide]({{<ref "./connection-details-composition">}}).
 
diff --git a/content/v2.1/guides/connection-details-composition.md b/content/v2.1/guides/connection-details-composition.md
@@ -17,7 +17,9 @@ resources and exposes them for the XR.
 
 {{<hint "note">}}
 Crossplane v1 included a feature that automatically created connection details
-for XRs.
+for XRs. **Crossplane v2 removed native XR connection details**—but `writeConnectionSecretToRef`
+on managed resources (MRs) still works as before. The function pipeline now controls
+XR level aggregation; compose the `Secret` explicitly for full control.
 
 To learn more about how to specify XR connection details in Crossplane v1, please see the
 [v1 connection details]({{<ref "../../v1.20/concepts/connection-details">}}) docs page.
diff --git a/content/v2.1/guides/upgrade-to-crossplane-v2.md b/content/v2.1/guides/upgrade-to-crossplane-v2.md
@@ -96,6 +96,17 @@ or [External Secrets Operator](https://external-secrets.io/latest/) before upgra
 ### Composite resource connection details
 **Removed**: composite resources no longer have native connection details support.
 
+{{<hint "tip">}}
+**This only affects XRs, not managed resources.**
+
+`writeConnectionSecretToRef` on managed resources (MRs) still works as
+before—use it directly on `spec.writeConnectionSecretToRef` in any MR spec.
+
+Only the _XR level_ built-in connection details aggregation changed. Crossplane
+v2 gives your composition function full control instead: you decide what goes in
+the secret, where it's created, and when.
+{{</hint>}}
+
 You can recreate this feature by composing your own connection details `Secret`
 as described in the [connection details composition guide]({{<ref "./connection-details-composition">}}).
 
diff --git a/content/v2.2/guides/connection-details-composition.md b/content/v2.2/guides/connection-details-composition.md
@@ -17,7 +17,9 @@ resources and exposes them for the XR.
 
 {{<hint "note">}}
 Crossplane v1 included a feature that automatically created connection details
-for XRs.
+for XRs. **Crossplane v2 removed native XR connection details**—but `writeConnectionSecretToRef`
+on managed resources (MRs) still works as before. The function pipeline now controls
+XR level aggregation; compose the `Secret` explicitly for full control.
 
 To learn more about how to specify XR connection details in Crossplane v1, please see the
 [v1 connection details]({{<ref "../../v1.20/concepts/connection-details">}}) docs page.
diff --git a/content/v2.2/guides/upgrade-to-crossplane-v2.md b/content/v2.2/guides/upgrade-to-crossplane-v2.md
@@ -96,6 +96,17 @@ or [External Secrets Operator](https://external-secrets.io/latest/) before upgra
 ### Composite resource connection details
 **Removed**: composite resources no longer have native connection details support.
 
+{{<hint "tip">}}
+**This only affects XRs, not managed resources.**
+
+`writeConnectionSecretToRef` on managed resources (MRs) still works as
+before—use it directly on `spec.writeConnectionSecretToRef` in any MR spec.
+
+Only the _XR level_ built-in connection details aggregation changed. Crossplane
+v2 gives your composition function full control instead: you decide what goes in
+the secret, where it's created, and when.
+{{</hint>}}
+
 You can recreate this feature by composing your own connection details `Secret`
 as described in the [connection details composition guide]({{<ref "./connection-details-composition">}}).
 
