Managed Resource Definitions

Managed Resource Definitions (MRDs) provide a lightweight abstraction over Kubernetes Custom Resource Definitions (CRDs) that enables selective installation and better documentation of managed resources.

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.

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

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.

 1apiVersion: apiextensions.crossplane.io/v1alpha1
 2kind: ManagedResourceDefinition
 3metadata:
 4  name: databases.rds.aws.crossplane.io
 5spec:
 6  group: rds.aws.crossplane.io
 7  names:
 8    kind: Database
 9    plural: databases
10  scope: Namespaced
11  
12  # Connection details documentation
13  connectionDetails:
14  - name: endpoint
15    description: "The RDS instance connection endpoint"
16    type: string
17    fromConnectionSecretKey: endpoint
18  - name: port
19    description: "The port number for database connections"
20    type: integer
21    fromConnectionSecretKey: port
22  - name: username
23    description: "The master username for the database"
24    type: string
25    fromConnectionSecretKey: username
26  - name: password
27    description: "The master password for the database"
28    type: string
29    fromConnectionSecretKey: password
30  - name: ca_certificate
31    description: "The CA certificate for SSL connections"
32    type: string
33    fromConnectionSecretKey: ca_certificate
34    
35  # Standard CRD specification follows...
36  versions:
37  - name: v1alpha1
38    served: true
39    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.

1apiVersion: apiextensions.crossplane.io/v1alpha1
2kind: ManagedResourceActivationPolicy
3metadata:
4  name: aws-core-resources
5spec:
6  activations:
7  - "instances.ec2.aws.crossplane.io"      # Specific MRD
8  - "*.rds.aws.crossplane.io"             # All RDS resources
9  - "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.

1# In provider package metadata
2spec:
3  capabilities:
4  - safe-start

safe-start implementation examples

The Crossplane community has implemented safe-start in several providers:

• provider-nop - Reference implementation 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.