Document MRD/MRAP/SafeStart #958

n3wscott · 2025-08-07T18:26:40Z

first draft of MRD documentation based on the spec and PRs related to MRD/MRAP/SafeStart

netlify · 2025-08-07T18:26:46Z

✅ Deploy Preview for crossplane ready!

Name	Link
🔨 Latest commit	`b22239c`
🔍 Latest deploy log	https://app.netlify.com/projects/crossplane/deploys/68967ae8ec9ce3000819f581
😎 Deploy Preview	https://deploy-preview-958--crossplane.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 80 (🟢 up 2 from production) Accessibility: 90 (🔴 down 2 from production) Best Practices: 83 (no change from production) SEO: 100 (no change from production) PWA: 70 (no change from production) View the detailed breakdown and full score reports

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

content/master/get-started/get-started-with-mrds.md

content/master/guides/implementing-safestart.md

content/master/packages/provider-capabilities.md

phisco · 2025-08-08T14:08:30Z

content/master/get-started/get-started-with-mrds.md

+Add more resources using wildcard patterns. Update your activation policy:
+
+```shell
+kubectl patch mrap aws-demo-resources --type merge -p '{


nit: I prefer kubectl apply -f - <<EOF with full manifests, so that people can copy paste from any point in the guide, rather than incremental patches. Definitely not a showstopper though.

this is a continuation of the above. So in general I agree but in this case I am not sure

I believe the other getting started guides don't currently use the EOF style. This guide should match them closely stylistically.

FWIW preferences like this in our docs have been a big challenge over the years. We've gone back and forth on here docs. Last time we talked about it I believe the consensus was to do what the Kubernetes docs do, which is:

Example manifests are distinct files in the docs repo

Our docs site tool (currently Hugo) embeds those files inline

We include kubectl apply -f https://docs.crossplane.io/... links to quickly apply them

IMO the Kube docs approach gives the best of both worlds.

You can quickly apply a manifest by copying a CLI command

The example manifest shown inline is plain old YAML, not YAML with arcane shell stuff around it

I don't think we had a tracking issue for this - raised #960.

… MRD/MRAP/SafeStart Signed-off-by: Scott Nichols <[email protected]>

Signed-off-by: Scott Nichols <[email protected]>

…t page docs Signed-off-by: Scott Nichols <[email protected]>

content/master/get-started/get-started-with-mrds.md

Signed-off-by: Scott Nichols <[email protected]>

negz

I've just read the getting started guide so far.

I see right as I'm hitting comment that you just moved it though. Some of my comments about sections being too detailed are less important in that context.

negz · 2025-08-08T19:17:21Z

content/master/get-started/get-started-with-mrds.md

+{{< hint "tip" >}}
+This guide demonstrates the performance and discovery benefits of MRDs by 
+working with a subset of AWS resources rather than installing hundreds of CRDs.
+{{< /hint >}}


I imagine a lot of novice/first time users won't know what these issues are, if they've never actually tried to install a billion CRDs. Not sure what the best way to address that is - we probably don't want to spent a ton of time educating them on the problem in the guide.

negz · 2025-08-08T19:37:21Z

content/master/get-started/get-started-with-mrds.md

+Before installing providers, it's important to understand Crossplane's default 
+activation behavior. Crossplane creates a default ManagedResourceActivationPolicy 
+that, by default, activates **all** managed resources with a `"*"` pattern.


Suggested change

Before installing providers, it's important to understand Crossplane's default

activation behavior. Crossplane creates a default ManagedResourceActivationPolicy

that, by default, activates **all** managed resources with a `"*"` pattern.

Before installing providers, it's important to understand Crossplane's default

activation behavior. Crossplane creates a default `ManagedResourceActivationPolicy`

that, by default, activates **all** managed resources with a `"*"` pattern.

Existing guides use Codeblocks for all kind names. I'm on the fence about this practice and our docs overall aren't super consistent, but we should match the guides for now.

negz · 2025-08-08T19:39:55Z

content/master/get-started/get-started-with-mrds.md

+metadata:
+  name: provider-aws
+spec:
+  package: xpkg.upbound.io/crossplane-contrib/provider-aws:v0.45.0


We must use xpkg.crossplane.io in these guides. @jeanduplessis mentioned the first build of provider-aws with real v2 support will be v2.0.0.

negz · 2025-08-08T19:41:02Z

content/master/get-started/get-started-with-mrds.md

+
+{{< hint "important" >}}
+The default `"*"` activation pattern defeats the performance benefits of 
+safe-start by activating all resources. For this tutorial, the guide works with the 


This is the first mention of safe-start. Probably worth explaining what that is and how it relates to MRDs and MRAPs.

negz · 2025-08-08T19:41:59Z

content/master/get-started/get-started-with-mrds.md

+Look for the `connectionDetails` section:
+
+```yaml
+spec:
+  connectionDetails:
+  - description: The public IP address assigned to the instance
+    name: public_ip
+    type: string
+  - description: The private IP address assigned to the instance  
+    name: private_ip
+    type: string
+  - description: The public DNS name assigned to the instance
+    name: public_dns
+    type: string
+```


Do any providers implement this yet in practice?

I'd suggest dropping it then (no-one will be able to 'follow' the guide yet).

how are the providers going to implement them if they don't get documented?

negz · 2025-08-08T19:43:13Z

content/master/get-started/get-started-with-mrds.md

+instances.ec2.aws.crossplane.io                 2024-01-15T10:30:00Z
+```
+
+## Create a managed resource


Could link to the existing MR guide for this instead. I'm picturing a tip "follow the get started with managed resources guide to verify you can create an MR".

negz · 2025-08-08T19:47:13Z

content/master/get-started/get-started-with-mrds.md

+  # ... other activated MRDs
+```
+
+## Performance comparison


Perf, multiple policies, and prod recommendations feel out of place for a getting started guide. I'd move them to concepts.

negz

More review - now through the safe start guide.

content/master/guides/implementing-safestart.md

negz · 2025-08-08T19:53:15Z

content/master/guides/implementing-safestart.md

+
+Test safe-start behavior in a real cluster:
+
+```shell


This is a fairly large script to include inline. I wonder if it'd be useful to actually save it somewhere (e.g. outside of docs) for folks to run. Maybe the provider-template repo?

content/master/guides/implementing-safestart.md

negz

MRAP review

~50% of this feels low value to me. I'd cut most of the examples of different ways to use policies in the wild (team based, env based, use gitops etc etc).

content/master/guides/mrd-activation-policies.md

n3wscott · 2025-08-08T20:36:37Z

@negz why don't you just edit and push the changes you want? or fork the PR

Signed-off-by: Scott Nichols <[email protected]>

negz · 2025-08-08T23:30:18Z

@negz why don't you just edit and push the changes you want? or fork the PR

Sure lemme take a shot and see what I come up with.

n3wscott force-pushed the document-mrd branch 7 times, most recently from 6106ed2 to 7ed06f6 Compare August 7, 2025 20:19

n3wscott commented Aug 7, 2025

View reviewed changes

n3wscott force-pushed the document-mrd branch 5 times, most recently from dc59c59 to b1f70b3 Compare August 7, 2025 21:18

n3wscott marked this pull request as ready for review August 7, 2025 21:21

n3wscott requested a review from negz August 7, 2025 21:22

phisco linked an issue Aug 8, 2025 that may be closed by this pull request

Document the new ManagedResourceDefinitions and ManagedResourceActivationPolicies types #957

Open

phisco reviewed Aug 8, 2025

View reviewed changes

n3wscott added 4 commits August 8, 2025 09:32

first draft of MRD documentation based on the spec and PRs related to…

3fcc447

… MRD/MRAP/SafeStart Signed-off-by: Scott Nichols <[email protected]>

linter

e0a38db

Signed-off-by: Scott Nichols <[email protected]>

addressing feedback

cc1784c

Signed-off-by: Scott Nichols <[email protected]>

trim the implementing safestart guide

8f42902

Signed-off-by: Scott Nichols <[email protected]>

n3wscott force-pushed the document-mrd branch from 8df1adc to 64722f6 Compare August 8, 2025 16:34

move around a bit of content. Trim down how much MRDs are on the fron…

ded459a

…t page docs Signed-off-by: Scott Nichols <[email protected]>

n3wscott force-pushed the document-mrd branch from 64722f6 to ded459a Compare August 8, 2025 16:57

negz reviewed Aug 8, 2025

View reviewed changes

content/master/get-started/get-started-with-mrds.md Outdated Show resolved Hide resolved

move mrd guide

a07a632

Signed-off-by: Scott Nichols <[email protected]>

negz reviewed Aug 8, 2025

View reviewed changes

content/master/guides/mrd-activation-policies.md Outdated Show resolved Hide resolved

drop mrd activation policies guide

f05078c

Signed-off-by: Scott Nichols <[email protected]>

n3wscott force-pushed the document-mrd branch from eb63837 to 7f351c4 Compare August 8, 2025 22:20

clean up links

b22239c

Signed-off-by: Scott Nichols <[email protected]>

n3wscott force-pushed the document-mrd branch from 7f351c4 to b22239c Compare August 8, 2025 22:32

negz mentioned this pull request Aug 9, 2025

Add documentation for MRDs, MRAPs, and safe-start #964

Open

n3wscott closed this Aug 11, 2025

Document MRD/MRAP/SafeStart #958

Document MRD/MRAP/SafeStart #958

Conversation

n3wscott commented Aug 7, 2025

Uh oh!

netlify bot commented Aug 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for crossplane ready!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

negz left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

negz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

negz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

n3wscott commented Aug 8, 2025

Uh oh!

negz commented Aug 8, 2025

Uh oh!

Uh oh!

netlify bot commented Aug 7, 2025 •

edited

Loading