Add documentation for MRDs, MRAPs, and safe-start #964
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
✅ Deploy Preview for crossplane ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
negz
force-pushed
the
emm-arr-dee
branch
21 times, most recently
from
d5ba59e to
94f0d80
Compare
Same for CronOperation. This matches the established pattern. Signed-off-by: Nic Cope <[email protected]>
negz
force-pushed
the
emm-arr-dee
branch
3 times, most recently
from
9018335 to
4150774
Compare
negz
changed the title
Large Crossplane providers install hundreds of CRDs consuming significant API server resources, even when users only need a few resource types. The new alpha ManagedResourceDefinition (MRD) and ManagedResourceActivationPolicy (MRAP) features in Crossplane v2.0+ solve this by enabling selective activation of provider resources, but lack user-facing documentation. This change adds complete documentation covering both concepts and practical implementation. The MRD concepts page explains the CRD scaling problem and selective activation approach. The MRAP concepts page details pattern-based activation strategies and multiple policy coordination. Two how-to guides provide end-to-end workflows: one for users wanting to reduce CRD overhead through selective activation, and another for provider developers implementing safe-start capability. The user guide was tested with simulated MRDs to verify the activation workflow and troubleshooting steps. Signed-off-by: Nic Cope <[email protected]>
Signed-off-by: Nic Cope <[email protected]>
Without the quote it renders like a comment for some reason. Signed-off-by: Nic Cope <[email protected]>
Signed-off-by: Nic Cope <[email protected]>
tr0njavolta
reviewed
Aug 12, 2025
| {{</hint>}} | ||
|
|
||
| A `ManagedResourceDefinition` (MRD) is a lightweight abstraction over | ||
| Kubernetes CustomResourceDefinitions (CRDs) that enables selective activation of |
There was a problem hiding this comment.
Suggested change
| Kubernetes CustomResourceDefinitions (CRDs) that enables selective activation of | |
| Kubernetes `CustomResourceDefinitions` (CRDs) that enables selective activation of |
| <!-- vale Microsoft.HeadingAcronyms = YES --> | ||
| <!-- vale Google.Headings = YES --> | ||
|
|
||
| MRAPs contain activation patterns that match ManagedResourceDefinition names. |
There was a problem hiding this comment.
Suggested change
| MRAPs contain activation patterns that match ManagedResourceDefinition names. | |
| MRAPs contain activation patterns that match `ManagedResourceDefinition` names. |
| supported, consuming unnecessary cluster resources. | ||
|
|
||
| MRAPs solve this by providing pattern-based activation of | ||
| ManagedResourceDefinitions, letting you choose which provider resources to |
There was a problem hiding this comment.
Suggested change
| ManagedResourceDefinitions, letting you choose which provider resources to | |
| `ManagedResourceDefinitions`, letting you choose which provider resources to |
Comment on lines
+19
to
+25
| Large Crossplane providers can install 100+ managed resource CRDs, consuming | ||
| significant cluster resources even when you only need one or two resource | ||
| types. This guide shows how to use | ||
| [ManagedResourceDefinitions]({{<ref "../managed-resources/managed-resource-definitions">}}) | ||
| and | ||
| [ManagedResourceActivationPolicies]({{<ref "../managed-resources/managed-resource-activation-policies">}}) | ||
| to install only the provider resources you actually need. |
There was a problem hiding this comment.
Suggested change
| Large Crossplane providers can install 100+ managed resource CRDs, consuming | |
| significant cluster resources even when you only need one or two resource | |
| types. This guide shows how to use | |
| [ManagedResourceDefinitions]({{<ref "../managed-resources/managed-resource-definitions">}}) | |
| and | |
| [ManagedResourceActivationPolicies]({{<ref "../managed-resources/managed-resource-activation-policies">}}) | |
| to install only the provider resources you actually need. | |
| Large Crossplane providers can install 100+ managed resource CRDs, consuming | |
| significant cluster resources even when you only need one or two resource | |
| types. This guide shows how to use | |
| [`ManagedResourceDefinitions`]({{<ref "../managed-resources/managed-resource-definitions">}}) | |
| and | |
| [`ManagedResourceActivationPolicies`]({{<ref "../managed-resources/managed-resource-activation-policies">}}) | |
| to install only the provider resources you actually need. |
| - Basic familiarity with Kubernetes and Crossplane concepts | ||
|
|
||
| {{<hint "important">}} | ||
| ManagedResourceDefinitions and ManagedResourceActivationPolicies are alpha |
There was a problem hiding this comment.
Suggested change
| ManagedResourceDefinitions and ManagedResourceActivationPolicies are alpha | |
| `ManagedResourceDefinitions` and `ManagedResourceActivationPolicies` are alpha |
|
|
||
| ## What safe-start provides | ||
|
|
||
| safe-start changes how your provider handles CRD installation: |
There was a problem hiding this comment.
Suggested change
| safe-start changes how your provider handles CRD installation: | |
| Safe-start changes how your provider handles CRD installation: |
or safe-start? Not sure, but I didn't add suggestions for the other instances.
| - Higher memory usage and API server load | ||
|
|
||
| **With safe-start:** | ||
| - Providers create ManagedResourceDefinitions but CRDs only when activated |
There was a problem hiding this comment.
Suggested change
| - Providers create ManagedResourceDefinitions but CRDs only when activated | |
| - Providers create `ManagedResourceDefinitions` but CRDs only when activated |
|
|
||
| **With safe-start:** | ||
| - Providers create ManagedResourceDefinitions but CRDs only when activated | ||
| - Users activate only needed resources through ManagedResourceActivationPolicies |
There was a problem hiding this comment.
Suggested change
| - Users activate only needed resources through ManagedResourceActivationPolicies | |
| - Users activate only needed resources through `ManagedResourceActivationPolicies` |
|
|
||
| - Provider built with crossplane-runtime v2.0+ | ||
| - Understanding of | ||
| [ManagedResourceDefinitions]({{<ref "../managed-resources/managed-resource-definitions">}}) |
There was a problem hiding this comment.
Suggested change
| [ManagedResourceDefinitions]({{<ref "../managed-resources/managed-resource-definitions">}}) | |
| [`ManagedResourceDefinitions`]({{<ref "../managed-resources/managed-resource-definitions">}}) |
|
|
||
| ### Step 2: Add required imports | ||
|
|
||
| Update your main.go imports (see |
There was a problem hiding this comment.
Suggested change
| Update your main.go imports (see | |
| Update your `main.go` imports (see |
tr0njavolta
reviewed
Aug 12, 2025
| --- | ||
|
|
||
| This guide shows provider developers how to implement safe-start capability in | ||
| their Crossplane providers. safe-start enables |
There was a problem hiding this comment.
Suggested change
| their Crossplane providers. safe-start enables | |
| their Crossplane providers. `safe-start` enables |
or Safe-start?
I just chatted to @tr0njavolta on Slack and they don't feel strongly about the formatting changes. We're pretty inconsistent and I lean these days toward not using the backticks as much (e.g. see the Operations docs), so I'd prefer to avoid reformatting. I think separately we should probably agree on a style for this and do a pass over the whole docs. |
tr0njavolta
approved these changes
Aug 12, 2025
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Closes #958
Large Crossplane providers install hundreds of CRDs consuming significant API server resources, even when users only need a few resource types. The new alpha ManagedResourceDefinition (MRD) and ManagedResourceActivationPolicy
(MRAP) features in Crossplane v2.0+ solve this by enabling selective activation of provider resources, but lack user-facing documentation.
This change adds complete documentation covering both concepts and practical implementation. The MRD concepts page explains the CRD scaling problem and selective activation approach. The MRAP concepts page details pattern-based activation strategies and multiple policy coordination. Two how-to guides provide end-to-end workflows: one for users wanting to reduce CRD overhead through selective activation, and another for provider developers implementing
safe-start capability. The user guide was tested with simulated MRDs to verify the activation workflow and troubleshooting steps.