Clarify the specifics of connection details in compositions

[jbw976]

This PR attempts to clarify the nuances/specifics that are necessary to correctly specify the connection details that will be aggregated from composed resources and published for a claim.

This wording was put together in our latest FAQ blog post, so I wanted to bring the docs closer in line to what we felt worked in that post: https://blog.crossplane.io/faq-2-claim-connection-details/

Most of the changes are just rewordings and clarifications, e.g. to point to specific field paths, but there is 1 line I found in my testing that appears to be incorrect in our current docs:

1. The claim and XR must both specify a writeConnectionSecretToRef.

I believe this is inaccurate because XR/XRDs do not have a writeConnectionSecretToRef field. Instead, a Composition has a writeConnectionSecretsToNamespace field and that was missing from our current docs.

[netlify]

✅ Deploy Preview for crossplane ready!

Name	Link
🔨 Latest commit	ec97ef2
🔍 Latest deploy log	https://app.netlify.com/sites/crossplane/deploys/64b7061c36818e00088e68cf
😎 Deploy Preview	https://deploy-preview-485--crossplane.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[plumbis]

Can you take a look at the changes in PR #475 and give feedback on this there?

XRD Secrets

XR Secrets

Composition Secrets

Looks like I may have missed covering secrets for Claims.

[jbw976]

Just took a pass now @plumbis: #475 (review)

[jbw976]

there is 1 line I found in my testing that appears to be incorrect in our current docs:

1. The claim and XR must both specify a writeConnectionSecretToRef.

I believe this is inaccurate because XR/XRDs do not have a writeConnectionSecretToRef field

btw, I think I goofed this 😓 - I think I was reading the original documentation from the perspective of the XRD having to specify a writeConnectionSecretToRef field. What I now believe I overlooked is the scenario of someone directly creating a XR instead of indirectly having the XR created via a claim.

I'll try to update both this PR and the blog post to get this detail correct 😩

[jbw976]

@plumbis I updated the guidance in these docs to be actually accurate in ec97ef2, can you take another look?

I also published that update to https://blog.crossplane.io/faq-2-claim-connection-details/ already so the correction is out there for folks. We can tweak if needed from feedback in this PR 😅