Composite Resources

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

Creating 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 xmydatabases.example.org.

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

When a user calls the custom API, xmydatabases.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: xMyDatabase
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

Naming external resources

By default, managed resources created by a composite resource have the name of the composite resource, followed by a random suffix.

For example, a composite resource named “my-composite-resource” creates external resources named “my-composite-resource-fqvkw.”

Resource names can be deterministic by applying an annotation to the composite resource.

1apiVersion: example.org/v1alpha1
2kind: xMyDatabase
3metadata:
4  name: my-composite-resource
5  annotations: 
6    crossplane.io/external-name: my-custom-name
7# Removed for brevity

Inside the Composition, use a patch to apply the external-name to the resources.

The fromFieldPath patch copies the metadata.annotations field from the composite resource to the metadata.annotations inside the managed resource.

 1apiVersion: apiextensions.crossplane.io/v1
 2kind: Composition
 3metadata:
 4  name: my-composition
 5spec:
 6  resources:
 7    - name: database
 8      base:
 9        # Removed for brevity
10      patches:
11      - fromFieldPath: metadata.annotations
12        toFieldPath: metadata.annotations

For more information on patching resources refer to the Patch and Transform documentation.

Composition selection

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

1apiVersion: example.org/v1alpha1
2kind: xMyDatabase
3metadata:
4  name: my-composite-resource
5spec:
6  compositionRef:
7    name: my-other-composition
8  # 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: xMyDatabase
3metadata:
4  name: my-composite-resource
5spec:
6  compositionSelector:
7    matchLabels:
8      environment: production
9  # 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: xMyDatabase
3metadata:
4  name: my-composite-resource
5spec:
6  compositionUpdatePolicy: Manual
7  # 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: xMyDatabase
3metadata:
4  name: my-composite-resource
5spec:
6  compositionUpdatePolicy: Manual
7  compositionRevisionRef:
8    name: my-composition-b5aa1eb
9  # Removed for brevity

1kubectl get compositionrevision
2NAME                         REVISION   XR-KIND        XR-APIVERSION            AGE
3my-composition-5c976ad       1          xmydatabases   example.org/v1alpha1     65m
4my-composition-b5aa1eb       2          xmydatabases   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: xMyDatabase
3metadata:
4  name: my-composite-resource
5spec:
6  compositionRevisionSelector:
7    matchLabels:
8      channel: dev
9  # Removed for brevity

Manage connection secrets

When a composite resource creates resources, Crossplane provides any connection secrets to the composite resource.

Use writeConnectionSecretToRef to specify where the composite resource writes their connection secrets to.

For example, this composite resource saves the connection secrets in a Kubernetes secret object named my-secret in the namespace crossplane-system.

1apiVersion: example.org/v1alpha1
2kind: xMyDatabase
3metadata:
4  name: my-composite-resource
5spec:
6  writeConnectionSecretToRef:
7    name: my-secret
8    namespace: crossplane-system
9  # Removed for brevity

Composite resources can write connection secrets to an external secret store, like HashiCorp Vault.

Use the publishConnectionDetailsTo field to save connection secrets to an external secrets store.

1apiVersion: example.org/v1alpha1
2kind: xMyDatabase
3metadata:
4  name: my-composite-resource
5spec:
6  publishConnectionDetailsTo:
7    name: my-external-secret-store
8  # Removed for brevity

Read the External Secrets Store documentation for more information on using external secret stores.

For more information on connection secrets read the Connection Secrets knowledge base article.

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: xMyDatabase
3metadata:
4  name: my-composite-resource
5  annotations:
6    crossplane.io/paused: "true"
7spec:
8  # 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 xMyDatabase.example.org
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 managed resources created in the Resource Refs.

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

Composite resource conditions

The conditions of composite resources match the conditions of their managed resources.

Read the conditions section of the managed resources documentation for details.

Composite resource labels

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

Composite label

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

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

Claim name label

Crossplane adds the crossplane.io/claim-name label to composite resources created from a Claim. The label indicates the name of the Claim linked to this composite resource.

1kubectl describe xmydatabase.example.org/my-claimed-database-x9rx9
2Name:         my-claimed-database2-x9rx9
3Namespace:
4Labels:       crossplane.io/claim-name=my-claimed-database

Composite resources created directly, without using a Claim, don’t have a crossplane.io/claim-name label.

Claim namespace label

Crossplane adds the crossplane.io/claim-namespace label to composite resources created from a Claim. The label indicates the namespace of the Claim linked to this composite resource.

1kubectl describe xmydatabase.example.org/my-claimed-database-x9rx9
2Name:         my-claimed-database2-x9rx9
3Namespace:
4Labels:       crossplane.io/claim-namespace=default

Composite resources created directly, without using a Claim, don’t have a crossplane.io/claim-namespace label.