Implementing safe-start in Providers

This is an alpha feature. Crossplane may change or drop this feature at any time.

This feature was introduced in v2.

For more information read the Crossplane feature lifecycle.

On this page

This guide shows provider developers how to implement safe-start capability in their Crossplane providers. safe-start enables disabling unused managed resources through ManagedResourceDefinitions, improving performance and reducing resource overhead.

Important

safe-start requires Crossplane v2.0+ and crossplane-runtime v2.0+. Implementing safe-start involves code changes that affect provider startup behavior.

What safe-start provides

safe-start changes how your provider handles CRD installation:

Without safe-start:

Providers create all managed resource CRDs when installed
Users get all resources even if they only need one or two
Higher memory usage and API server load

With safe-start:

Providers create ManagedResourceDefinitions but CRDs only when activated
Users activate only needed resources through ManagedResourceActivationPolicies
Significant reduction in cluster resource overhead

Prerequisites

Before implementing safe-start:

Provider built with crossplane-runtime v2.0+
Understanding of ManagedResourceDefinitions
Test environment with Crossplane v2.0+

Implementation steps

Step 1: Declare safe-start capability

Add safe-start to your provider package metadata:

1# package/crossplane.yaml
2apiVersion: meta.pkg.crossplane.io/v1
3kind: Provider
4metadata:
5  name: provider-example
6spec:
7  capabilities:
8  - safe-start

Step 2: Add required imports

Update your main.go imports (see crossplane-runtime godoc for full API reference):

 1import (
 2    // existing imports...
 3    
 4    "k8s.io/apimachinery/pkg/runtime/schema"
 5    apiextensionsv1 "k8s.io/apiextensions-apiserver/pkg/apis/apiextensions/v1"
 6    
 7    "github.com/crossplane/crossplane-runtime/v2/pkg/controller"
 8    "github.com/crossplane/crossplane-runtime/v2/pkg/gate"
 9    "github.com/crossplane/crossplane-runtime/v2/pkg/reconciler/customresourcesgate"
10)

Step 3: Initialize the gate

Add gate initialization in your main function:

 1func main() {
 2    // existing setup code...
 3    
 4    o := controller.Options{
 5        // existing options...
 6        Gate: new(gate.Gate[schema.GroupVersionKind]),
 7    }
 8    
 9    // Add CustomResourceDefinition to scheme for gate controller
10    if err := apiextensionsv1.AddToScheme(mgr.GetScheme()); err != nil {
11        panic(err)
12    }
13    
14    // Setup controllers
15    if err := yourprovider.Setup(mgr, o); err != nil {
16        panic(err)
17    }
18        
19    // Setup the CRD gate controller  
20    if err := customresourcesgate.Setup(mgr, o); err != nil {
21        panic(err)
22    }
23        
24    // start manager...
25}

Step 4: Use gated controller setup

Create a gated setup function for each managed resource controller:

 1// SetupGated registers controller setup with the gate, waiting for the
 2// required CRD
 3func SetupGated(mgr ctrl.Manager, o controller.Options) error {
 4    o.Gate.Register(func() {
 5        if err := Setup(mgr, o); err != nil {
 6            panic(err)
 7        }
 8    }, v1alpha1.MyResourceGroupVersionKind)
 9    return nil
10}
11
12// Setup is your existing controller setup function (unchanged)
13func Setup(mgr ctrl.Manager, o controller.Options) error {
14    // existing controller setup code...
15}

Step 5: Update controller registration

Change your controller setup to use the gated versions:

 1// internal/controller/controller.go
 2func Setup(mgr ctrl.Manager, o controller.Options) error {
 3    for _, setup := range []func(ctrl.Manager, controller.Options) error{
 4        myresource.SetupGated,  // Changed from myresource.Setup
 5        // other gated setups...
 6    } {
 7        if err := setup(mgr, o); err != nil {
 8            return err
 9        }
10    }
11    return nil
12}

Implementation details

The safe-start implementation uses a “gate” pattern:

Gate initialization: Creates a gate that tracks CRD readiness
Controller registration: Controllers register with the gate, specifying which CRDs they need
CRD monitoring: The customresourcesgate controller watches for CRD creation/deletion
Delayed startup: Controllers only start when their required CRDs become active

Testing your implementation

Test safe-start behavior with this basic workflow:

 1# Install Crossplane v2.0+
 2helm install crossplane crossplane-stable/crossplane \
 3  --namespace crossplane-system \
 4  --set provider.defaultActivations={}
 5
 6# Install your provider  
 7kubectl apply -f provider.yaml
 8
 9# Check that MRDs are created but inactive
10kubectl get mrds
11# All should show STATE: Inactive
12
13# No CRDs should exist yet
14kubectl get crds | grep yourprovider.m.crossplane.io
15# Should return no results
16
17# Create activation policy
18kubectl apply -f - <<EOF
19apiVersion: apiextensions.crossplane.io/v1alpha1
20kind: ManagedResourceActivationPolicy
21metadata:
22  name: test-activation
23spec:
24  activate:
25  - "myresource.yourprovider.m.crossplane.io"
26EOF
27
28# Verify activation worked
29kubectl get mrd myresource.yourprovider.m.crossplane.io
30# Should show STATE: Active
31
32# CRD should now exist
33kubectl get crd myresource.yourprovider.m.crossplane.io

Troubleshooting

Controllers never start

Cause: gate waits for CRDs that never become active.

Solution: check that Crossplane activated MRDs and created CRDs:

1kubectl get mrds -o wide
2kubectl describe mrap <activation-policy-name>

CRDs don’t appear

Cause: MRDs might not activate or activation policy doesn’t match.

Solution: verify activation policy patterns match MRD names:

1kubectl get mrds
2kubectl get mrap -o yaml

Migration considerations

When adding safe-start to existing providers:

Existing installations: Continue working as expected (no CRD changes)
New installations: Start with inactive MRDs, require activation policies

Next steps

Test your safe-start implementation with different activation patterns
Update provider documentation to explain activation requirements
Consider the user experience for providers that now require activation policies

Learn more about the user experience in disabling unused managed resources.