Update Composition Docs #475

plumbis · 2023-06-22T22:05:27Z

This PR rewrites the docs related to Composition.

The new /concepts/compositions page streamlines the details and focuses on the fields available in a Composition and what they do.

New XRD page breaks out info specific to writing XRDs and XRD status. Resolves #456, #448, #288,

New XR page details XR options. Resolves #455, (partially) #370, #432.

New Claims page details creating a Claim and claiming an existing XR. Resolves #281.

New Patch and Transform page covering patching options and configurations in detail. Resolves #380

New documentation on EnvironmentConfigs. Resolves #305

Additionally composite functions has been moved out of the KB and into /concepts

New KB on connection details.

Reviewed:

Page	Reviewer1	Reviewer2
Compositions	@negz
XRD	@negz
XR	@negz
Claims	@negz
Patch and Transform	@jbw976
EnvironmentConfigs	@jbw976
connection details	@jbw976

Signed-off-by: Pete Lumbis pete@upbound.io

netlify · 2023-06-22T22:05:37Z

✅ Deploy Preview for crossplane ready!

Name	Link
🔨 Latest commit	`ce9fedf`
🔍 Latest deploy log	https://app.netlify.com/sites/crossplane/deploys/64c15fc1f67e2b0007e0e2b1
😎 Deploy Preview	https://deploy-preview-475--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.

negz · 2023-07-13T18:03:46Z

@plumbis Should I set this to ready for review? I think it is, right?

plumbis · 2023-07-13T18:10:19Z

The published pages mentioned in the first comment are all ready for review. There are still at least two pages to write/edit before this would be ready to merge.

negz

Thanks @plumbis! I like where this is headed.

None of my comments are major or blocking - happy for someone else to approve this once you're ready.

content/master/concepts/claims.md

negz · 2023-07-13T22:46:38Z

content/master/concepts/claims.md

+```
+
+The Claim uses the XRD's 
+{{<hover label="xrd1" line="10">}}claimNames{{</hover>}} to request resources.


What do you mean by "request resources" here?

I think of claimNames is defining the type (i.e. type name) of the claim.

I changed this to "uses the XRD's kind API endpoint to request resources"

I'm purposefully vague with "request resources" to avoid unnecessary details about the underlying XR

negz · 2023-07-13T22:48:34Z

content/master/concepts/claims.md

+When Crossplane creates a Claim in a namespace it also creates a composite
+resource.


Nit: This reads to me as if Crossplane is going to, itself, create my-claimed-database.

I would think of what's happening here as something more like:

"When you create my-claimed-database in a namespace, Crossplane creates a matching XR".

The problem with "you" here is that it's not necessarily the reader. Flipping between terms (you, user, developer, etc) makes the reader have to "keep state" against who is doing what.

I'm going to second Nic's point. Crossplane has no ability to create claims. Claims are always user-applied.

negz · 2023-07-13T22:50:53Z

content/master/concepts/claims.md

+By default, creating a Claim creates a new composite resource. Claims can also
+link to existing composite resources. 


For context: This is where the name "claim" comes from. "I'm claiming this XR".

Do we have any real-world examples of users doing this? I'm just curious.

utils/vale/styles/Google/Headings.yml

content/master/concepts/patch-and-transform.md

negz · 2023-07-14T00:44:36Z

content/master/concepts/patch-and-transform.md

+- type: FromCompositeFieldPath
+  fromFieldPath: spec.parameters.size
+  toFieldPath: spec.forProvider.settings.tier
+```


Note to self: I reviewed every file but this one, but only got this far down this one before I had to run.

jbw976

Just took a pass specifically through the connection secret details in the context of #485, that's all I looked at right now 🙇‍♂️

content/master/concepts/compositions.md

content/master/concepts/composite-resource-definitions.md

content/master/concepts/composite-resources.md

jbw976

Took a full pass through patch-and-transform.md today and left some comments, looking very good @plumbis!

content/master/concepts/patch-and-transform.md

jbw976 · 2023-07-21T18:20:57Z

content/master/concepts/patch-and-transform.md

+
+The 
+{{<hover label="combineFromComp" line="12">}}CombineFromComposite{{</hover>}}
+patch only supports the 


for a few of these patch types, we say that it only supports X option, then further down after another paragraph we say that it only supports Y strategy. Should these two sentences be combined into the same paragraph, so the context of "limitations" for this patch type is all grouped together?

e.g., The CombineToComposite patch only supports the combine option and the only supported strategy is strategy: string.

Can you give me another example? For this one (and likely the others) I keep them on unique lines to try and make it easier to find the one line/argument/whatever when you're skimming or to be able to understand each line (almost like an API doc) if you're building it for the first time. Open to changing.

content/master/concepts/patch-and-transform.md

jbw976

Finished reading/reviewing the Environment Configurations page! Not too many comments here, mostly it was all helpful/useful 🤓

content/master/concepts/environment-configs.md

jbw976

Read through the new connection details KB page and the storing connection details section of the compositions page.

content/master/concepts/compositions.md

content/knowledge-base/guides/connection-details.md

AaronME

Thanks, @plumbis !

AaronME · 2023-07-25T23:41:59Z

content/knowledge-base/guides/connection-details.md

+This guide discusses creating Kubernetes secrets.  
+Crossplane also supports using external secret stores like [HashiCorp Vault](https://www.vaultproject.io/). 
+
+Read the [external secrets store guide]({{<ref "/knowledge-base/integrations/vault-as-secret-store">}}) for more information on using Crossplane


Might be helpful to call out that using ESS or native secrets is a decision which must be made at composition design time. The configuration fields are mutually exclusive, I think.

I haven't tested it but according to code comments you can do both.

AaronME · 2023-07-25T23:46:37Z

content/knowledge-base/guides/connection-details.md

+Compositions and CompositeResourceDefinitions require the exact names of the
+secrets generated by a resource. 


I don't understand what this is saying.

I'm struggling to express "hey, this is how you find the names of the keys a resource produces and you'll need them when defining the connectiondetails in a Composition"

I'm wide open to suggestions.

AaronME · 2023-07-25T23:50:26Z

content/knowledge-base/guides/connection-details.md

+Resources in a Composition that create connection details still create a
+secret object containing their connection details.  


Suggested change

Resources in a Composition that create connection details still create a

secret object containing their connection details.

Managed Resources create secrets containing their connection details. This is true whether the Managed Resource is declared on its own or as part of a Composition, and whether that Composition is called as an XR or Claim.

Indicating that this is Managed Resource functionality might help users grok the crossplane/kubernetes model.

Are you trying to say "an MR creates a secret. This always happens, even when it's an XR?"

AaronME · 2023-07-25T23:51:45Z

content/knowledge-base/guides/connection-details.md

+Crossplane also generates
+another secret object for each composite resource, 
+containing the secrets from all the defined resources.
+


"Composition authors will need to be aware of both of these secrets when crafting their compositions."

I don't think that's necessarily true. it's possible that the composed resource secret isn't used/needed and only the composite secret is used.

content/knowledge-base/guides/connection-details.md

AaronME · 2023-07-26T03:42:14Z

content/master/concepts/composite-resources.md

+Creating composite resources requires a 
+[Composition]({{<ref "./compositions">}}) and a 
+[CompositeResourceDefinition]({{<ref "./composite-resource-definitions">}}) 
+(`XRD`).  
+The Composition defines the set of resources to create.  
+The XRD defines the custom API users call to request the set of resources.


I've leaned into the following convention, because XR can get confusing:

I use the term "Composite Resource" to refer to the API defined by an XRD and one or more Compositions.
I use the term "CompositeResource" and the abbreviation "XR" to refer to a Resource which calls the API of a Composite Resource -- or a specific instantiation of a Composite Resource.

I welcome any suggestions on how to more clearly differentiate between the API which can be called (XRD + Composition = Composite Resource) and a specific call to that API (Claim --> CompositeResource, or XR).

content/master/concepts/composite-resources.md

content/master/concepts/patch-and-transform.md

sttts · 2023-07-26T14:11:10Z

content/knowledge-base/guides/connection-details.md

+usernames, passwords or connection details like an IP address.  
+
+Crossplane refers to this information as the _connection details_ or 
+_connection secrets_.   


These two paragraphs should better be right at the top to set the stage what this topic is actually about.

The reason it's not is because the current top is intended to be a quick reference for anyone dealing with secrets and wanting a checklist to see what they did right/wrong.

Signed-off-by: Pete Lumbis <pete@upbound.io>

jbw976

Thanks for all the collaboration and syncing together to review and discuss all these changes. They will be a great improvement for the v1.13 docs!! 💪

plumbis mentioned this pull request Jun 28, 2023

Create a KB article on XRD API versioning #478

Closed

plumbis force-pushed the compositions branch from 98c8886 to 3d93cb2 Compare June 30, 2023 15:17

negz self-assigned this Jul 13, 2023

negz self-requested a review July 13, 2023 18:03

AaronME self-assigned this Jul 13, 2023

negz reviewed Jul 14, 2023

View reviewed changes

plumbis mentioned this pull request Jul 15, 2023

Clarify the specifics of connection details in compositions #485

Merged

jbw976 reviewed Jul 18, 2023

View reviewed changes

content/master/concepts/compositions.md Show resolved Hide resolved

content/master/concepts/composite-resource-definitions.md Show resolved Hide resolved

content/master/concepts/composite-resources.md Outdated Show resolved Hide resolved

plumbis mentioned this pull request Jul 18, 2023

Vale doesn't catch CompositeResourceDefinintions as an error #490

Closed

jbw976 reviewed Jul 21, 2023

View reviewed changes

plumbis marked this pull request as ready for review July 21, 2023 21:36

jbw976 reviewed Jul 24, 2023

View reviewed changes

content/master/concepts/environment-configs.md Outdated Show resolved Hide resolved

content/master/concepts/environment-configs.md Show resolved Hide resolved

content/master/concepts/environment-configs.md Show resolved Hide resolved

jbw976 reviewed Jul 25, 2023

View reviewed changes

AaronME self-requested a review July 25, 2023 20:12

AaronME reviewed Jul 26, 2023

View reviewed changes

sttts reviewed Jul 26, 2023

View reviewed changes

plumbis added 11 commits July 26, 2023 13:56

move XFNs to concepts

41243c6

Signed-off-by: Pete Lumbis <pete@upbound.io>

Move composition troubleshooting out of composition doc

91b3253

Signed-off-by: Pete Lumbis <pete@upbound.io>

Spin content out of compositions into unique page

ad26c2e

Signed-off-by: Pete Lumbis <pete@upbound.io>

Update links to compositions

4fa8596

Signed-off-by: Pete Lumbis <pete@upbound.io>

Remove duplicate rule

fc3cf27

Signed-off-by: Pete Lumbis <pete@upbound.io>

more crossplane types

22676d4

Signed-off-by: Pete Lumbis <pete@upbound.io>

WIP

162c66a

Signed-off-by: Pete Lumbis <pete@upbound.io>

+compositeTypeRef +Compositions

69c8b86

Signed-off-by: Pete Lumbis <pete@upbound.io>

+substrings

937cf1b

Signed-off-by: Pete Lumbis <pete@upbound.io>

wip

ada8c45

Signed-off-by: Pete Lumbis <pete@upbound.io>

link update

cac1e64

Signed-off-by: Pete Lumbis <pete@upbound.io>

plumbis added 14 commits July 26, 2023 14:01

Vale fix

4eb9806

Signed-off-by: Pete Lumbis <pete@upbound.io>

Removing terminology page now that all terms are individually documented

09312ef

Signed-off-by: Pete Lumbis <pete@upbound.io>

Add descriptions to all concepts pages

6e9f163

Signed-off-by: Pete Lumbis <pete@upbound.io>

PR feedback

9639c87

Signed-off-by: Pete Lumbis <pete@upbound.io>

feedback from jbw

6e7f643

Signed-off-by: Pete Lumbis <pete@upbound.io>

Connection secrets content

723d8af

Signed-off-by: Pete Lumbis <pete@upbound.io>

Style updates

63fe109

Signed-off-by: Pete Lumbis <pete@upbound.io>

remove references to MR in secrets

0b1f8c0

Signed-off-by: Pete Lumbis <pete@upbound.io>

Add a comment based on jbw feedback

85736b9

Signed-off-by: Pete Lumbis <pete@upbound.io>

fix incorrect shortcode arg

62e1322

Signed-off-by: Pete Lumbis <pete@upbound.io>

review feedback from jbw

6fa6d5b

Signed-off-by: Pete Lumbis <pete@upbound.io>

add an alias to redirect from original KB

63f4c8b

Signed-off-by: Pete Lumbis <pete@upbound.io>

add note that values aren't written to the composed resource secret

d2e094d

Signed-off-by: Pete Lumbis <pete@upbound.io>

review feedback from aaron

ce9fedf

Signed-off-by: Pete Lumbis <pete@upbound.io>

plumbis force-pushed the compositions branch from 7905951 to ce9fedf Compare July 26, 2023 18:02

jbw976 approved these changes Jul 26, 2023

View reviewed changes

plumbis merged commit 2583a00 into crossplane:master Jul 26, 2023
7 of 8 checks passed

plumbis deleted the compositions branch July 26, 2023 18:26

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update Composition Docs #475

Update Composition Docs #475

plumbis commented Jun 22, 2023 •

edited by jbw976

netlify bot commented Jun 22, 2023 •

edited

negz commented Jul 13, 2023

plumbis commented Jul 13, 2023

negz left a comment

negz Jul 13, 2023

plumbis Jul 18, 2023

negz Jul 13, 2023

plumbis Jul 18, 2023

AaronME Jul 26, 2023

negz Jul 13, 2023

AaronME Jul 26, 2023

negz Jul 14, 2023

jbw976 left a comment

jbw976 left a comment

jbw976 Jul 21, 2023

plumbis Jul 21, 2023

jbw976 left a comment

jbw976 left a comment

AaronME left a comment

AaronME Jul 25, 2023

plumbis Jul 26, 2023

AaronME Jul 25, 2023

plumbis Jul 26, 2023

AaronME Jul 25, 2023

plumbis Jul 26, 2023

AaronME Jul 25, 2023

plumbis Jul 26, 2023

AaronME Jul 26, 2023

sttts Jul 26, 2023

plumbis Jul 26, 2023

jbw976 left a comment

		When Crossplane creates a Claim in a namespace it also creates a composite
		resource.

		By default, creating a Claim creates a new composite resource. Claims can also
		link to existing composite resources.

		Compositions and CompositeResourceDefinitions require the exact names of the
		secrets generated by a resource.

		Resources in a Composition that create connection details still create a
		secret object containing their connection details.

	Resources in a Composition that create connection details still create a
	secret object containing their connection details.
	Managed Resources create secrets containing their connection details. This is true whether the Managed Resource is declared on its own or as part of a Composition, and whether that Composition is called as an XR or Claim.

Update Composition Docs #475

Update Composition Docs #475

Conversation

plumbis commented Jun 22, 2023 • edited by jbw976

netlify bot commented Jun 22, 2023 • edited

✅ Deploy Preview for crossplane ready!

negz commented Jul 13, 2023

plumbis commented Jul 13, 2023

negz left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jbw976 left a comment

Choose a reason for hiding this comment

jbw976 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jbw976 left a comment

Choose a reason for hiding this comment

jbw976 left a comment

Choose a reason for hiding this comment

AaronME left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jbw976 left a comment

Choose a reason for hiding this comment

plumbis commented Jun 22, 2023 •

edited by jbw976

netlify bot commented Jun 22, 2023 •

edited