Composite Resources

On this page

This document is for a preview version of Crossplane.

This document applies to Crossplane v2.0-preview and not to the latest release v1.19.

Don't use Crossplane v2.0-preview in production.

A composite resource, or XR, represents a set of Kubernetes resources as a single Kubernetes object. Crossplane creates composite resources when users access a custom API, defined in the CompositeResourceDefinition.

Tip

Composite resources are a composite of Kubernetes resources.
A Composition defines how to compose the resources together.

A composite resource or XR (this page) is a custom API.

You use two Crossplane types to create a new custom API:

A Composite Resource Definition (XRD) - Defines the XR’s schema.
A Composition - Configures how the XR creates other resources.

Create composite resources

Creating composite resources requires a Composition and a CompositeResourceDefinition (XRD).

The Composition defines the set of resources to create. The XRD defines the custom API users call to request the set of resources.

XRDs define the API used to create a composite resource. For example, this CompositeResourceDefinition creates a custom API endpoint mydatabases.example.org.

 1apiVersion: apiextensions.crossplane.io/v1
 2kind: CompositeResourceDefinition
 3metadata: 
 4  name: mydatabases.example.org
 5spec:
 6  group: example.org
 7  names:
 8    kind: MyDatabase
 9    plural: mydatabases
10  # Removed for brevity

When a user calls the custom API, mydatabases.example.org, Crossplane chooses the Composition to use based on the Composition’s compositeTypeRef

1apiVersion: apiextensions.crossplane.io/v1
2kind: Composition
3metadata:
4  name: my-composition
5spec:
6  compositeTypeRef:
7    apiVersion: example.org/v1alpha1
8    kind: MyDatabase
9  # Removed for brevity

The Composition compositeTypeRef matches the XRD group and kind.

Crossplane creates the resources defined in the matching Composition and represents them as a single composite resource.

1kubectl get composite
2NAME                    SYNCED   READY   COMPOSITION         AGE
3my-composite-resource   True     True    my-composition      4s

Composition selection

Select a specific Composition for a composite resource to use with compositionRef

Important

The selected Composition must allow the composite resource to use it with a compositeTypeRef. Read more about the compositeTypeRef field in the Enable Composite Resources section of the Composition documentation.

 1apiVersion: example.org/v1alpha1
 2kind: MyDatabase
 3metadata:
 4  namespace: default
 5  name: my-composite-resource
 6spec:
 7  crossplane:
 8    compositionRef:
 9      name: my-other-composition
10  # Removed for brevity

A composite resource can also select a Composition based on labels instead of the exact name with a compositionSelector.

Inside the matchLabels section provide one or more Composition labels to match.

 1apiVersion: example.org/v1alpha1
 2kind: MyDatabase
 3metadata:
 4  namespace: default
 5  name: my-composite-resource
 6spec:
 7  crossplane:
 8    compositionSelector:
 9      matchLabels:
10        environment: production
11    # Removed for brevity

Composition revision policy

Crossplane tracks changes to Compositions as Composition revisions .

A composite resource can use a compositionUpdatePolicy to manually or automatically reference newer Composition revisions.

The default compositionUpdatePolicy is “Automatic.” Composite resources automatically use the latest Composition revision.

Change the policy to Manual to prevent composite resources from automatically upgrading.

1apiVersion: example.org/v1alpha1
2kind: MyDatabase
3metadata:
4  namespace: default
5  name: my-composite-resource
6spec:
7  crossplane:
8    compositionUpdatePolicy: Manual
9    # Removed for brevity

Composition revision selection

Crossplane records changes to Compositions as Composition revisions.
A composite resource can select a specific Composition revision.

Use compositionRevisionRef to select a specific Composition revision by name.

For example, to select a specific Composition revision use the name of the desired Composition revision.

 1apiVersion: example.org/v1alpha1
 2kind: MyDatabase
 3metadata:
 4  namespace: default
 5  name: my-composite-resource
 6spec:
 7  crossplane:
 8    compositionUpdatePolicy: Manual
 9    compositionRevisionRef:
10      name: my-composition-b5aa1eb
11    # Removed for brevity

Note

Find the Composition revision name from kubectl get compositionrevision

1kubectl get compositionrevision
2NAME                         REVISION   XR-KIND        XR-APIVERSION            AGE
3my-composition-5c976ad       1          mydatabases    example.org/v1alpha1     65m
4my-composition-b5aa1eb       2          mydatabases    example.org/v1alpha1     64m

A Composite resource can also select Composition revisions based on labels instead of the exact name with a compositionRevisionSelector.

Inside the matchLabels section provide one or more Composition revision labels to match.

 1apiVersion: example.org/v1alpha1
 2kind: MyDatabase
 3metadata:
 4  namespace: default
 5  name: my-composite-resource
 6spec:
 7  crossplane:
 8    compositionRevisionSelector:
 9      matchLabels:
10        channel: dev
11    # Removed for brevity

Pausing composite resources

Crossplane supports pausing composite resources. A paused composite resource doesn’t check or make changes on its external resources.

To pause a composite resource apply the crossplane.io/paused annotation.

1apiVersion: example.org/v1alpha1
2kind: MyDatabase
3metadata:
4  namespace: default
5  name: my-composite-resource
6  annotations:
7    crossplane.io/paused: "true"
8spec:
9  # Removed for brevity

Verify composite resources

Use kubectl get composite to view all the composite resources Crossplane created.

1kubectl get composite
2NAME                    SYNCED   READY   COMPOSITION         AGE
3my-composite-resource   True     True    my-composition      4s

Use kubectl get for the specific custom API endpoint to view only those resources.

1kubectl get mydatabases
2NAME                    SYNCED   READY   COMPOSITION        AGE
3my-composite-resource   True     True    my-composition     12m

Use kubectl describe composite to view the linked Composition Ref, and unique resources created in the Resource Refs.

 1kubectl describe composite my-composite-resource
 2Name:         my-composite-resource
 3Namespace:    default
 4API Version:  example.org/v1alpha1
 5Kind:         MyDatabase
 6Spec:
 7  Composition Ref:
 8    Name:  my-composition
 9  Composition Revision Ref:
10    Name:                     my-composition-cf2d3a7
11  Composition Update Policy:  Automatic
12  Resource Refs:
13    API Version:  s3.aws.m.upbound.io/v1beta1
14    Kind:         Bucket
15    Name:         my-composite-resource-fmrks
16    API Version:  dynamodb.aws.m.upbound.io/v1beta1
17    Kind:         Table
18    Name:         my-composite-resource-wnr9t
19# Removed for brevity

Composite resource conditions

A composite resource has two status conditions: Synced and Ready.

Crossplane sets the Synced status condition to True when it’s able to successfully reconcile the composite resource. If Crossplane can’t reconcile the composite resource it’ll report an error in the Synced condition.

Crossplane sets the Ready status condition to True when the composite resource’s composition function pipeline reports that all of its composed resources are ready. If a composed resource isn’t ready Crossplane will report it in the Ready condition.

Composite resource labels

Crossplane adds labels to composed resources to show their relationship to other Crossplane components.

Crossplane adds the crossplane.io/composite label to all composed resources. The label matches the name of the composite. Crossplane applies the composite label to anyresource created by a composite, creating a reference between the resource and owning composite resource.

1kubectl describe mydatabase.example.org/my-database-x9rx9
2Name:         my-database2-x9rx9
3Namespace:    default
4Labels:       crossplane.io/composite=my-database-x9rx9