From e0a38db4d651ef27d3f4f7f5d57184d3eb466610 Mon Sep 17 00:00:00 2001 From: Scott Nichols Date: Thu, 7 Aug 2025 11:51:25 -0700 Subject: [PATCH] linter Signed-off-by: Scott Nichols --- .../get-started/get-started-with-mrds.md | 46 +++---- .../master/guides/implementing-safestart.md | 124 +++++++++--------- .../master/guides/mrd-activation-policies.md | 46 +++---- .../managed-resource-definitions.md | 60 +++++---- .../master/packages/provider-capabilities.md | 98 +++++++------- content/master/whats-new/_index.md | 8 +- .../styles/Crossplane/crossplane-words.txt | 6 + .../styles/Crossplane/spelling-exceptions.txt | 7 +- 8 files changed, 210 insertions(+), 185 deletions(-) diff --git a/content/master/get-started/get-started-with-mrds.md b/content/master/get-started/get-started-with-mrds.md index 7a7f4ef1..8ab7ac80 100644 --- a/content/master/get-started/get-started-with-mrds.md +++ b/content/master/get-started/get-started-with-mrds.md @@ -36,7 +36,7 @@ that, by default, activates **all** managed resources with a `"*"` pattern. {{< hint "important" >}} 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. {{< /hint >}} @@ -46,7 +46,7 @@ Check if you have a default activation policy: 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 >}} {{< tab "Edit Existing Policy" >}} @@ -62,7 +62,7 @@ kubectl patch mrap crossplane-default-activation-policy --type='merge' \ {{< hint "note" >}} 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 >}} {{< /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" >}}). {{< /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. ```yaml @@ -123,7 +123,7 @@ NAME INSTALLED HEALTHY PACKAGE 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: @@ -146,7 +146,7 @@ clusters.eks.aws.crossplane.io Active 2m # ... 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. {{< /tab >}} @@ -162,14 +162,14 @@ clusters.eks.aws.crossplane.io Inactive 2m # ... 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. {{< /tab >}} {{< /tabs >}} {{< hint "note" >}} -For the rest of this tutorial, we assume you have default activation -disabled to demonstrate selective activation. If you have default activation +For the rest of this tutorial, the guide assumes you have default activation +disabled to show selective activation. If you have default activation enabled, the MRDs are already active. {{< /hint >}} @@ -195,7 +195,7 @@ spec: type: string ``` -## Verify CRD creation behavior +## Verify resource creation behavior 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 ``` -This shows many CRDs (100+), demonstrating that active MRDs -create CRDs immediately. +This shows 100+ CRDs, demonstrating that active MRDs +create CRDs. {{< /tab >}} {{< tab "With Disabled Default Activation" >}} @@ -288,9 +288,9 @@ dbinstances.rds.aws.crossplane.io Active 5m # ... 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 kubectl get crds | grep -E "(instances.ec2|buckets.s3|rds)" | head -5 @@ -321,8 +321,8 @@ spec: ``` {{< hint "note" >}} -This example assumes you have AWS credentials configured. See the -[AWS Provider documentation]({{< ref "../guides/aws-provider" >}}) for +This example assumes you have AWS credentials configured. See +[ProviderConfig documentation]({{< ref "../managed-resources/managed-resources#providerconfigref" >}}) for authentication setup. {{< /hint >}} @@ -428,16 +428,16 @@ status: Compare the resource usage with traditional provider installation: **Without MRDs (traditional):** -- All ~200 AWS CRDs created immediately +- All ~200 AWS CRDs created when provider installs - Higher memory usage in kube-apiserver - Longer provider installation time **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 - 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 kubectl get crds | grep aws.crossplane.io | wc -l @@ -463,7 +463,7 @@ spec: 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. ## Clean up @@ -522,9 +522,9 @@ Now that you understand MRDs and activation policies, you can: * **Optimize cluster performance** by using selective activation * **Improve resource discovery** through MRD connection details documentation * **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: * [MRD activation policies best practices]({{< ref "../guides/mrd-activation-policies" >}}) - Comprehensive guide including default policy configuration * [Managed Resource Definitions concepts]({{< ref "managed-resource-definitions" >}}) -* [Provider capabilities and SafeStart]({{< ref "../packages/provider-capabilities" >}}) \ No newline at end of file +* [Provider capabilities and safe-start]({{< ref "../packages/provider-capabilities" >}}) \ No newline at end of file diff --git a/content/master/guides/implementing-safestart.md b/content/master/guides/implementing-safestart.md index c28e3606..28d070f0 100644 --- a/content/master/guides/implementing-safestart.md +++ b/content/master/guides/implementing-safestart.md @@ -1,36 +1,36 @@ --- -title: Implementing SafeStart in Providers +title: Implementing safe-start in Providers 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 -their Crossplane providers. SafeStart enables selective resource activation +This guide shows provider developers how to implement safe-start capability in +their Crossplane providers. safe-start enables selective resource activation through Managed Resource Definitions (MRDs), improving performance and resource management. {{< 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. {{< /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:** -- All managed resources become CRDs immediately when provider installs +**Without safe-start:** +- All managed resources become CRDs when provider installs - Users get all ~200 AWS resources even if they need only 5 - Higher memory usage and slower API server responses -**With SafeStart:** +**With safe-start:** - All managed resources become inactive MRDs when provider installs - Users activate only needed resources through policies - Lower resource overhead and better performance ## Prerequisites -Before implementing SafeStart, ensure you have: +Before implementing safe-start, ensure you have: * Provider built with Crossplane v2.0+ runtime * Understanding of [MRDs and activation policies]({{< ref "mrd-activation-policies" >}}) @@ -39,9 +39,9 @@ Before implementing SafeStart, ensure you have: ## 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 apiVersion: meta.pkg.crossplane.io/v1 @@ -51,15 +51,15 @@ metadata: spec: package: registry.example.com/provider-example:v1.0.0 capabilities: - - name: SafeStart + - name: safe-start ``` {{< 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. {{< /hint >}} -### Step 2: Enhance MRD generation +### Step 2: Enhance managed resource definition generation Update your MRD generation to include connection details documentation: @@ -81,7 +81,7 @@ type ManagedResourceDefinitionSpec struct { Names Names `json:"names"` Scope string `json:"scope"` - // SafeStart-specific fields + // safe-start-specific fields ConnectionDetails []ConnectionDetail `json:"connectionDetails,omitempty"` State ResourceState `json:"state,omitempty"` } @@ -103,10 +103,10 @@ func GetProvider() *ujconfig.Provider { ujconfig.WithIncludeList(ExternalNameConfigured()), ujconfig.WithDefaultResourceOptions( 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){ configureConnectionDetails, configureMRDDocumentation, @@ -150,7 +150,7 @@ func configureConnectionDetails(p *ujconfig.Provider) { ### 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: ```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 apiVersion: rbac.authorization.k8s.io/v1 @@ -198,7 +198,7 @@ rules: resources: ["*"] verbs: ["*"] -# Additional SafeStart permissions +# safe-start permissions - apiGroups: ["apiextensions.k8s.io"] resources: ["customresourcedefinitions"] verbs: ["get", "list", "watch", "create", "update", "patch", "delete"] @@ -207,7 +207,7 @@ rules: 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: @@ -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: @@ -306,18 +306,18 @@ build-package: generate mkdir -p package/ cp package/crds/*.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 "kind: Provider" >> package/provider.yaml echo "spec:" >> package/provider.yaml echo " capabilities:" >> package/provider.yaml - echo " - name: SafeStart" >> package/provider.yaml + echo " - name: safe-start" >> package/provider.yaml ``` {{< /tab >}} {{< tab "GitHub Actions" >}} ```yaml -name: Build and Test SafeStart Provider +name: Build and Test safe-start Provider on: push: @@ -351,13 +351,13 @@ jobs: echo "Generated MRDs:" ls -la package/mrds/ - - name: Test SafeStart Integration + - name: Test safe-start Integration run: | # Start local cluster make kind-up make install-crossplane-v2 - # Install provider with SafeStart + # Install provider with safe-start make install-provider # Verify MRDs created but inactive @@ -396,7 +396,7 @@ spec: plural: databases scope: Namespaced - # SafeStart-specific fields + # safe-start-specific fields connectionDetails: - name: endpoint description: "The RDS instance connection endpoint" @@ -427,7 +427,7 @@ spec: # ... rest of CRD spec ``` -## Testing SafeStart implementation +## Testing safe-start implementation ### Unit testing @@ -435,7 +435,7 @@ Test your MRD generation and controller logic: ```go func TestMRDGeneration(t *testing.T) { - // Test that MRDs are generated with correct connection details + // Test MRD generation with correct connection details mrd := generateMRDForResource("Database") assert.Equal(t, "databases.rds.aws.example.io", mrd.Name) @@ -463,7 +463,7 @@ func TestMRDActivation(t *testing.T) { assert.NoError(t, err) assert.False(t, result.Requeue) - // Verify CRD was created + // Verify CRD creation crd := &apiextv1.CustomResourceDefinition{} err = fakeClient.Get(ctx, types.NamespacedName{Name: "databases.rds.aws.example.io"}, crd) assert.NoError(t, err) @@ -472,13 +472,13 @@ func TestMRDActivation(t *testing.T) { ### Integration testing -Test SafeStart behavior in a real cluster: +Test safe-start behavior in a real cluster: -```bash +```shell #!/bin/bash set -e -echo "Starting SafeStart integration test..." +echo "Starting safe-start integration test..." # Install Crossplane v2.0 kubectl create namespace crossplane-system @@ -487,7 +487,7 @@ helm install crossplane crossplane-stable/crossplane \ --version v2.0.0 \ --wait -# Install provider with SafeStart +# Install provider with safe-start kubectl apply -f - < ### README updates + ```markdown # 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 - Improved performance for large providers - Connection details documentation -### Quick Start with SafeStart +### Quick Start with safe-start 1. Install the provider: ```yaml @@ -633,10 +635,10 @@ spec: - "*.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: @@ -658,10 +660,10 @@ Document what connection details each resource provides: ## Troubleshooting -### Common issues +### Common Issues **MRDs not activating:** -```bash +```shell # Check activation policy exists and matches kubectl get mrap kubectl describe mrap my-policy @@ -672,7 +674,7 @@ kubectl describe mrd my-resource.provider.example.io ``` **CRDs not created:** -```bash +```shell # Check MRD controller logs 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:** -```bash +```shell # Verify MRD is active kubectl get mrd my-resource.provider.example.io -o jsonpath='{.spec.state}' @@ -702,13 +704,13 @@ kubectl describe my-resource my-instance ### User experience - Include helpful error messages when resources aren't activated - Provide clear migration guides for existing users -- Document connection details thoroughly +- Document connection details ### Testing strategy -- Test both with and without SafeStart in CI -- Verify activation/deactivation cycles work correctly +- Test both with and without safe-start in CI +- Verify activation/deactivation cycles work - Test resource creation after activation -SafeStart provides significant value for large providers and improves the -overall Crossplane user experience. Following this guide helps ensure your +safe-start provides significant value for large providers and improves the + Crossplane user experience. Following this guide helps ensure your implementation is robust, well-documented, and user-friendly. \ No newline at end of file diff --git a/content/master/guides/mrd-activation-policies.md b/content/master/guides/mrd-activation-policies.md index 804a85a3..b4c67260 100644 --- a/content/master/guides/mrd-activation-policies.md +++ b/content/master/guides/mrd-activation-policies.md @@ -1,5 +1,5 @@ --- -title: Writing MRD Activation Policies +title: Writing MRD activation policies weight: 150 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 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 resources according to configurable patterns. By default, it uses a wildcard @@ -32,7 +32,7 @@ spec: ``` {{< 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. {{< /hint >}} @@ -86,13 +86,13 @@ provider: ### 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 # View current default policy 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' \ -p='{"spec":{"activations":["nonexistent.example.com"]}}' @@ -105,8 +105,8 @@ kubectl delete mrap crossplane-default-activation-policy ``` {{< hint "note" >}} -**Changes to the default policy are permanent.** Once the default MRAP exists, -Crossplane will not modify it. The Helm chart `provider.defaultActivations` +**Changes to the default policy are permanent.** After the default MRAP exists, +Crossplane doesn't change it. The Helm chart `provider.defaultActivations` value is only used when creating the policy if it doesn't already exist. {{< /hint >}} @@ -161,12 +161,12 @@ EOF - **Performance**: Only activates resources you actually use - **Security**: Principle of least privilege for resource access - **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 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 apiVersion: apiextensions.crossplane.io/v1alpha1 @@ -200,7 +200,7 @@ spec: ``` 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 * Security policies require explicit resource approval @@ -234,7 +234,7 @@ spec: ``` 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 * Development environments need broad resource access @@ -267,7 +267,7 @@ spec: ### Staging environment -Include additional resources for integration testing: +Include resources for integration testing: ```yaml apiVersion: apiextensions.crossplane.io/v1alpha1 @@ -396,9 +396,9 @@ spec: - "*.insights.azure.crossplane.io" ``` -### Application team +### App team -Resources needed by application developers: +Resources needed by app developers: ```yaml apiVersion: apiextensions.crossplane.io/v1alpha1 @@ -451,8 +451,8 @@ spec: - "*.lambda.aws.crossplane.io" ``` -You can delete the `advanced-resources` policy to quickly deactivate optional -resources while keeping base functionality. +You can delete the `advanced-resources` policy to deactivate optional +resources while keeping base capability. ### Feature flag patterns @@ -477,7 +477,7 @@ spec: ### Check activation status -Verify your policies are working correctly: +Verify your policies work: ```shell # List all activation policies @@ -495,7 +495,7 @@ kubectl get mrds -l crossplane.io/provider=provider-aws --field-selector spec.st ### Test resource creation -Verify activated resources work correctly: +Verify activated resources work: ```shell # Try creating a managed resource @@ -523,7 +523,7 @@ Common issues and solutions: kubectl get 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 # Look for controller errors @@ -551,7 +551,7 @@ spec: ### Policy consolidation -Multiple small policies vs. few large policies: +Multiple small policies vs. large policies: {{< tabs >}} {{< tab "Multiple Small Policies (Recommended)" >}} @@ -599,7 +599,9 @@ spec: ## Policy lifecycle management + ### GitOps workflow + Store activation policies in Git for proper change management: @@ -687,5 +689,5 @@ spec: # ... composition definition ``` -This helps operators understand which activation policies are needed for -specific compositions to work correctly. \ No newline at end of file +This helps operators understand which activation policies you need for +specific compositions to work. \ No newline at end of file diff --git a/content/master/managed-resources/managed-resource-definitions.md b/content/master/managed-resources/managed-resource-definitions.md index ea2af556..34d841c3 100644 --- a/content/master/managed-resources/managed-resource-definitions.md +++ b/content/master/managed-resources/managed-resource-definitions.md @@ -12,9 +12,11 @@ installation and better documentation of managed resources. MRDs are available in Crossplane v2.0+ as an alpha feature. {{< /hint >}} -## What are managed resource definitions? + +## What are managed resource definitions + -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: * **Connection details schema** - Documents what connection details the @@ -25,7 +27,7 @@ metadata that provides: available **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. ```mermaid @@ -43,7 +45,7 @@ flowchart LR style crd fill:#f3e5f5 ``` -## Why use managed resource definitions? +## Why use managed resource definitions MRDs solve several challenges with traditional provider packages: @@ -69,7 +71,7 @@ needs the full set. **MRDs enable environment-specific resource activation** through policies. -## How MRDs work +## How managed resource definitions work 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 MRDs become active -### MRD lifecycle +### Managed resource definition lifecycle ```mermaid flowchart TD @@ -99,7 +101,7 @@ flowchart TD style inactive fill:#ffcdd2 ``` -### MRD states +### Managed resource definition 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: * Editing the MRD directly (`spec.state: Active`) * Using a ManagedResourceActivationPolicy -* Provider package capabilities (SafeStart) +* Provider package capabilities (safe-start) ## Connection details schema @@ -142,13 +144,15 @@ spec: The `connectionDetails` field documents: * **Connection detail names** - What keys appear in connection secrets * **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 + ## Managed Resource Activation Policy + 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. ```yaml @@ -171,44 +175,48 @@ MRAP supports several activation patterns: * **Wildcard prefix**: `*.rds.aws.crossplane.io` (all RDS 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 Providers can declare capabilities that affect MRD behavior: -### SafeStart capability -Providers with the `SafeStart` capability start with all MRDs inactive by + +### safe-start capability + +Providers with the `safe-start` capability start with all MRDs inactive by 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 # In provider package metadata spec: capabilities: - - name: SafeStart + - name: safe-start ``` {{< hint "note" >}} -Implementing SafeStart requires significant provider code changes. Provider +Implementing safe-start requires significant provider code changes. Provider 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. {{< /hint >}} -### SafeStart implementation examples + +### safe-start implementation examples + -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) - showing SafeStart integration with both namespaced and cluster-scoped resources -* **provider-aws** - Large provider demonstrating SafeStart performance benefits + showing safe-start integration with both namespaced and cluster-scoped resources +* **provider-aws** - Large provider demonstrating safe-start performance benefits These implementations provide real-world examples of: - MRD controller integration - Build process modifications -- Testing strategies for SafeStart behavior +- Testing strategies for safe-start behavior - Migration approaches for existing users ## 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 * **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 -* **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 a managed resource provides @@ -228,10 +236,10 @@ Understanding these terms helps when working with MRDs: MRDs integrate with existing Crossplane concepts: * **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 (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 work without modification. \ No newline at end of file diff --git a/content/master/packages/provider-capabilities.md b/content/master/packages/provider-capabilities.md index 9a7d89d7..653d60e2 100644 --- a/content/master/packages/provider-capabilities.md +++ b/content/master/packages/provider-capabilities.md @@ -5,14 +5,14 @@ description: Understand provider capabilities and how they affect resource behav --- 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. -## What are provider capabilities? +## What are provider capabilities Provider capabilities are metadata declarations in provider packages that tell -Crossplane how the provider should behave. They're similar to feature flags -but are declared at the package level. +Crossplane how the provider should behave. They're like feature flags +but you declare them at the package level. ```yaml # In provider package metadata @@ -22,7 +22,7 @@ metadata: name: provider-aws spec: capabilities: - - name: SafeStart + - name: safe-start - name: CustomCapability ``` @@ -31,43 +31,45 @@ and managing the provider. ## Available capabilities -### SafeStart + +### safe-start + -The `SafeStart` capability changes how Managed Resource Definitions (MRDs) are -activated when the provider is installed. +The `safe-start` capability changes how Managed Resource Definitions (MRDs) are +activated when you install the provider. -**Without SafeStart:** +**Without safe-start:** - 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 -**With SafeStart:** +**With safe-start:** - 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 ```yaml spec: capabilities: - - name: SafeStart + - name: safe-start ``` {{< 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 creation of unused CRDs. {{< /hint >}} -#### When to use SafeStart +#### When to use safe-start -Use SafeStart when: -* Your provider defines many managed resources (>50) +Use safe-start when: +* Your provider defines over 50 managed resources * Users typically need only a subset of available resources * Installation performance and resource usage are concerns * You want to provide better resource discovery through MRDs -Don't use SafeStart when: -* Your provider has few managed resources (<20) +Don't use safe-start when: +* Your provider has under 20 managed resources * Most users need all available resources * Backward compatibility with existing installations is critical * 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: -* **Exact match**: `SafeStart` -* **Case variations**: `safestart`, `safe-start`, `SafeStart` +* **Exact match**: `safe-start` +* **Case variations**: `safestart`, `safe-start`, `safe-start` * **Fuzzy matching**: Handles common spelling variations 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 install[Install Provider Package] readCaps[Read Capabilities] - checkSafe{Has SafeStart?} + checkSafe{Has safe-start?} activateAll[Activate All MRDs] keepInactive[Keep MRDs Inactive] createCRDs[Create All CRDs] @@ -111,23 +113,23 @@ flowchart TD ### Legacy providers -Providers without any capabilities work exactly as before: +Providers without any capabilities work as before: * 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 ### Modern providers -Providers with SafeStart capability require additional setup: +Providers with safe-start capability require extra setup: * Create ManagedResourceActivationPolicy to activate needed resources * Verify required CRDs exist before creating managed resources * 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 -[complete SafeStart implementation guide]({{< ref "../guides/implementing-safestart" >}}) +[complete safe-start implementation guide]({{< ref "../guides/implementing-safestart" >}}) for detailed instructions. ### Key implementation requirements @@ -140,11 +142,11 @@ for detailed instructions. **Build process changes:** - 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 **RBAC updates:** -SafeStart providers need additional permissions to manage CRDs dynamically: +safe-start providers need extra permissions to manage CRDs dynamically: ```yaml apiVersion: rbac.authorization.k8s.io/v1 @@ -157,7 +159,7 @@ rules: resources: ["events"] verbs: ["create", "update", "patch"] -# Additional SafeStart permissions +# Additional safe-start permissions - apiGroups: ["apiextensions.k8s.io"] resources: ["customresourcedefinitions"] verbs: ["get", "list", "watch", "create", "update", "patch", "delete"] @@ -168,7 +170,7 @@ rules: ### Provider package metadata -Declare SafeStart capability in your provider package: +Declare safe-start capability in your provider package: ```yaml apiVersion: meta.pkg.crossplane.io/v1 @@ -178,10 +180,10 @@ metadata: spec: package: registry.example.com/my-provider:v2.0.0 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: @@ -219,21 +221,21 @@ spec: ### 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: - Adding both namespaced and cluster-scoped resource variants - MRD controller integration -- Build process updates for SafeStart support -- Testing strategies for SafeStart behavior +- Build process updates for safe-start support +- Testing strategies for safe-start behavior {{< 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. {{< /hint >}} ### Migration considerations -When adding SafeStart to existing providers: +When adding safe-start to existing providers: **Backward compatibility:** - Existing provider installations continue working unchanged @@ -244,19 +246,19 @@ When adding SafeStart to existing providers: ```yaml # Document version compatibility clearly # Provider v1.x: Traditional CRD installation -# Provider v2.0+: SafeStart support with MRDs +# Provider v2.0+: safe-start support with MRDs ``` ## Best practices ### For provider developers -**Do use SafeStart when:** +**Do use safe-start when:** * Your provider has >50 managed resources * Resource activation patterns vary by environment * Performance optimization is important -**Document capabilities clearly:** +**Document capabilities:** * Explain what each capability does * Provide migration guides for existing users * Include examples of activation policies @@ -291,7 +293,7 @@ spec: - "*.example.com" # Activate all resources ``` -**Monitor activation status:** +**Track activation status:** ```shell # Check which MRDs are active kubectl get mrds -l provider=my-provider @@ -305,7 +307,7 @@ kubectl top nodes ## 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 * **NetworkPolicies** - Provider-specific network isolation @@ -318,7 +320,7 @@ The capability system is extensible. Future capabilities might include: **MRDs not activating:** ```shell -# Check if provider has SafeStart capability +# Check if provider has safe-start capability kubectl get provider my-provider -o yaml | grep -A5 capabilities # Verify activation policy exists and matches @@ -362,10 +364,10 @@ kubectl get mrds -l state=Active | wc -l 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 -* **Package manager** - Capabilities are read during package installation -* **RBAC** - Some capabilities require additional permissions +* **Package manager** - Crossplane reads capabilities during package installation +* **RBAC** - Some capabilities require extra permissions * **Compositions** - May need updates when capabilities change resource availability Capabilities provide a foundation for evolving provider behavior while diff --git a/content/master/whats-new/_index.md b/content/master/whats-new/_index.md index 33a7a39c..c0d85e84 100644 --- a/content/master/whats-new/_index.md +++ b/content/master/whats-new/_index.md @@ -173,14 +173,14 @@ deprecate and remove cluster scoped MRs at a future date. Read more about Crossplane v2's [backward compatibility](#backward-compatibility). {{}} -## Managed Resource Definitions +## Managed resource definitions Crossplane v2 introduces Managed Resource Definitions (MRDs) that provide selective resource activation and improved resource discovery. **MRDs solve performance and usability challenges with large providers.** 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. ```mermaid @@ -211,7 +211,7 @@ flowchart LR style crd2 fill:#e8f5e8 ``` -### Key MRD benefits +### Key managed resource definition benefits **Performance optimization** - Only create CRDs for resources you need, reducing 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 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. Learn more about [Managed Resource Definitions]({{}}) diff --git a/utils/vale/styles/Crossplane/crossplane-words.txt b/utils/vale/styles/Crossplane/crossplane-words.txt index dd8712f4..6347fd5d 100644 --- a/utils/vale/styles/Crossplane/crossplane-words.txt +++ b/utils/vale/styles/Crossplane/crossplane-words.txt @@ -81,6 +81,8 @@ RunFunctionRequest RunFunctionResponse SafeStart SafeStart-capable +safe-start +safe-start-capable Sigstore SSL StoreConfig @@ -108,3 +110,7 @@ XRD's XRDs XR's XRs +ResourceQuotas +NetworkPolicies +CustomValidation +TelemetryOpt diff --git a/utils/vale/styles/Crossplane/spelling-exceptions.txt b/utils/vale/styles/Crossplane/spelling-exceptions.txt index 59e79cb5..40b897b0 100644 --- a/utils/vale/styles/Crossplane/spelling-exceptions.txt +++ b/utils/vale/styles/Crossplane/spelling-exceptions.txt @@ -104,4 +104,9 @@ Crossplane-specific non-SafeStart GitOps Makefile -backporting +provider-wide +ResourceQuotas +NetworkPolicies +CustomValidation +TelemetryOpt +non-safe-start