Composite Resources - Crossplane

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.

{{<hint "tip" >}} Composite resources are a composite of managed resources.
A Composition defines how to compose the managed resources together. {{< /hint >}}

{{<expand "Confused about Compositions, XRDs, XRs and Claims?" >}} Crossplane has four core components that users commonly mix up:

[Compositions]({{<ref "./compositions">}}) - A template to define how to create resources.
[Composite Resource Definition]({{<ref "./composite-resource-definitions">}}) (XRD) - A custom API specification.
Composite Resource (XR) - This page. Created by using the custom API defined in a Composite Resource Definition. XRs use the Composition template to create new managed resources.
[Claims]({{<ref "./claims" >}}) (XRC) - Like a Composite Resource, but with namespace scoping. {{</expand >}}

Creating composite resources

Creating composite resources requires a [Composition]({{<ref "./compositions">}}) and a [CompositeResourceDefinition]({{<ref "./composite-resource-definitions">}}) (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 {{<hover label="xrd1" line="2">}}CompositeResourceDefinition{{</hover>}} creates a custom API endpoint {{<hover label="xrd1" line="4">}}xmydatabases.example.org{{</hover>}}.

yaml

apiVersion: apiextensions.crossplane.io/v1
kind: CompositeResourceDefinition
metadata: 
  name: xmydatabases.example.org
spec:
  group: example.org
  names:
    kind: xMyDatabase
    plural: xmydatabases
  # Removed for brevity

When a user calls the custom API, {{<hover label="xrd1" line="4">}}xmydatabases.example.org{{</hover>}}, Crossplane chooses the Composition to use based on the Composition's {{<hover label="typeref" line="6">}}compositeTypeRef{{</hover>}}

yaml

apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata:
  name: my-composition
spec:
  compositeTypeRef:
    apiVersion: example.org/v1alpha1
    kind: xMyDatabase
  # Removed for brevity

The Composition {{<hover label="typeref" line="6">}}compositeTypeRef{{</hover>}} matches the XRD {{<hover label="xrd1" line="6">}}group{{</hover>}} and {{<hover label="xrd1" line="9">}}kind{{</hover>}}.

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

shell{copy-lines="1"}

kubectl get composite
NAME                    SYNCED   READY   COMPOSITION         AGE
my-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 {{<hover label="annotation" line="5">}}annotation{{</hover>}} to the composite resource.

yaml

apiVersion: example.org/v1alpha1
kind: xMyDatabase
metadata:
  name: my-composite-resource
  annotations: 
    crossplane.io/external-name: my-custom-name
# Removed for brevity

Inside the Composition, use a {{<hover label="comp" line="10">}}patch{{</hover>}} to apply the external-name to the resources.

The {{<hover label="comp" line="11">}}fromFieldPath{{</hover>}} patch copies the {{<hover label="comp" line="11">}}metadata.annotations{{</hover>}} field from the composite resource to the {{<hover label="comp" line="12">}}metadata.annotations{{</hover>}} inside the managed resource.

{{<hint "note" >}} If a managed resource has the crossplane.io/external-name annotation Crossplane uses the annotation value to name the external resource. {{</hint >}}

yaml

apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata:
  name: my-composition
spec:
  mode: Pipeline
  pipeline:
  - step: patch-and-transform
    functionRef:
      name: function-patch-and-transform
    input:
      apiVersion: pt.fn.crossplane.io/v1beta1
      kind: Resources
      resources:
      - name: database
        base:
          # Removed for brevity
        patches:
        - fromFieldPath: metadata.annotations
          toFieldPath: metadata.annotations

For more information on using function-patch-and-transform to patch resources refer to the [Function Patch and Transform]({{<ref "../guides/function-patch-and-transform">}}) documentation.

Composition selection

Select a specific Composition for a composite resource to use with {{<hover label="compref" line="6">}}compositionRef{{</hover>}}

{{<hint "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]({{<ref "./compositions#enable-composite-resources">}}) section of the Composition documentation. {{< /hint >}}

yaml

apiVersion: example.org/v1alpha1
kind: xMyDatabase
metadata:
  name: my-composite-resource
spec:
  compositionRef:
    name: my-other-composition
  # Removed for brevity

A composite resource can also select a Composition based on labels instead of the exact name with a {{<hover label="complabel" line="6">}}compositionSelector{{</hover>}}.

Inside the {{<hover label="complabel" line="7">}}matchLabels{{</hover>}} section provide one or more Composition labels to match.

yaml

apiVersion: example.org/v1alpha1
kind: xMyDatabase
metadata:
  name: my-composite-resource
spec:
  compositionSelector:
    matchLabels:
      environment: production
  # Removed for brevity

Composition revision policy

Crossplane tracks changes to Compositions as [Composition revisions]({{<ref "composition-revisions">}}) .

A composite resource can use a {{<hover label="comprev" line="6">}}compositionUpdatePolicy{{</hover>}} to manually or automatically reference newer Composition revisions.

The default {{<hover label="comprev" line="6">}}compositionUpdatePolicy{{</hover>}} is "Automatic." Composite resources automatically use the latest Composition revision.

Change the policy to {{<hover label="comprev" line="6">}}Manual{{</hover>}} to prevent composite resources from automatically upgrading.

yaml

apiVersion: example.org/v1alpha1
kind: xMyDatabase
metadata:
  name: my-composite-resource
spec:
  compositionUpdatePolicy: Manual
  # Removed for brevity

Composition revision selection

Crossplane records changes to Compositions as [Composition revisions]({{<ref "composition-revisions">}}).
A composite resource can select a specific Composition revision.

Use {{<hover label="comprevref" line="6">}}compositionRevisionRef{{</hover>}} to select a specific Composition revision by name.

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

yaml

apiVersion: example.org/v1alpha1
kind: xMyDatabase
metadata:
  name: my-composite-resource
spec:
  compositionUpdatePolicy: Manual
  compositionRevisionRef:
    name: my-composition-b5aa1eb
  # Removed for brevity

{{<hint "note" >}} Find the Composition revision name from {{<hover label="getcomprev" line="1">}}kubectl get compositionrevision{{</hover>}}

shell

kubectl get compositionrevision
NAME                         REVISION   XR-KIND        XR-APIVERSION            AGE
my-composition-5c976ad       1          xmydatabases   example.org/v1alpha1     65m
my-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 {{<hover label="comprevsel" line="6">}}compositionRevisionSelector{{</hover>}}.

Inside the {{<hover label="comprevsel" line="7">}}matchLabels{{</hover>}} section provide one or more Composition revision labels to match.

yaml

apiVersion: example.org/v1alpha1
kind: xMyDatabase
metadata:
  name: my-composite-resource
spec:
  compositionRevisionSelector:
    matchLabels:
      channel: dev
  # Removed for brevity

Manage connection secrets

When a composite resource creates resources, Crossplane provides any [connection secrets]({{<ref "./managed-resources#writeconnectionsecrettoref">}}) to the composite resource.

A resource may only access connection secrets allowed by the XRD. By default XRDs provide access to all connection secrets generated by managed resources.
Read more about [managing connection secrets]({{<ref "./composite-resource-definitions#manage-connection-secrets">}}) in the XRD documentation. {{< /hint >}}

Use {{<hover label="writesecret" line="6">}}writeConnectionSecretToRef{{</hover>}} 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 {{<hover label="writesecret" line="7">}}my-secret{{</hover>}} in the namespace {{<hover label="writesecret" line="8">}}crossplane-system{{</hover>}}.

yaml

apiVersion: example.org/v1alpha1
kind: xMyDatabase
metadata:
  name: my-composite-resource
spec:
  writeConnectionSecretToRef:
    name: my-secret
    namespace: crossplane-system
  # Removed for brevity

Composite resources can write connection secrets to an [external secret store]({{<ref "../guides/vault-as-secret-store">}}), like HashiCorp Vault.

{{<hint "important" >}} External secret stores are an alpha feature. Alpha features aren't enabled by default. {{< /hint >}}

Use the {{<hover label="publishsecret" line="6">}}publishConnectionDetailsTo{{</hover>}} field to save connection secrets to an external secrets store.

yaml

apiVersion: example.org/v1alpha1
kind: xMyDatabase
metadata:
  name: my-composite-resource
spec:
  publishConnectionDetailsTo:
    name: my-external-secret-store
  # Removed for brevity

Read the [External Secrets Store]({{<ref "../guides/vault-as-secret-store">}}) documentation for more information on using external secret stores.

For more information on connection secrets read the [Connection Secrets knowledge base article]({{<ref "connection-details">}}).

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 {{<hover label="pause" line="4">}}crossplane.io/paused{{</hover>}} annotation.

yaml

apiVersion: example.org/v1alpha1
kind: xMyDatabase
metadata:
  name: my-composite-resource
  annotations:
    crossplane.io/paused: "true"
spec:
  # Removed for brevity

Verify composite resources

Use {{<hover label="getcomposite" line="1">}}kubectl get composite{{</hover>}} to view all the composite resources Crossplane created.

shell{copy-lines="1",label="getcomposite"}

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

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

shell

kubectl get xMyDatabase.example.org
NAME                    SYNCED   READY   COMPOSITION        AGE
my-composite-resource   True     True    my-composition     12m

Use {{<hover label="desccomposite" line="1">}}kubectl describe composite{{</hover>}} to view the linked {{<hover label="desccomposite" line="16">}}Composition Ref{{</hover>}}, and unique managed resources created in the {{<hover label="desccomposite" line="22">}}Resource Refs{{</hover>}}.

yaml

kubectl describe composite my-composite-resource
Name:         my-composite-resource
API Version:  example.org/v1alpha1
Kind:         xMyDatabase
Spec:
  Composition Ref:
    Name:  my-composition
  Composition Revision Ref:
    Name:                     my-composition-cf2d3a7
  Composition Update Policy:  Automatic
  Resource Refs:
    API Version:  s3.aws.upbound.io/v1beta1
    Kind:         Bucket
    Name:         my-composite-resource-fmrks
    API Version:  dynamodb.aws.upbound.io/v1beta1
    Kind:         Table
    Name:         my-composite-resource-wnr9t
# Removed for brevity

Composite resource conditions

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

Read the [conditions section]({{<ref "./managed-resources#conditions">}}) 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 {{<hover label="complabel" line="4">}} crossplane.io/composite{{</hover>}} 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.

shell

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

Claim name label

Crossplane adds the {{<hover label="claimname" line="4">}}crossplane.io/claim-name{{</hover>}} label to composite resources created from a Claim. The label indicates the name of the Claim linked to this composite resource.

shell

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

Composite resources created directly, without using a Claim, don't have a {{<hover label="claimname" line="4">}}crossplane.io/claim-name{{</hover>}} label.

Claim namespace label

Crossplane adds the {{<hover label="claimname" line="4">}}crossplane.io/claim-namespace{{</hover>}} label to composite resources created from a Claim. The label indicates the namespace of the Claim linked to this composite resource.

shell

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

Composite resources created directly, without using a Claim, don't have a {{<hover label="claimname" line="4">}}crossplane.io/claim-namespace{{</hover>}} label.