crossplane
/
docs
mirror of https://github.com/crossplane/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

linter 

Signed-off-by: Scott Nichols <n3wscott@upbound.io>
This commit is contained in:
Scott Nichols 2025-08-07 11:51:25 -07:00
parent 3fcc4473a9
commit e0a38db4d6
8 changed files with 210 additions and 185 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
content/master/get-started/get-started-with-mrds.md
View File

@ -36,7 +36,7 @@ that, by default, activates **all** managed resources with a `"*"` pattern.
{{< hint "important" >}} {{< hint "important" >}}
The default `"*"` activation pattern defeats the performance benefits of The default `"*"` activation pattern defeats the performance benefits of
SafeStart by activating all resources. For this tutorial, we work with the safe-start by activating all resources. For this tutorial, the guide works with the
default behavior, but production setups should use more selective activation. default behavior, but production setups should use more selective activation.
{{< /hint >}} {{< /hint >}}
@ -46,7 +46,7 @@ Check if you have a default activation policy:
kubectl get mrap crossplane-default-activation-policy -o yaml kubectl get mrap crossplane-default-activation-policy -o yaml
``` ```
You can modify the default activation policy directly: You can edit the default activation policy directly:
{{< tabs >}} {{< tabs >}}
{{< tab "Edit Existing Policy" >}} {{< tab "Edit Existing Policy" >}}
@ -62,7 +62,7 @@ kubectl patch mrap crossplane-default-activation-policy --type='merge' \
{{< hint "note" >}} {{< hint "note" >}}
Changes to the default policy are permanent. After the policy exists, Crossplane Changes to the default policy are permanent. After the policy exists, Crossplane
won't modify it, even if you change Helm values. doesn't change it, even if you change Helm values.
{{< /hint >}} {{< /hint >}}
{{< /tab >}} {{< /tab >}}
@ -85,9 +85,9 @@ Learn more about configuring default activation policies during installation
and best practices in the [MRD activation policies guide]({{< ref "../guides/mrd-activation-policies#default-activation-policy" >}}). and best practices in the [MRD activation policies guide]({{< ref "../guides/mrd-activation-policies#default-activation-policy" >}}).
{{< /hint >}} {{< /hint >}}
## Install a SafeStart provider ## Install a provider with safe-start capability
Now install a provider that supports SafeStart. This provider creates MRDs Now install a provider that supports safe-start. This provider creates MRDs
that activation policies control. that activation policies control.
```yaml ```yaml
@ -123,7 +123,7 @@ NAME INSTALLED HEALTHY PACKAGE
provider-aws True True xpkg.upbound.io/crossplane-contrib/provider-aws 2m provider-aws True True xpkg.upbound.io/crossplane-contrib/provider-aws 2m
``` ```
## Examine the MRDs ## Examine the managed resource definitions
List the MRDs created by the provider: List the MRDs created by the provider:
@ -146,7 +146,7 @@ clusters.eks.aws.crossplane.io Active 2m
# ... many more, all Active # ... many more, all Active
``` ```
The default policy activates all MRDs, so SafeStart providers behave like The default policy activates all MRDs, so safe-start providers behave like
traditional providers. traditional providers.
{{< /tab >}} {{< /tab >}}
@ -162,14 +162,14 @@ clusters.eks.aws.crossplane.io Inactive 2m
# ... many more, all Inactive # ... many more, all Inactive
``` ```
This demonstrates true SafeStart behavior where resources must be explicitly This demonstrates true safe-start behavior where resources must be explicitly
activated. activated.
{{< /tab >}} {{< /tab >}}
{{< /tabs >}} {{< /tabs >}}
{{< hint "note" >}} {{< hint "note" >}}
For the rest of this tutorial, we assume you have default activation For the rest of this tutorial, the guide assumes you have default activation
disabled to demonstrate selective activation. If you have default activation disabled to show selective activation. If you have default activation
enabled, the MRDs are already active. enabled, the MRDs are already active.
{{< /hint >}} {{< /hint >}}
@ -195,7 +195,7 @@ spec:
type: string type: string
``` ```
## Verify CRD creation behavior ## Verify resource creation behavior
The presence of CRDs depends on whether MRDs are active: The presence of CRDs depends on whether MRDs are active:
@ -207,8 +207,8 @@ Because MRDs are active due to the default `"*"` policy, CRDs exist:
kubectl get crds | grep aws.crossplane.io | wc -l kubectl get crds | grep aws.crossplane.io | wc -l
``` ```
This shows many CRDs (100+), demonstrating that active MRDs This shows 100+ CRDs, demonstrating that active MRDs
create CRDs immediately. create CRDs.
{{< /tab >}} {{< /tab >}}
{{< tab "With Disabled Default Activation" >}} {{< tab "With Disabled Default Activation" >}}
@ -288,9 +288,9 @@ dbinstances.rds.aws.crossplane.io Active 5m
# ... other RDS resources # ... other RDS resources
``` ```
## Verify CRDs are created ## Verify custom resource definition creation
Now that MRDs are active, CRDs should exist: Now that MRDs are active, CRDs exist:
```shell ```shell
kubectl get crds | grep -E "(instances.ec2|buckets.s3|rds)" | head -5 kubectl get crds | grep -E "(instances.ec2|buckets.s3|rds)" | head -5
@ -321,8 +321,8 @@ spec:
``` ```
{{< hint "note" >}} {{< hint "note" >}}
This example assumes you have AWS credentials configured. See the This example assumes you have AWS credentials configured. See
[AWS Provider documentation]({{< ref "../guides/aws-provider" >}}) for [ProviderConfig documentation]({{< ref "../managed-resources/managed-resources#providerconfigref" >}}) for
authentication setup. authentication setup.
{{< /hint >}} {{< /hint >}}
@ -428,16 +428,16 @@ status:
Compare the resource usage with traditional provider installation: Compare the resource usage with traditional provider installation:
**Without MRDs (traditional):** **Without MRDs (traditional):**
- All ~200 AWS CRDs created immediately - All ~200 AWS CRDs created when provider installs
- Higher memory usage in kube-apiserver - Higher memory usage in kube-apiserver
- Longer provider installation time - Longer provider installation time
**With MRDs and selective activation:** **With MRDs and selective activation:**
- Only activated CRDs created (~10-20 in this example) - Only activated CRDs created (10 to 20 in this example)
- Lower memory footprint - Lower memory footprint
- Faster resource discovery and management - Faster resource discovery and management
Check the number of AWS CRDs currently in your cluster: Check the number of AWS CRDs in your cluster:
```shell ```shell
kubectl get crds | grep aws.crossplane.io | wc -l kubectl get crds | grep aws.crossplane.io | wc -l
@ -463,7 +463,7 @@ spec:
EOF EOF
``` ```
The activations from both policies are combined, giving you fine-grained Both policies combine their activations, giving you fine-grained
control over resource availability. control over resource availability.
## Clean up ## Clean up
@ -522,9 +522,9 @@ Now that you understand MRDs and activation policies, you can:
* **Optimize cluster performance** by using selective activation * **Optimize cluster performance** by using selective activation
* **Improve resource discovery** through MRD connection details documentation * **Improve resource discovery** through MRD connection details documentation
* **Implement environment-specific policies** for different deployment stages * **Implement environment-specific policies** for different deployment stages
* **Plan provider adoption** using SafeStart-capable providers * **Plan provider adoption** using safe-start-capable providers
Learn more about: Learn more about:
* [MRD activation policies best practices]({{< ref "../guides/mrd-activation-policies" >}}) - Comprehensive guide including default policy configuration * [MRD activation policies best practices]({{< ref "../guides/mrd-activation-policies" >}}) - Comprehensive guide including default policy configuration
* [Managed Resource Definitions concepts]({{< ref "managed-resource-definitions" >}}) * [Managed Resource Definitions concepts]({{< ref "managed-resource-definitions" >}})
* [Provider capabilities and SafeStart]({{< ref "../packages/provider-capabilities" >}}) * [Provider capabilities and safe-start]({{< ref "../packages/provider-capabilities" >}})

124
content/master/guides/implementing-safestart.md
View File

@ -1,36 +1,36 @@
--- ---
title: Implementing SafeStart in Providers title: Implementing safe-start in Providers
weight: 160 weight: 160
description: Guide for provider developers to implement SafeStart capability description: Guide for provider developers to implement safe-start capability
--- ---
This guide shows provider developers how to implement SafeStart capability in This guide shows provider developers how to implement safe-start capability in
their Crossplane providers. SafeStart enables selective resource activation their Crossplane providers. safe-start enables selective resource activation
through Managed Resource Definitions (MRDs), improving performance and resource through Managed Resource Definitions (MRDs), improving performance and resource
management. management.
{{< hint "important" >}} {{< hint "important" >}}
SafeStart requires Crossplane v2.0+ and involves significant provider changes. safe-start requires Crossplane v2.0+ and involves significant provider changes.
Plan for breaking changes and thorough testing before implementing. Plan for breaking changes and thorough testing before implementing.
{{< /hint >}} {{< /hint >}}
## What SafeStart provides ## What safe-start provides
SafeStart transforms how your provider handles resource installation: safe-start transforms how your provider handles resource installation:
**Without SafeStart:** **Without safe-start:**
- All managed resources become CRDs immediately when provider installs - All managed resources become CRDs when provider installs
- Users get all ~200 AWS resources even if they need only 5 - Users get all ~200 AWS resources even if they need only 5
- Higher memory usage and slower API server responses - Higher memory usage and slower API server responses
**With SafeStart:** **With safe-start:**
- All managed resources become inactive MRDs when provider installs - All managed resources become inactive MRDs when provider installs
- Users activate only needed resources through policies - Users activate only needed resources through policies
- Lower resource overhead and better performance - Lower resource overhead and better performance
## Prerequisites ## Prerequisites
Before implementing SafeStart, ensure you have: Before implementing safe-start, ensure you have:
* Provider built with Crossplane v2.0+ runtime * Provider built with Crossplane v2.0+ runtime
* Understanding of [MRDs and activation policies]({{< ref "mrd-activation-policies" >}}) * Understanding of [MRDs and activation policies]({{< ref "mrd-activation-policies" >}})
@ -39,9 +39,9 @@ Before implementing SafeStart, ensure you have:
## Implementation steps ## Implementation steps
### Step 1: Update provider metadata ### Step 1: Update Provider Metadata
Declare SafeStart capability in your provider package metadata: Declare safe-start capability in your provider package metadata:
```yaml ```yaml
apiVersion: meta.pkg.crossplane.io/v1 apiVersion: meta.pkg.crossplane.io/v1
@ -51,15 +51,15 @@ metadata:
spec: spec:
package: registry.example.com/provider-example:v1.0.0 package: registry.example.com/provider-example:v1.0.0
capabilities: capabilities:
- name: SafeStart - name: safe-start
``` ```
{{< hint "tip" >}} {{< hint "tip" >}}
Crossplane supports flexible capability matching. `SafeStart`, `safestart`, Crossplane supports flexible capability matching. `safe-start`, `safestart`,
and `safe-start` are all recognized as the same capability. and `safe-start` are all recognized as the same capability.
{{< /hint >}} {{< /hint >}}
### Step 2: Enhance MRD generation ### Step 2: Enhance managed resource definition generation
Update your MRD generation to include connection details documentation: Update your MRD generation to include connection details documentation:
@ -81,7 +81,7 @@ type ManagedResourceDefinitionSpec struct {
Names Names `json:"names"` Names Names `json:"names"`
Scope string `json:"scope"` Scope string `json:"scope"`
// SafeStart-specific fields // safe-start-specific fields
ConnectionDetails []ConnectionDetail `json:"connectionDetails,omitempty"` ConnectionDetails []ConnectionDetail `json:"connectionDetails,omitempty"`
State ResourceState `json:"state,omitempty"` State ResourceState `json:"state,omitempty"`
} }
@ -103,10 +103,10 @@ func GetProvider() *ujconfig.Provider {
ujconfig.WithIncludeList(ExternalNameConfigured()), ujconfig.WithIncludeList(ExternalNameConfigured()),
ujconfig.WithDefaultResourceOptions( ujconfig.WithDefaultResourceOptions(
ExternalNameConfigurations(), ExternalNameConfigurations(),
SafeStartConfiguration(), // Add SafeStart config safe-startConfiguration(), // Add safe-start config
)) ))
// Configure SafeStart for specific resources // Configure safe-start for specific resources
for _, configure := range []func(provider *ujconfig.Provider){ for _, configure := range []func(provider *ujconfig.Provider){
configureConnectionDetails, configureConnectionDetails,
configureMRDDocumentation, configureMRDDocumentation,
@ -150,7 +150,7 @@ func configureConnectionDetails(p *ujconfig.Provider) {
### Step 3: Handle namespaced resources ### Step 3: Handle namespaced resources
SafeStart works best with namespaced managed resources. Update your resources safe-start works best with namespaced managed resources. Update your resources
to support both cluster and namespaced scopes: to support both cluster and namespaced scopes:
```go ```go
@ -180,9 +180,9 @@ type ClusterDatabase struct {
} }
``` ```
### Step 4: Update RBAC permissions ### Step 4: Update RBAC Permissions
SafeStart providers need additional permissions to manage CRDs dynamically: safe-start providers need extra permissions to manage CRDs dynamically:
```yaml ```yaml
apiVersion: rbac.authorization.k8s.io/v1 apiVersion: rbac.authorization.k8s.io/v1
@ -198,7 +198,7 @@ rules:
resources: ["*"] resources: ["*"]
verbs: ["*"] verbs: ["*"]
# Additional SafeStart permissions # safe-start permissions
- apiGroups: ["apiextensions.k8s.io"] - apiGroups: ["apiextensions.k8s.io"]
resources: ["customresourcedefinitions"] resources: ["customresourcedefinitions"]
verbs: ["get", "list", "watch", "create", "update", "patch", "delete"] verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
@ -207,7 +207,7 @@ rules:
verbs: ["get", "list", "watch", "update", "patch"] verbs: ["get", "list", "watch", "update", "patch"]
``` ```
### Step 5: Implement MRD controller logic ### Step 5: Implement managed resource definition controller logic
Add controller logic to handle MRD activation and CRD lifecycle: Add controller logic to handle MRD activation and CRD lifecycle:
@ -280,7 +280,7 @@ func (r *MRDReconciler) createCRD(ctx context.Context, mrd *xpv1alpha1.ManagedRe
} }
``` ```
### Step 6: Update build and CI processes ### Step 6: Update build and continuous integration processes
Update your build process to generate MRDs alongside CRDs: Update your build process to generate MRDs alongside CRDs:
@ -306,18 +306,18 @@ build-package: generate
mkdir -p package/ mkdir -p package/
cp package/crds/*.yaml package/ cp package/crds/*.yaml package/
cp package/mrds/*.yaml package/ cp package/mrds/*.yaml package/
echo "# Package metadata with SafeStart capability" > package/provider.yaml echo "# Package metadata with safe-start capability" > package/provider.yaml
echo "apiVersion: meta.pkg.crossplane.io/v1" >> package/provider.yaml echo "apiVersion: meta.pkg.crossplane.io/v1" >> package/provider.yaml
echo "kind: Provider" >> package/provider.yaml echo "kind: Provider" >> package/provider.yaml
echo "spec:" >> package/provider.yaml echo "spec:" >> package/provider.yaml
echo " capabilities:" >> package/provider.yaml echo " capabilities:" >> package/provider.yaml
echo " - name: SafeStart" >> package/provider.yaml echo " - name: safe-start" >> package/provider.yaml
``` ```
{{< /tab >}} {{< /tab >}}
{{< tab "GitHub Actions" >}} {{< tab "GitHub Actions" >}}
```yaml ```yaml
name: Build and Test SafeStart Provider name: Build and Test safe-start Provider
on: on:
push: push:
@ -351,13 +351,13 @@ jobs:
echo "Generated MRDs:" echo "Generated MRDs:"
ls -la package/mrds/ ls -la package/mrds/
- name: Test SafeStart Integration - name: Test safe-start Integration
run: | run: |
# Start local cluster # Start local cluster
make kind-up make kind-up
make install-crossplane-v2 make install-crossplane-v2
# Install provider with SafeStart # Install provider with safe-start
make install-provider make install-provider
# Verify MRDs created but inactive # Verify MRDs created but inactive
@ -396,7 +396,7 @@ spec:
plural: databases plural: databases
scope: Namespaced scope: Namespaced
# SafeStart-specific fields # safe-start-specific fields
connectionDetails: connectionDetails:
- name: endpoint - name: endpoint
description: "The RDS instance connection endpoint" description: "The RDS instance connection endpoint"
@ -427,7 +427,7 @@ spec:
# ... rest of CRD spec # ... rest of CRD spec
``` ```
## Testing SafeStart implementation ## Testing safe-start implementation
### Unit testing ### Unit testing
@ -435,7 +435,7 @@ Test your MRD generation and controller logic:
```go ```go
func TestMRDGeneration(t *testing.T) { func TestMRDGeneration(t *testing.T) {
// Test that MRDs are generated with correct connection details // Test MRD generation with correct connection details
mrd := generateMRDForResource("Database") mrd := generateMRDForResource("Database")
assert.Equal(t, "databases.rds.aws.example.io", mrd.Name) assert.Equal(t, "databases.rds.aws.example.io", mrd.Name)
@ -463,7 +463,7 @@ func TestMRDActivation(t *testing.T) {
assert.NoError(t, err) assert.NoError(t, err)
assert.False(t, result.Requeue) assert.False(t, result.Requeue)
// Verify CRD was created // Verify CRD creation
crd := &apiextv1.CustomResourceDefinition{} crd := &apiextv1.CustomResourceDefinition{}
err = fakeClient.Get(ctx, types.NamespacedName{Name: "databases.rds.aws.example.io"}, crd) err = fakeClient.Get(ctx, types.NamespacedName{Name: "databases.rds.aws.example.io"}, crd)
assert.NoError(t, err) assert.NoError(t, err)
@ -472,13 +472,13 @@ func TestMRDActivation(t *testing.T) {
### Integration testing ### Integration testing
Test SafeStart behavior in a real cluster: Test safe-start behavior in a real cluster:
```bash ```shell
#!/bin/bash #!/bin/bash
set -e set -e
echo "Starting SafeStart integration test..." echo "Starting safe-start integration test..."
# Install Crossplane v2.0 # Install Crossplane v2.0
kubectl create namespace crossplane-system kubectl create namespace crossplane-system
@ -487,7 +487,7 @@ helm install crossplane crossplane-stable/crossplane \
--version v2.0.0 \ --version v2.0.0 \
--wait --wait
# Install provider with SafeStart # Install provider with safe-start
kubectl apply -f - <<EOF kubectl apply -f - <<EOF
apiVersion: pkg.crossplane.io/v1 apiVersion: pkg.crossplane.io/v1
kind: Provider kind: Provider
@ -496,7 +496,7 @@ metadata:
spec: spec:
package: registry.example.com/provider-example:latest package: registry.example.com/provider-example:latest
capabilities: capabilities:
- name: SafeStart - name: safe-start
EOF EOF
# Wait for provider installation # Wait for provider installation
@ -553,24 +553,24 @@ EOF
# Verify resource creation # Verify resource creation
kubectl wait --for=condition=Ready database/test-db --timeout=300s --namespace default kubectl wait --for=condition=Ready database/test-db --timeout=300s --namespace default
echo "✓ SafeStart integration test passed" echo "✓ safe-start integration test passed"
``` ```
## Migration considerations ## Migration considerations
### For existing users ### For existing users
When you add SafeStart to an existing provider: When you add safe-start to an existing provider:
**Breaking change considerations:** **Breaking change considerations:**
- Existing installations will continue working (backward compatibility) - Existing installations continue to work (backward compatibility)
- New installations will have inactive MRDs by default - New installations have inactive MRDs by default
- Users need activation policies for new installations - Users need activation policies for new installations
**Migration strategy:** **Migration strategy:**
```yaml ```yaml
# Provide migration documentation like: # Provide migration documentation like:
# For users upgrading to SafeStart-enabled provider v2.0: # For users upgrading to safe-start-enabled provider v2.0:
# 1. Existing resources continue working unchanged # 1. Existing resources continue working unchanged
# 2. For new installations, create activation policy: # 2. For new installations, create activation policy:
@ -585,31 +585,33 @@ spec:
### Version compatibility matrix ### Version compatibility matrix
Document version compatibility clearly: Document version compatibility:
| Provider Version | Crossplane Version | SafeStart Support | Notes | | Provider Version | Crossplane Version | safe-start Support | Notes |
|------------------|-------------------|------------------|-------| |------------------|-------------------|------------------|-------|
| v1.x | v1.x - v2.x | No | Legacy CRD-only mode | | v1.x | v1.x - v2.x | No | Legacy CRD-only mode |
| v2.0 | v2.0+ | Yes | Full SafeStart support | | v2.0 | v2.0+ | Yes | Full safe-start support |
| v2.1 | v2.0+ | Yes | Enhanced MRD features | | v2.1 | v2.0+ | Yes | Enhanced MRD features |
## Documentation requirements ## Documentation requirements
Update your provider documentation to include: Update your provider documentation to include:
<!-- vale Google.Headings = NO -->
### README updates ### README updates
<!-- vale Google.Headings = YES -->
```markdown ```markdown
# Provider Example # Provider Example
## SafeStart Support ## safe-start Support
This provider supports SafeStart capability, which provides: This provider supports safe-start capability, which provides:
- Selective resource activation - Selective resource activation
- Improved performance for large providers - Improved performance for large providers
- Connection details documentation - Connection details documentation
### Quick Start with SafeStart ### Quick Start with safe-start
1. Install the provider: 1. Install the provider:
```yaml ```yaml
@ -633,10 +635,10 @@ spec:
- "*.s3.aws.example.io" - "*.s3.aws.example.io"
``` ```
3. Create resources normally - only activated resources work. 3. Create resources - only activated resources work.
``` ```
### Connection details documentation ### Connection Details Documentation
Document what connection details each resource provides: Document what connection details each resource provides:
@ -658,10 +660,10 @@ Document what connection details each resource provides:
## Troubleshooting ## Troubleshooting
### Common issues ### Common Issues
**MRDs not activating:** **MRDs not activating:**
```bash ```shell
# Check activation policy exists and matches # Check activation policy exists and matches
kubectl get mrap kubectl get mrap
kubectl describe mrap my-policy kubectl describe mrap my-policy
@ -672,7 +674,7 @@ kubectl describe mrd my-resource.provider.example.io
``` ```
**CRDs not created:** **CRDs not created:**
```bash ```shell
# Check MRD controller logs # Check MRD controller logs
kubectl logs -n crossplane-system deployment/provider-example kubectl logs -n crossplane-system deployment/provider-example
@ -681,7 +683,7 @@ kubectl auth can-i create customresourcedefinitions --as=system:serviceaccount:c
``` ```
**Resource creation fails:** **Resource creation fails:**
```bash ```shell
# Verify MRD is active # Verify MRD is active
kubectl get mrd my-resource.provider.example.io -o jsonpath='{.spec.state}' kubectl get mrd my-resource.provider.example.io -o jsonpath='{.spec.state}'
@ -702,13 +704,13 @@ kubectl describe my-resource my-instance
### User experience ### User experience
- Include helpful error messages when resources aren't activated - Include helpful error messages when resources aren't activated
- Provide clear migration guides for existing users - Provide clear migration guides for existing users
- Document connection details thoroughly - Document connection details
### Testing strategy ### Testing strategy
- Test both with and without SafeStart in CI - Test both with and without safe-start in CI
- Verify activation/deactivation cycles work correctly - Verify activation/deactivation cycles work
- Test resource creation after activation - Test resource creation after activation
SafeStart provides significant value for large providers and improves the safe-start provides significant value for large providers and improves the
overall Crossplane user experience. Following this guide helps ensure your Crossplane user experience. Following this guide helps ensure your
implementation is robust, well-documented, and user-friendly. implementation is robust, well-documented, and user-friendly.

46
content/master/guides/mrd-activation-policies.md
View File

@ -1,5 +1,5 @@
--- ---
title: Writing MRD Activation Policies title: Writing MRD activation policies
weight: 150 weight: 150
description: Learn how to create effective activation policies for managed resources description: Learn how to create effective activation policies for managed resources
--- ---
@ -15,7 +15,7 @@ Crossplane automatically creates a default ManagedResourceActivationPolicy when
installed. Understanding and configuring this default policy is crucial for installed. Understanding and configuring this default policy is crucial for
effective MRD management. effective MRD management.
### What is the default MRAP? ### What's the default activation policy
The default MRAP is automatically created by Crossplane and activates managed The default MRAP is automatically created by Crossplane and activates managed
resources according to configurable patterns. By default, it uses a wildcard resources according to configurable patterns. By default, it uses a wildcard
@ -32,7 +32,7 @@ spec:
``` ```
{{< hint "important" >}} {{< hint "important" >}}
The default `"*"` pattern means SafeStart providers will still create all CRDs, The default `"*"` pattern means safe-start providers still create all CRDs,
defeating the performance benefits. Most users should customize this behavior. defeating the performance benefits. Most users should customize this behavior.
{{< /hint >}} {{< /hint >}}
@ -86,13 +86,13 @@ provider:
### Modifying the default policy after installation ### Modifying the default policy after installation
The default activation policy can be modified directly and changes will persist: You can change the default activation policy directly and changes persist:
```shell ```shell
# View current default policy # View current default policy
kubectl get mrap crossplane-default-activation-policy -o yaml kubectl get mrap crossplane-default-activation-policy -o yaml
# Permanently modify to disable default activation # Permanently change to disable default activation
kubectl patch mrap crossplane-default-activation-policy --type='merge' \ kubectl patch mrap crossplane-default-activation-policy --type='merge' \
-p='{"spec":{"activations":["nonexistent.example.com"]}}' -p='{"spec":{"activations":["nonexistent.example.com"]}}'
@ -105,8 +105,8 @@ kubectl delete mrap crossplane-default-activation-policy
``` ```
{{< hint "note" >}} {{< hint "note" >}}
**Changes to the default policy are permanent.** Once the default MRAP exists, **Changes to the default policy are permanent.** After the default MRAP exists,
Crossplane will not modify it. The Helm chart `provider.defaultActivations` Crossplane doesn't change it. The Helm chart `provider.defaultActivations`
value is only used when creating the policy if it doesn't already exist. value is only used when creating the policy if it doesn't already exist.
{{< /hint >}} {{< /hint >}}
@ -161,12 +161,12 @@ EOF
- **Performance**: Only activates resources you actually use - **Performance**: Only activates resources you actually use
- **Security**: Principle of least privilege for resource access - **Security**: Principle of least privilege for resource access
- **Clarity**: Explicit about which resources are available - **Clarity**: Explicit about which resources are available
- **Maintainability**: Easier to understand and modify activation patterns - **Maintainability**: Easier to understand and change activation patterns
## Policy basics ## Policy basics
Beyond the default policy, you can create custom activation policies that Beyond the default policy, you can create custom activation policies that
specify which MRDs should be activated using pattern matching: specify which MRDs should activate using pattern matching:
```yaml ```yaml
apiVersion: apiextensions.crossplane.io/v1alpha1 apiVersion: apiextensions.crossplane.io/v1alpha1
@ -200,7 +200,7 @@ spec:
``` ```
Use exact matching when: Use exact matching when:
* You know exactly which resources you need * You know which resources you need
* You want fine-grained control over individual resources * You want fine-grained control over individual resources
* Security policies require explicit resource approval * Security policies require explicit resource approval
@ -234,7 +234,7 @@ spec:
``` ```
Use provider-wide activation when: Use provider-wide activation when:
* You're migrating from non-SafeStart providers * You're migrating from non-safe-start providers
* Your applications use diverse resources from a single provider * Your applications use diverse resources from a single provider
* Development environments need broad resource access * Development environments need broad resource access
@ -267,7 +267,7 @@ spec:
### Staging environment ### Staging environment
Include additional resources for integration testing: Include resources for integration testing:
```yaml ```yaml
apiVersion: apiextensions.crossplane.io/v1alpha1 apiVersion: apiextensions.crossplane.io/v1alpha1
@ -396,9 +396,9 @@ spec:
- "*.insights.azure.crossplane.io" - "*.insights.azure.crossplane.io"
``` ```
### Application team ### App team
Resources needed by application developers: Resources needed by app developers:
```yaml ```yaml
apiVersion: apiextensions.crossplane.io/v1alpha1 apiVersion: apiextensions.crossplane.io/v1alpha1
@ -451,8 +451,8 @@ spec:
- "*.lambda.aws.crossplane.io" - "*.lambda.aws.crossplane.io"
``` ```
You can delete the `advanced-resources` policy to quickly deactivate optional You can delete the `advanced-resources` policy to deactivate optional
resources while keeping base functionality. resources while keeping base capability.
### Feature flag patterns ### Feature flag patterns
@ -477,7 +477,7 @@ spec:
### Check activation status ### Check activation status
Verify your policies are working correctly: Verify your policies work:
```shell ```shell
# List all activation policies # List all activation policies
@ -495,7 +495,7 @@ kubectl get mrds -l crossplane.io/provider=provider-aws --field-selector spec.st
### Test resource creation ### Test resource creation
Verify activated resources work correctly: Verify activated resources work:
```shell ```shell
# Try creating a managed resource # Try creating a managed resource
@ -523,7 +523,7 @@ Common issues and solutions:
kubectl get mrd my-resource.provider.example.com kubectl get mrd my-resource.provider.example.com
kubectl describe mrd my-resource.provider.example.com kubectl describe mrd my-resource.provider.example.com
# Verify policy is matching correctly # Verify policy is matching
kubectl get mrap my-policy -o yaml | grep -A20 status kubectl get mrap my-policy -o yaml | grep -A20 status
# Look for controller errors # Look for controller errors
@ -551,7 +551,7 @@ spec:
### Policy consolidation ### Policy consolidation
Multiple small policies vs. few large policies: Multiple small policies vs. large policies:
{{< tabs >}} {{< tabs >}}
{{< tab "Multiple Small Policies (Recommended)" >}} {{< tab "Multiple Small Policies (Recommended)" >}}
@ -599,7 +599,9 @@ spec:
## Policy lifecycle management ## Policy lifecycle management
<!-- vale Google.Headings = NO -->
### GitOps workflow ### GitOps workflow
<!-- vale Google.Headings = YES -->
Store activation policies in Git for proper change management: Store activation policies in Git for proper change management:
@ -687,5 +689,5 @@ spec:
# ... composition definition # ... composition definition
``` ```
This helps operators understand which activation policies are needed for This helps operators understand which activation policies you need for
specific compositions to work correctly. specific compositions to work.

60
content/master/managed-resources/managed-resource-definitions.md
View File

@ -12,9 +12,11 @@ installation and better documentation of managed resources.
MRDs are available in Crossplane v2.0+ as an alpha feature. MRDs are available in Crossplane v2.0+ as an alpha feature.
{{< /hint >}} {{< /hint >}}
## What are managed resource definitions? <!-- vale write-good.Passive = NO -->
## What are managed resource definitions
<!-- vale write-good.Passive = YES -->
A Managed Resource Definition (MRD) is essentially a CRD with additional A Managed Resource Definition (MRD) is essentially a CRD with extra
metadata that provides: metadata that provides:
* **Connection details schema** - Documents what connection details the * **Connection details schema** - Documents what connection details the
@ -25,7 +27,7 @@ metadata that provides:
available available
**Every managed resource in a provider package has an associated MRD.** The MRD **Every managed resource in a provider package has an associated MRD.** The MRD
contains the same schema as the CRD, plus additional Crossplane-specific contains the same schema as the CRD, plus extra Crossplane-specific
metadata. metadata.
```mermaid ```mermaid
@ -43,7 +45,7 @@ flowchart LR
style crd fill:#f3e5f5 style crd fill:#f3e5f5
``` ```
## Why use managed resource definitions? ## Why use managed resource definitions
MRDs solve several challenges with traditional provider packages: MRDs solve several challenges with traditional provider packages:
@ -69,7 +71,7 @@ needs the full set.
**MRDs enable environment-specific resource activation** through policies. **MRDs enable environment-specific resource activation** through policies.
## How MRDs work ## How managed resource definitions work
When you install a provider package, Crossplane creates: When you install a provider package, Crossplane creates:
@ -78,7 +80,7 @@ When you install a provider package, Crossplane creates:
3. **Activation policies** - ManagedResourceActivationPolicy controls which 3. **Activation policies** - ManagedResourceActivationPolicy controls which
MRDs become active MRDs become active
### MRD lifecycle ### Managed resource definition lifecycle
```mermaid ```mermaid
flowchart TD flowchart TD
@ -99,7 +101,7 @@ flowchart TD
style inactive fill:#ffcdd2 style inactive fill:#ffcdd2
``` ```
### MRD states ### Managed resource definition states
MRDs can be in one of two states: MRDs can be in one of two states:
@ -109,7 +111,7 @@ MRDs can be in one of two states:
You can change an MRD's state by: You can change an MRD's state by:
* Editing the MRD directly (`spec.state: Active`) * Editing the MRD directly (`spec.state: Active`)
* Using a ManagedResourceActivationPolicy * Using a ManagedResourceActivationPolicy
* Provider package capabilities (SafeStart) * Provider package capabilities (safe-start)
## Connection details schema ## Connection details schema
@ -142,13 +144,15 @@ spec:
The `connectionDetails` field documents: The `connectionDetails` field documents:
* **Connection detail names** - What keys appear in connection secrets * **Connection detail names** - What keys appear in connection secrets
* **Descriptions** - What each connection detail contains * **Descriptions** - What each connection detail contains
* **Types** - The data type of each detail * **Types** - The data each detail's type
* **Source keys** - How details map from provider responses * **Source keys** - How details map from provider responses
<!-- vale Google.Headings = NO -->
## Managed Resource Activation Policy ## Managed Resource Activation Policy
<!-- vale Google.Headings = YES -->
ManagedResourceActivationPolicy (MRAP) provides pattern-based control over ManagedResourceActivationPolicy (MRAP) provides pattern-based control over
which MRDs become active. This is more scalable than manually activating which MRDs become active. Pattern-based control is more scalable than manually activating
individual MRDs. individual MRDs.
```yaml ```yaml
@ -171,44 +175,48 @@ MRAP supports several activation patterns:
* **Wildcard prefix**: `*.rds.aws.crossplane.io` (all RDS resources) * **Wildcard prefix**: `*.rds.aws.crossplane.io` (all RDS resources)
* **Provider wildcard**: `*.aws.crossplane.io` (all AWS resources) * **Provider wildcard**: `*.aws.crossplane.io` (all AWS resources)
Multiple MRAPs can exist, and their activations are combined. Multiple MRAPs can exist, and their activations combine.
## Provider capabilities ## Provider capabilities
Providers can declare capabilities that affect MRD behavior: Providers can declare capabilities that affect MRD behavior:
### SafeStart capability <!-- vale Google.Headings = NO -->
Providers with the `SafeStart` capability start with all MRDs inactive by ### safe-start capability
<!-- vale Google.Headings = YES -->
Providers with the `safe-start` capability start with all MRDs inactive by
default. This prevents performance issues when installing large providers. default. This prevents performance issues when installing large providers.
Without SafeStart, all MRDs are active by default for backward compatibility. Without safe-start, all MRDs are active by default for backward compatibility.
```yaml ```yaml
# In provider package metadata # In provider package metadata
spec: spec:
capabilities: capabilities:
- name: SafeStart - name: safe-start
``` ```
{{< hint "note" >}} {{< hint "note" >}}
Implementing SafeStart requires significant provider code changes. Provider Implementing safe-start requires significant provider code changes. Provider
developers should follow the developers should follow the
[SafeStart implementation guide]({{< ref "../guides/implementing-safestart" >}}) [safe-start implementation guide]({{< ref "../guides/implementing-safestart" >}})
for detailed technical requirements and examples. for detailed technical requirements and examples.
{{< /hint >}} {{< /hint >}}
### SafeStart implementation examples <!-- vale Google.Headings = NO -->
### safe-start implementation examples
<!-- vale Google.Headings = YES -->
The Crossplane community has implemented SafeStart in several providers: The Crossplane community has implemented safe-start in several providers:
* **provider-nop** - [Reference implementation](https://github.com/crossplane-contrib/provider-nop/pull/24) * **provider-nop** - [Reference implementation](https://github.com/crossplane-contrib/provider-nop/pull/24)
showing SafeStart integration with both namespaced and cluster-scoped resources showing safe-start integration with both namespaced and cluster-scoped resources
* **provider-aws** - Large provider demonstrating SafeStart performance benefits * **provider-aws** - Large provider demonstrating safe-start performance benefits
These implementations provide real-world examples of: These implementations provide real-world examples of:
- MRD controller integration - MRD controller integration
- Build process modifications - Build process modifications
- Testing strategies for SafeStart behavior - Testing strategies for safe-start behavior
- Migration approaches for existing users - Migration approaches for existing users
## Key concepts ## Key concepts
@ -217,9 +225,9 @@ Understanding these terms helps when working with MRDs:
* **MRD** - The definition that may or may not have an active CRD * **MRD** - The definition that may or may not have an active CRD
* **MRAP** - Policy that controls which MRDs become active * **MRAP** - Policy that controls which MRDs become active
* **Active state** - MRD has an underlying CRD, resources can be created * **Active state** - MRD has an underlying CRD, you can create resources
* **Inactive state** - No CRD exists, resource creation fails * **Inactive state** - No CRD exists, resource creation fails
* **SafeStart** - Provider capability that defaults MRDs to inactive * **safe-start** - Provider capability that defaults MRDs to inactive
* **Connection details schema** - Documentation of what connection details * **Connection details schema** - Documentation of what connection details
a managed resource provides a managed resource provides
@ -228,10 +236,10 @@ Understanding these terms helps when working with MRDs:
MRDs integrate with existing Crossplane concepts: MRDs integrate with existing Crossplane concepts:
* **Providers** - Create MRDs when installed * **Providers** - Create MRDs when installed
* **Managed resources** - Can only be created when their MRD is active * **Managed resources** - You can only create when their MRD is active
* **Compositions** - Can reference both active and inactive managed resources * **Compositions** - Can reference both active and inactive managed resources
(composition validation occurs at render time) (composition validation occurs at render time)
* **Claims** - Work normally once the underlying managed resources are active * **Claims** - Work after the underlying managed resources are active
MRDs are backward compatible. Existing providers and compositions continue to MRDs are backward compatible. Existing providers and compositions continue to
work without modification. work without modification.

98
content/master/packages/provider-capabilities.md
View File

@ -5,14 +5,14 @@ description: Understand provider capabilities and how they affect resource behav
--- ---
Provider capabilities are declarative features that providers can implement to Provider capabilities are declarative features that providers can implement to
modify their behavior and integration with Crossplane. Capabilities enable change their behavior and integration with Crossplane. Capabilities enable
providers to opt into new features while maintaining backward compatibility. providers to opt into new features while maintaining backward compatibility.
## What are provider capabilities? ## What are provider capabilities
Provider capabilities are metadata declarations in provider packages that tell Provider capabilities are metadata declarations in provider packages that tell
Crossplane how the provider should behave. They're similar to feature flags Crossplane how the provider should behave. They're like feature flags
but are declared at the package level. but you declare them at the package level.
```yaml ```yaml
# In provider package metadata # In provider package metadata
@ -22,7 +22,7 @@ metadata:
name: provider-aws name: provider-aws
spec: spec:
capabilities: capabilities:
- name: SafeStart - name: safe-start
- name: CustomCapability - name: CustomCapability
``` ```
@ -31,43 +31,45 @@ and managing the provider.
## Available capabilities ## Available capabilities
### SafeStart <!-- vale Google.Headings = NO -->
### safe-start
<!-- vale Google.Headings = YES -->
The `SafeStart` capability changes how Managed Resource Definitions (MRDs) are The `safe-start` capability changes how Managed Resource Definitions (MRDs) are
activated when the provider is installed. activated when you install the provider.
**Without SafeStart:** **Without safe-start:**
- All MRDs are automatically activated - All MRDs are automatically activated
- All corresponding CRDs are created immediately - Crossplane creates all corresponding CRDs when provider installs
- Compatible with legacy providers and existing workflows - Compatible with legacy providers and existing workflows
**With SafeStart:** **With safe-start:**
- All MRDs start in `Inactive` state - All MRDs start in `Inactive` state
- No CRDs are created until MRDs are explicitly activated - No CRDs until you explicitly activate MRDs
- Reduces initial resource overhead and improves performance - Reduces initial resource overhead and improves performance
```yaml ```yaml
spec: spec:
capabilities: capabilities:
- name: SafeStart - name: safe-start
``` ```
{{< hint "tip" >}} {{< hint "tip" >}}
SafeStart is particularly valuable for large providers like AWS that define safe-start is valuable for large providers like AWS that define
hundreds of managed resources. It prevents performance issues by avoiding the hundreds of managed resources. It prevents performance issues by avoiding the
creation of unused CRDs. creation of unused CRDs.
{{< /hint >}} {{< /hint >}}
#### When to use SafeStart #### When to use safe-start
Use SafeStart when: Use safe-start when:
* Your provider defines many managed resources (>50) * Your provider defines over 50 managed resources
* Users typically need only a subset of available resources * Users typically need only a subset of available resources
* Installation performance and resource usage are concerns * Installation performance and resource usage are concerns
* You want to provide better resource discovery through MRDs * You want to provide better resource discovery through MRDs
Don't use SafeStart when: Don't use safe-start when:
* Your provider has few managed resources (<20) * Your provider has under 20 managed resources
* Most users need all available resources * Most users need all available resources
* Backward compatibility with existing installations is critical * Backward compatibility with existing installations is critical
* Your users aren't ready to manage resource activation * Your users aren't ready to manage resource activation
@ -76,8 +78,8 @@ Don't use SafeStart when:
Crossplane supports flexible matching for capability names: Crossplane supports flexible matching for capability names:
* **Exact match**: `SafeStart` * **Exact match**: `safe-start`
* **Case variations**: `safestart`, `safe-start`, `SafeStart` * **Case variations**: `safestart`, `safe-start`, `safe-start`
* **Fuzzy matching**: Handles common spelling variations * **Fuzzy matching**: Handles common spelling variations
This flexibility prevents issues when providers use different naming conventions. This flexibility prevents issues when providers use different naming conventions.
@ -90,7 +92,7 @@ The provider installation process changes based on declared capabilities:
flowchart TD flowchart TD
install[Install Provider Package] install[Install Provider Package]
readCaps[Read Capabilities] readCaps[Read Capabilities]
checkSafe{Has SafeStart?} checkSafe{Has safe-start?}
activateAll[Activate All MRDs] activateAll[Activate All MRDs]
keepInactive[Keep MRDs Inactive] keepInactive[Keep MRDs Inactive]
createCRDs[Create All CRDs] createCRDs[Create All CRDs]
@ -111,23 +113,23 @@ flowchart TD
### Legacy providers ### Legacy providers
Providers without any capabilities work exactly as before: Providers without any capabilities work as before:
* All MRDs are active by default * All MRDs are active by default
* All CRDs are created immediately * Crossplane creates all CRDs when provider installs
* No changes required for existing compositions or configurations * No changes required for existing compositions or configurations
### Modern providers ### Modern providers
Providers with SafeStart capability require additional setup: Providers with safe-start capability require extra setup:
* Create ManagedResourceActivationPolicy to activate needed resources * Create ManagedResourceActivationPolicy to activate needed resources
* Verify required CRDs exist before creating managed resources * Verify required CRDs exist before creating managed resources
* Use MRD connection details documentation for resource planning * Use MRD connection details documentation for resource planning
## Implementing SafeStart in providers ## Implementing safe-start in providers
SafeStart implementation requires several technical changes to provider code and safe-start implementation requires several technical changes to provider code and
build processes. This section provides an overview - see the build processes. This section provides an overview - see the
[complete SafeStart implementation guide]({{< ref "../guides/implementing-safestart" >}}) [complete safe-start implementation guide]({{< ref "../guides/implementing-safestart" >}})
for detailed instructions. for detailed instructions.
### Key implementation requirements ### Key implementation requirements
@ -140,11 +142,11 @@ for detailed instructions.
**Build process changes:** **Build process changes:**
- Update Makefile to generate MRDs alongside CRDs - Update Makefile to generate MRDs alongside CRDs
- Modify CI/CD to test SafeStart behavior - Change CI/CD to test safe-start behavior
- Include MRDs in provider package artifacts - Include MRDs in provider package artifacts
**RBAC updates:** **RBAC updates:**
SafeStart providers need additional permissions to manage CRDs dynamically: safe-start providers need extra permissions to manage CRDs dynamically:
```yaml ```yaml
apiVersion: rbac.authorization.k8s.io/v1 apiVersion: rbac.authorization.k8s.io/v1
@ -157,7 +159,7 @@ rules:
resources: ["events"] resources: ["events"]
verbs: ["create", "update", "patch"] verbs: ["create", "update", "patch"]
# Additional SafeStart permissions # Additional safe-start permissions
- apiGroups: ["apiextensions.k8s.io"] - apiGroups: ["apiextensions.k8s.io"]
resources: ["customresourcedefinitions"] resources: ["customresourcedefinitions"]
verbs: ["get", "list", "watch", "create", "update", "patch", "delete"] verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
@ -168,7 +170,7 @@ rules:
### Provider package metadata ### Provider package metadata
Declare SafeStart capability in your provider package: Declare safe-start capability in your provider package:
```yaml ```yaml
apiVersion: meta.pkg.crossplane.io/v1 apiVersion: meta.pkg.crossplane.io/v1
@ -178,10 +180,10 @@ metadata:
spec: spec:
package: registry.example.com/my-provider:v2.0.0 package: registry.example.com/my-provider:v2.0.0
capabilities: capabilities:
- name: SafeStart - name: safe-start
``` ```
### MRD generation with connection details ### Managed resource definition generation with connection details
Generate MRDs that document connection details for better user experience: Generate MRDs that document connection details for better user experience:
@ -219,21 +221,21 @@ spec:
### Implementation examples ### Implementation examples
The [provider-nop SafeStart implementation](https://github.com/crossplane-contrib/provider-nop/pull/24) The [provider-nop safe-start implementation](https://github.com/crossplane-contrib/provider-nop/pull/24)
demonstrates: demonstrates:
- Adding both namespaced and cluster-scoped resource variants - Adding both namespaced and cluster-scoped resource variants
- MRD controller integration - MRD controller integration
- Build process updates for SafeStart support - Build process updates for safe-start support
- Testing strategies for SafeStart behavior - Testing strategies for safe-start behavior
{{< hint "tip" >}} {{< hint "tip" >}}
See the [complete SafeStart implementation guide]({{< ref "../guides/implementing-safestart" >}}) See the [complete safe-start implementation guide]({{< ref "../guides/implementing-safestart" >}})
for step-by-step instructions, code examples, and testing strategies. for step-by-step instructions, code examples, and testing strategies.
{{< /hint >}} {{< /hint >}}
### Migration considerations ### Migration considerations
When adding SafeStart to existing providers: When adding safe-start to existing providers:
**Backward compatibility:** **Backward compatibility:**
- Existing provider installations continue working unchanged - Existing provider installations continue working unchanged
@ -244,19 +246,19 @@ When adding SafeStart to existing providers:
```yaml ```yaml
# Document version compatibility clearly # Document version compatibility clearly
# Provider v1.x: Traditional CRD installation # Provider v1.x: Traditional CRD installation
# Provider v2.0+: SafeStart support with MRDs # Provider v2.0+: safe-start support with MRDs
``` ```
## Best practices ## Best practices
### For provider developers ### For provider developers
**Do use SafeStart when:** **Do use safe-start when:**
* Your provider has >50 managed resources * Your provider has >50 managed resources
* Resource activation patterns vary by environment * Resource activation patterns vary by environment
* Performance optimization is important * Performance optimization is important
**Document capabilities clearly:** **Document capabilities:**
* Explain what each capability does * Explain what each capability does
* Provide migration guides for existing users * Provide migration guides for existing users
* Include examples of activation policies * Include examples of activation policies
@ -291,7 +293,7 @@ spec:
- "*.example.com" # Activate all resources - "*.example.com" # Activate all resources
``` ```
**Monitor activation status:** **Track activation status:**
```shell ```shell
# Check which MRDs are active # Check which MRDs are active
kubectl get mrds -l provider=my-provider kubectl get mrds -l provider=my-provider
@ -305,7 +307,7 @@ kubectl top nodes
## Future capabilities ## Future capabilities
The capability system is extensible. Future capabilities might include: The capability system is extendable. Future capabilities might include:
* **ResourceQuotas** - Automatic resource limit management * **ResourceQuotas** - Automatic resource limit management
* **NetworkPolicies** - Provider-specific network isolation * **NetworkPolicies** - Provider-specific network isolation
@ -318,7 +320,7 @@ The capability system is extensible. Future capabilities might include:
**MRDs not activating:** **MRDs not activating:**
```shell ```shell
# Check if provider has SafeStart capability # Check if provider has safe-start capability
kubectl get provider my-provider -o yaml | grep -A5 capabilities kubectl get provider my-provider -o yaml | grep -A5 capabilities
# Verify activation policy exists and matches # Verify activation policy exists and matches
@ -362,10 +364,10 @@ kubectl get mrds -l state=Active | wc -l
Provider capabilities integrate with: Provider capabilities integrate with:
* **MRDs** - SafeStart controls default activation state * **MRDs** - safe-start controls default activation state
* **Activation policies** - Work together to control resource availability * **Activation policies** - Work together to control resource availability
* **Package manager** - Capabilities are read during package installation * **Package manager** - Crossplane reads capabilities during package installation
* **RBAC** - Some capabilities require additional permissions * **RBAC** - Some capabilities require extra permissions
* **Compositions** - May need updates when capabilities change resource availability * **Compositions** - May need updates when capabilities change resource availability
Capabilities provide a foundation for evolving provider behavior while Capabilities provide a foundation for evolving provider behavior while

8
content/master/whats-new/_index.md
View File

@ -173,14 +173,14 @@ deprecate and remove cluster scoped MRs at a future date.
Read more about Crossplane v2's [backward compatibility](#backward-compatibility). Read more about Crossplane v2's [backward compatibility](#backward-compatibility).
{{</hint>}} {{</hint>}}
## Managed Resource Definitions ## Managed resource definitions
Crossplane v2 introduces Managed Resource Definitions (MRDs) that provide Crossplane v2 introduces Managed Resource Definitions (MRDs) that provide
selective resource activation and improved resource discovery. selective resource activation and improved resource discovery.
**MRDs solve performance and usability challenges with large providers.** **MRDs solve performance and usability challenges with large providers.**
Installing a provider like AWS traditionally creates hundreds of CRDs, even if Installing a provider like AWS traditionally creates hundreds of CRDs, even if
you only need a few resources. MRDs let you activate only the resources you you only need some resources. MRDs let you activate only the resources you
actually use. actually use.
```mermaid ```mermaid
@ -211,7 +211,7 @@ flowchart LR
style crd2 fill:#e8f5e8 style crd2 fill:#e8f5e8
``` ```
### Key MRD benefits ### Key managed resource definition benefits
**Performance optimization** - Only create CRDs for resources you need, reducing **Performance optimization** - Only create CRDs for resources you need, reducing
cluster overhead and improving provider installation speed. cluster overhead and improving provider installation speed.
@ -222,7 +222,7 @@ managed resource provides, making it easier to understand resource capabilities.
**Policy-based activation** - Use ManagedResourceActivationPolicy (MRAP) to **Policy-based activation** - Use ManagedResourceActivationPolicy (MRAP) to
activate resources with flexible pattern matching. activate resources with flexible pattern matching.
**SafeStart providers** - Providers can opt into SafeStart capability, starting **safe-start providers** - Providers can opt into safe-start capability, starting
with all MRDs inactive for better performance. with all MRDs inactive for better performance.
Learn more about [Managed Resource Definitions]({{<ref "../managed-resources/managed-resource-definitions">}}) Learn more about [Managed Resource Definitions]({{<ref "../managed-resources/managed-resource-definitions">}})

6
utils/vale/styles/Crossplane/crossplane-words.txt
View File

@ -81,6 +81,8 @@ RunFunctionRequest
RunFunctionResponse RunFunctionResponse
SafeStart SafeStart
SafeStart-capable SafeStart-capable
safe-start
safe-start-capable
Sigstore Sigstore
SSL SSL
StoreConfig StoreConfig
@ -108,3 +110,7 @@ XRD's
XRDs XRDs
XR's XR's
XRs XRs
ResourceQuotas
NetworkPolicies
CustomValidation
TelemetryOpt

7
utils/vale/styles/Crossplane/spelling-exceptions.txt
View File

@ -104,4 +104,9 @@ Crossplane-specific
non-SafeStart non-SafeStart
GitOps GitOps
Makefile Makefile
backporting provider-wide
ResourceQuotas
NetworkPolicies
CustomValidation
TelemetryOpt
non-safe-start