diff --git a/content/master/guides/implementing-safestart.md b/content/master/guides/implementing-safestart.md new file mode 100644 index 000000000..6cd2ff1c6 --- /dev/null +++ b/content/master/guides/implementing-safestart.md @@ -0,0 +1,264 @@ +--- +title: Implementing safe-start in Providers +weight: 160 +description: Guide for provider developers to implement safe-start capability +--- + +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" >}} +safe-start requires Crossplane v2.0+ and involves significant provider changes. +Plan for breaking changes and thorough testing before implementing. +{{< /hint >}} + +## What safe-start provides + +safe-start transforms how your provider handles resource installation: + +**Without safe-start:** +- All resources become MRDs that are automatically active and create CRDs +- Users get all ~100 resources even if they need only 5 +- Higher memory usage and slower API server responses + +**With safe-start:** +- All resources become MRDs that are inactive by default +- Users activate only needed resources through policies +- Lower resource overhead and better performance + +## Prerequisites + +Before implementing safe-start, ensure you have: + +* Provider built with `crossplane-runtime` v2.0+ +* Understanding of [MRDs and activation policies]({{< ref "using-mrds-and-activation-policies" >}}) +* Test environment with Crossplane v2.0+ +* CI/CD pipeline that can build and test provider changes + +## Implementation steps + +### Step 1: Update Provider Metadata + +Declare safe-start capability in your provider package metadata: + +```yaml +apiVersion: meta.pkg.crossplane.io/v1 +kind: Provider +metadata: + name: provider-example +spec: + package: registry.example.com/provider-example:v1.0.0 + capabilities: + - safe-start +``` + +{{< hint "tip" >}} +Crossplane supports flexible capability matching. `safe-start`, `safestart`, +and `safe-start` are all recognized as the same capability. +{{< /hint >}} + +### Step 2: Update RBAC Permissions + +safe-start providers need extra permissions to manage CRDs dynamically. Crossplane's RBAC manager automatically provides these permissions when you install safe-start providers. + +{{< hint "note" >}} +Manual RBAC configuration is only required if you disable Crossplane's RBAC manager (with `--args=--disable-rbac-manager`). +{{< /hint >}} + +**Automatically provided permissions:** +```yaml +# Crossplane RBAC manager grants these permissions automatically +# safe-start permissions +- apiGroups: ["apiextensions.k8s.io"] + resources: ["customresourcedefinitions"] + verbs: ["get", "list", "watch"] +``` + +**Manual configuration (only if you disable RBAC manager):** +```yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + name: provider-example-system +rules: +# Existing provider permissions +- apiGroups: [""] + resources: ["events"] + verbs: ["create", "update", "patch"] +- apiGroups: ["example.crossplane.io"] + resources: ["*"] + verbs: ["*"] + +# safe-start permissions +- apiGroups: ["apiextensions.k8s.io"] + resources: ["customresourcedefinitions"] + verbs: ["get", "list", "watch"] +``` + +## Testing safe-start implementation + +### Integration testing + +Test safe-start behavior in a real cluster: + +```shell +#!/bin/bash +set -e + +echo "Starting safe-start integration test..." + +# Install Crossplane v2.0 +kubectl create namespace crossplane-system +helm install crossplane crossplane-stable/crossplane \ + --namespace crossplane-system \ + --version v2.0.0 \ + --wait + +# Install provider with safe-start +kubectl apply -f - <20 resources +- Document recommended activation patterns for common use cases +- Provide environment-specific activation policy examples + +### User experience +- Include helpful error messages when resources aren't activated +- Provide clear migration guides for existing users +- Document connection details + +### Testing strategy +- Test both with and without safe-start in CI +- Verify activation/deactivation cycles work +- Test resource creation after activation diff --git a/content/master/guides/using-mrds-and-activation-policies.md b/content/master/guides/using-mrds-and-activation-policies.md new file mode 100644 index 000000000..415bb468a --- /dev/null +++ b/content/master/guides/using-mrds-and-activation-policies.md @@ -0,0 +1,523 @@ +--- +title: Managed Resource Definitions and Activation Policies +weight: 220 +description: Learn how to use MRDs and activation policies to optimize your Crossplane installation +--- + +This guide shows how to use Managed Resource Definitions (MRDs) and activation +policies to control which managed resources are available in your cluster. +You install a provider, examine its MRDs, and use policies to activate only +the resources you need. + +{{< hint "tip" >}} +This guide demonstrates the performance and discovery benefits of MRDs by +working with a subset of AWS resources rather than installing hundreds of CRDs. +{{< /hint >}} + +By the end of this guide, you understand how to: +* Examine MRDs created by provider packages +* Use activation policies to control resource availability +* Discover connection details through MRD schemas +* Optimize cluster performance by activating only needed resources + +## Prerequisites + +This guide requires: + +* A Kubernetes cluster with at least 2 GB of RAM +* Crossplane v2.0+ [installed on the cluster]({{< ref "../get-started/install" >}}) +* `kubectl` configured to access your cluster + +## Understand the default activation policy + +Before installing providers, it's important to understand Crossplane's default +activation behavior. Crossplane creates a default ManagedResourceActivationPolicy +that, by default, activates **all** managed resources with a `"*"` pattern. + +{{< hint "important" >}} +The default `"*"` activation pattern defeats the performance benefits of +safe-start by activating all resources. For this tutorial, the guide works with the +default behavior, but production setups should use more selective activation. +{{< /hint >}} + +Check if you have a default activation policy: + +```shell +kubectl get mrap crossplane-default-activation-policy -o yaml +``` + +You can edit the default activation policy directly: + +{{< tabs >}} +{{< tab "Edit Existing Policy" >}} +```shell +# Delete the default policy and restart Crossplane using Helm +kubectl delete mrap crossplane-default-activation-policy +helm upgrade crossplane crossplane-stable/crossplane \ + --set provider.defaultActivations=null \ + --namespace crossplane-system --reuse-values +kubectl rollout restart deployment/crossplane -n crossplane-system +``` + +{{< hint "note" >}} +Changes to the default policy are permanent. After the policy exists, Crossplane +doesn't change it, even if you change Helm values. +{{< /hint >}} +{{< /tab >}} + +{{< tab "Reset with Helm Values" >}} +```shell +# Delete the default policy and restart Crossplane to recreate from Helm values +kubectl delete mrap crossplane-default-activation-policy +helm upgrade crossplane crossplane-stable/crossplane \ + --set provider.defaultActivations=null \ + --namespace crossplane-system --reuse-values +kubectl rollout restart deployment/crossplane -n crossplane-system +``` + +This approach lets you use Helm chart values to control the default policy. +{{< /tab >}} +{{< /tabs >}} + +## Install a provider with safe-start capability + +Now install a provider that supports safe-start. This provider creates MRDs +that activation policies control. + +```yaml +apiVersion: pkg.crossplane.io/v1 +kind: Provider +metadata: + name: provider-aws +spec: + package: xpkg.crossplane.io/crossplane-contrib/provider-aws:v2.0.0 +``` + +Apply this configuration: + +```shell +kubectl apply -f - <}} +{{< tab "With Default Activation (default)" >}} +If you kept the default `"*"` activation pattern: + +```shell +NAME STATE AGE +buckets.s3.aws.crossplane.io Active 2m +instances.ec2.aws.crossplane.io Active 2m +databases.rds.aws.crossplane.io Active 2m +clusters.eks.aws.crossplane.io Active 2m +# ... many more, all Active +``` + +The default policy activates all MRDs, so safe-start providers behave like +traditional providers. +{{< /tab >}} + +{{< tab "With Disabled Default Activation" >}} +If you disabled default activation: + +```shell +NAME STATE AGE +buckets.s3.aws.crossplane.io Inactive 2m +instances.ec2.aws.crossplane.io Inactive 2m +databases.rds.aws.crossplane.io Inactive 2m +clusters.eks.aws.crossplane.io Inactive 2m +# ... many more, all Inactive +``` + +This demonstrates true safe-start behavior where resources must be explicitly +activated. +{{< /tab >}} +{{< /tabs >}} + +{{< hint "note" >}} +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 >}} + +Examine a specific MRD to understand its schema and connection details: + +```shell +kubectl get mrd instances.ec2.aws.crossplane.io -o yaml +``` + +Look for the `connectionDetails` section: + +```yaml +spec: + connectionDetails: + - description: The public IP address assigned to the instance + name: public_ip + type: string + - description: The private IP address assigned to the instance + name: private_ip + type: string + - description: The public DNS name assigned to the instance + name: public_dns + type: string +``` + +## Verify resource creation behavior + +The presence of CRDs depends on whether MRDs are active: + +{{< tabs >}} +{{< tab "With Default Activation (default)" >}} +Because MRDs are active due to the default `"*"` policy, CRDs exist: + +```shell +kubectl get crds | grep aws.crossplane.io | wc -l +``` + +This shows 100+ CRDs, demonstrating that active MRDs +create CRDs. +{{< /tab >}} + +{{< tab "With Disabled Default Activation" >}} +Because the MRDs are inactive, no CRDs should exist for AWS resources: + +```shell +kubectl get crds | grep aws.crossplane.io +``` + +This should return no results, demonstrating that inactive MRDs don't create +CRDs in your cluster. +{{< /tab >}} +{{< /tabs >}} + +## Create an activation policy + +Create a ManagedResourceActivationPolicy to activate specific AWS resources: + +```yaml +apiVersion: apiextensions.crossplane.io/v1alpha1 +kind: ManagedResourceActivationPolicy +metadata: + name: aws-demo-resources +spec: + activations: + - instances.ec2.aws.crossplane.io + - buckets.s3.aws.crossplane.io + - "*.rds.aws.crossplane.io" +``` + +Apply the policy: + +```shell +kubectl apply -f - <}} +This example assumes you have AWS credentials configured. See +[ProviderConfig documentation]({{< ref "../managed-resources/managed-resources#providerconfigref" >}}) for +authentication setup. +{{< /hint >}} + +```shell +kubectl apply -f - <}}) +* [Provider capabilities and safe-start]({{< ref "../packages/provider-capabilities" >}}) \ 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 new file mode 100644 index 000000000..f96aa96d7 --- /dev/null +++ b/content/master/managed-resources/managed-resource-definitions.md @@ -0,0 +1,265 @@ +--- +title: Managed Resource Definitions +weight: 10 +description: Understand Managed Resource Definitions (MRDs) and selective resource activation +--- + +Managed Resource Definitions (MRDs) provide a lightweight abstraction over +Kubernetes Custom Resource Definitions (CRDs) that enables selective +installation and better documentation of managed resources. + +{{< hint "note" >}} +MRDs are available in Crossplane v2.0+ as a beta feature. +{{< /hint >}} + + +## What are managed resource definitions + + +A Managed Resource Definition (MRD) is essentially a CRD with extra +metadata that provides: + +* **Connection details schema** - Documents what connection details the + managed resource provides +* **Activation control** - Controls whether the underlying CRD gets installed + in your cluster +* **Resource discovery** - Makes it easier to understand what resources are + available + +**Every managed resource in a provider package has an associated MRD.** The MRD +contains the same schema as the CRD, plus extra Crossplane-specific +metadata. + +```mermaid +flowchart LR + provider(Provider Package) + mrd(MRD) + crd(CRD) + mr(Managed Resource) + + provider --> mrd + mrd --"when active"--> crd + crd --> mr + + style mrd fill:#e1f5fe + style crd fill:#f3e5f5 +``` + +## Why use managed resource definitions + +MRDs solve several challenges with traditional provider packages: + +### Performance optimization +Installing a provider creates CRDs for _every_ managed resource the provider +supports. For large providers like AWS, this can mean hundreds of CRDs that +you may never use. + +**MRDs let you install only the CRDs you need**, reducing Kubernetes API +server overhead and improving cluster performance. + +### Connection details discovery +Understanding what connection details a managed resource provides requires +reading provider source code or trial-and-error testing. + +**MRDs document connection details in the schema**, making it clear what +credentials and endpoints each resource provides. + +### Selective installation +Different environments may need different subsets of managed resources. A +development environment might only need basic resources, while production +needs the full set. + +**MRDs enable environment-specific resource activation** through policies. + +## How managed resource definitions work + +When you install a provider package, Crossplane creates: + +1. **MRDs for all resources** - Every managed resource gets an MRD +2. **CRDs only when activated** - Crossplane creates CRDs only for active MRDs +3. **Activation policies** - ManagedResourceActivationPolicy controls which + MRDs become active + +### Managed resource definition lifecycle + +```mermaid +flowchart TD + install[Install Provider] + createMRD[Create MRDs] + checkPolicy{Activation Policy
Matches?} + activate[Activate MRD] + createCRD[Create CRD] + inactive[MRD Inactive] + + install --> createMRD + createMRD --> checkPolicy + checkPolicy -->|Yes| activate + checkPolicy -->|No| inactive + activate --> createCRD + + style activate fill:#c8e6c9 + style inactive fill:#ffcdd2 +``` + +### Managed resource definition states + +MRDs can be in one of two states: + +* **Active** - The underlying CRD exists and you can create managed resources +* **Inactive** - No CRD exists, managed resource creation fails + +You can change an MRD's state by: +* Editing the MRD directly (`spec.state: Active`) +* Using a ManagedResourceActivationPolicy +* Provider package capabilities (safe-start) + +## Connection details schema + +MRDs document the connection details that managed resources provide. This makes +it easier to understand what credentials and endpoints you get when creating +resources. + +```yaml +apiVersion: apiextensions.crossplane.io/v1alpha1 +kind: ManagedResourceDefinition +metadata: + name: databases.rds.aws.crossplane.io +spec: + group: rds.aws.crossplane.io + names: + kind: Database + plural: databases + scope: Namespaced + + # Connection details documentation + connectionDetails: + - name: endpoint + description: "The RDS instance connection endpoint" + type: string + fromConnectionSecretKey: endpoint + - name: port + description: "The port number for database connections" + type: integer + fromConnectionSecretKey: port + - name: username + description: "The master username for the database" + type: string + fromConnectionSecretKey: username + - name: password + description: "The master password for the database" + type: string + fromConnectionSecretKey: password + - name: ca_certificate + description: "The CA certificate for SSL connections" + type: string + fromConnectionSecretKey: ca_certificate + + # Standard CRD specification follows... + versions: + - name: v1alpha1 + served: true + storage: true +``` + +The `connectionDetails` field documents: +* **Connection detail names** - What keys appear in connection secrets +* **Descriptions** - What each connection detail contains +* **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. Pattern-based control is more scalable than manually activating +individual MRDs. + +```yaml +apiVersion: apiextensions.crossplane.io/v1alpha1 +kind: ManagedResourceActivationPolicy +metadata: + name: aws-core-resources +spec: + activations: + - "instances.ec2.aws.crossplane.io" # Specific MRD + - "*.rds.aws.crossplane.io" # All RDS resources + - "buckets.s3.aws.crossplane.io" # S3 buckets +``` + +### Activation patterns + +MRAP supports several activation patterns: + +* **Exact match**: `instances.ec2.aws.crossplane.io` +* **Wildcard prefix**: `*.rds.aws.crossplane.io` (all RDS resources) +* **Provider wildcard**: `*.aws.crossplane.io` (all AWS resources) + +Multiple MRAPs can exist, and their activations combine. + +## Provider capabilities + +Providers can declare capabilities that affect MRD behavior: + + +### 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 safe-start, all MRDs are active by default for backward compatibility. + +```yaml +# In provider package metadata +spec: + capabilities: + - safe-start +``` + +{{< hint "note" >}} +Implementing safe-start requires significant provider code changes. Provider +developers should follow the +[safe-start implementation guide]({{< ref "../guides/implementing-safestart" >}}) +for detailed technical requirements and examples. +{{< /hint >}} + + +### safe-start implementation examples + + +The Crossplane community has implemented safe-start in several providers: + +* **provider-nop** - [Reference implementation](https://github.com/crossplane-contrib/provider-nop/pull/24) + 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 safe-start behavior +- Migration approaches for existing users + +## Key concepts + +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, you can create resources +* **Inactive state** - No CRD exists, resource creation fails +* **safe-start** - Provider capability that defaults MRDs to inactive +* **Connection details schema** - Documentation of what connection details + a managed resource provides + +## Relationship to other Crossplane features + +MRDs integrate with existing Crossplane concepts: + +* **Providers** - Create MRDs when installed +* **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 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 new file mode 100644 index 000000000..8ff7f31bd --- /dev/null +++ b/content/master/packages/provider-capabilities.md @@ -0,0 +1,365 @@ +--- +title: Provider Capabilities +weight: 20 +description: Understand provider capabilities and how they affect resource behavior +--- + +Provider capabilities are declarative features that providers can implement to +change their behavior and integration with Crossplane. Capabilities enable +providers to opt into new features while maintaining backward compatibility. + +## What are provider capabilities + +Provider capabilities are metadata declarations in provider packages that tell +Crossplane how the provider should behave. They're like feature flags +but you declare them at the package level. + +```yaml +# In provider package metadata +apiVersion: meta.pkg.crossplane.io/v1alpha1 +kind: Provider +metadata: + name: provider-aws +spec: + capabilities: + - safe-start + - CustomCapability +``` + +Crossplane reads these capabilities and modifies its behavior when installing +and managing the provider. + +## Available capabilities + + +### safe-start + + +The `safe-start` capability changes how Managed Resource Definitions (MRDs) are +activated when you install the provider. + +**Without safe-start:** +- All resources become MRDs that are automatically active +- Active MRDs create corresponding CRDs +- Compatible with legacy providers and existing workflows + +**With safe-start:** +- All resources become MRDs that start in `Inactive` state +- No CRDs until you explicitly activate MRDs +- Reduces initial resource overhead and improves performance + +```yaml +spec: + capabilities: + - safe-start +``` + +{{< hint "tip" >}} +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 safe-start + +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 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 + +## Capability matching + +Crossplane supports flexible matching for capability names: + +* **Exact match**: `safe-start` +* **Case variations**: `SafeStart`, `safestart`, `safe-start` +* **Fuzzy matching**: Handles common spelling variations + +This flexibility prevents issues when providers use different naming conventions. + +## How capabilities affect installation + +The provider installation process changes based on declared capabilities: + +```mermaid +flowchart TD + install[Install Provider Package] + readCaps[Read Capabilities] + checkSafe{Has safe-start?} + activateAll[Activate All MRDs] + keepInactive[Keep MRDs Inactive] + createCRDs[Create All CRDs] + waitPolicy[Wait for Activation Policy] + + install --> readCaps + readCaps --> checkSafe + checkSafe -->|No| activateAll + checkSafe -->|Yes| keepInactive + activateAll --> createCRDs + keepInactive --> waitPolicy + + style keepInactive fill:#c8e6c9 + style waitPolicy fill:#fff3e0 +``` + +## Provider compatibility + +### Legacy providers + +Providers without any capabilities work as before: +* All MRDs are active by default +* Crossplane creates all CRDs when provider installs +* No changes required for existing compositions or configurations + +### Modern providers + +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 safe-start in providers + +safe-start implementation requires several technical changes to provider code and +build processes. This section provides an overview - see the +[complete safe-start implementation guide]({{< ref "../guides/implementing-safestart" >}}) +for detailed instructions. + +### Key implementation requirements + +**Code changes:** +- Add MRD controller logic to handle activation/deactivation +- Support both namespaced and cluster-scoped resources +- Generate MRDs with connection details documentation +- Implement CRD lifecycle management + +**Build process changes:** +- Update Makefile to generate MRDs alongside CRDs +- Change CI/CD to test safe-start behavior +- Include MRDs in provider package artifacts + +**RBAC updates:** +safe-start providers need extra permissions to manage CRDs dynamically: + +```yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + name: my-provider-system +rules: +# Standard provider permissions +- apiGroups: [""] + resources: ["events"] + verbs: ["create", "update", "patch"] + +# Additional safe-start permissions +- apiGroups: ["apiextensions.k8s.io"] + resources: ["customresourcedefinitions"] + verbs: ["get", "list", "watch", "create", "update", "patch", "delete"] +- apiGroups: ["apiextensions.crossplane.io"] + resources: ["managedresourcedefinitions"] + verbs: ["get", "list", "watch", "update", "patch"] +``` + +### Provider package metadata + +Declare safe-start capability in your provider package: + +```yaml +apiVersion: meta.pkg.crossplane.io/v1 +kind: Provider +metadata: + name: my-provider +spec: + package: registry.example.com/my-provider:v2.0.0 + capabilities: + - safe-start +``` + +### Managed resource definition generation with connection details + +Generate MRDs that document connection details for better user experience: + +```yaml +apiVersion: apiextensions.crossplane.io/v1alpha1 +kind: ManagedResourceDefinition +metadata: + name: databases.rds.aws.example.io +spec: + group: rds.aws.example.io + names: + kind: Database + plural: databases + scope: Namespaced + + # Connection details documentation + connectionDetails: + - name: endpoint + description: "The RDS instance connection endpoint" + type: string + fromConnectionSecretKey: endpoint + - name: port + description: "The port number for database connections" + type: integer + fromConnectionSecretKey: port + - name: username + description: "The master username for the database" + type: string + fromConnectionSecretKey: username + - name: password + description: "The master password for the database" + type: string + fromConnectionSecretKey: password +``` + +### Implementation examples + +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 safe-start support +- Testing strategies for safe-start behavior + +{{< hint "tip" >}} +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 safe-start to existing providers: + +**Backward compatibility:** +- Existing provider installations continue working unchanged +- New installations start with inactive MRDs +- Provide migration documentation for users + +**Version strategy:** +```yaml +# Document version compatibility clearly +# Provider v1.x: Traditional CRD installation +# Provider v2.0+: safe-start support with MRDs +``` + +## Best practices + +### For provider developers + +**Do use safe-start when:** +* Your provider has >50 managed resources +* Resource activation patterns vary by environment +* Performance optimization is important + +**Document capabilities:** +* Explain what each capability does +* Provide migration guides for existing users +* Include examples of activation policies + +**Test compatibility:** +* Verify behavior with and without capabilities +* Test with different Crossplane versions +* Validate RBAC permissions + +### For platform operators + +**Plan activation policies:** +```yaml +# Development environment - minimal resources +apiVersion: apiextensions.crossplane.io/v1alpha1 +kind: ManagedResourceActivationPolicy +metadata: + name: dev-resources +spec: + activations: + - "databases.*.example.com" + - "buckets.*.example.com" + +--- +# Production environment - comprehensive resources +apiVersion: apiextensions.crossplane.io/v1alpha1 +kind: ManagedResourceActivationPolicy +metadata: + name: prod-resources +spec: + activations: + - "*.example.com" # Activate all resources +``` + +**Track activation status:** +```shell +# Check which MRDs are active +kubectl get mrds -l provider=my-provider + +# Verify activation policies +kubectl get mrap -o wide + +# Monitor resource usage +kubectl top nodes +``` + +## Troubleshooting capabilities + +### Common issues + +**MRDs not activating:** +```shell +# Check if provider has safe-start capability +kubectl get provider my-provider -o yaml | grep -A5 capabilities + +# Verify activation policy exists and matches +kubectl get mrap +kubectl describe mrap my-policy +``` + +**CRDs not created:** +```shell +# Check MRD activation status +kubectl get mrd my-resource.example.com + +# Look for controller errors +kubectl logs -n crossplane-system deployment/crossplane +``` + +**Provider installation fails:** +```shell +# Check provider conditions +kubectl describe provider my-provider + +# Look for RBAC issues +kubectl get events --field-selector reason=FailedCreate +``` + +### Debug commands + +```shell +# List all providers and their capabilities +kubectl get providers -o jsonpath='{range .items[*]}{.metadata.name}: {.spec.capabilities[*].name}{"\n"}{end}' + +# Check MRD activation across providers +kubectl get mrds --show-labels + +# Verify CRD creation matches activation +kubectl get crds | grep example.com | wc -l +kubectl get mrds -l state=Active | wc -l +``` + +## Relationship to other features + +Provider capabilities integrate with: + +* **MRDs** - safe-start controls default activation state +* **Activation policies** - Work together to control resource availability +* **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 +maintaining compatibility with existing Crossplane installations. \ No newline at end of file diff --git a/content/master/whats-crossplane/_index.md b/content/master/whats-crossplane/_index.md index a558bd2c9..f8ad0c79a 100644 --- a/content/master/whats-crossplane/_index.md +++ b/content/master/whats-crossplane/_index.md @@ -46,14 +46,14 @@ involved in writing a controller. ## Crossplane components -Crossplane has four major components: +Crossplane has three major components: * [Composition](#composition) * [Managed resources](#managed-resources) * [Operations](#operations) * [Package manager](#package-manager) -You can use all four components to build your control plane, or pick only the +You can use all three components to build your control plane, or pick only the ones you need. ### Composition diff --git a/content/master/whats-new/_index.md b/content/master/whats-new/_index.md index 149e92da7..76d6e593b 100644 --- a/content/master/whats-new/_index.md +++ b/content/master/whats-new/_index.md @@ -6,12 +6,13 @@ description: Learn what's new in the Crossplane v2 preview **Crossplane v2 makes Crossplane more useful, more intuitive, and less opinionated.** -Crossplane v2 makes four major changes: +Crossplane v2 makes five major changes: * **Composite resources are now namespaced** -* **Managed resources are now namespaced** +* **Managed resources are now namespaced** * **Composition supports any Kubernetes resource** * **Operations enable operational workflows** +* **Managed Resource Definitions provide selective resource activation** **Crossplane v2 is better suited to building control planes for applications, not just infrastructure.** It removes the need for awkward abstractions like diff --git a/utils/vale/styles/Crossplane/crossplane-words.txt b/utils/vale/styles/Crossplane/crossplane-words.txt index 50a59d285..6347fd5d4 100644 --- a/utils/vale/styles/Crossplane/crossplane-words.txt +++ b/utils/vale/styles/Crossplane/crossplane-words.txt @@ -61,7 +61,15 @@ initProvider KCL LateInitialize managementPolicies +ManagedResourceActivationPolicy +ManagedResourceDefinition +ManagedResourceDefinitions +MRAP +MRAPs MR +MRD +MRD's +MRDs MRs Operation-specific PatchSet @@ -71,6 +79,10 @@ ProviderConfigs ProviderRevision RunFunctionRequest RunFunctionResponse +SafeStart +SafeStart-capable +safe-start +safe-start-capable Sigstore SSL StoreConfig @@ -98,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 a86c03206..40b897b0e 100644 --- a/utils/vale/styles/Crossplane/spelling-exceptions.txt +++ b/utils/vale/styles/Crossplane/spelling-exceptions.txt @@ -84,3 +84,29 @@ v2 validators version-specific webhook-based +well-documented +user-friendly +provider-nop +provider-specific +pattern-based +fine-grained +environment-specific +real-world +trial-and-error +CRD-only +flag-like +Team-based +Service-based +Provider-wide +Environment-based +Policy-based +Crossplane-specific +non-SafeStart +GitOps +Makefile +provider-wide +ResourceQuotas +NetworkPolicies +CustomValidation +TelemetryOpt +non-safe-start