title	weight	aliases	description
Compositions	30	composition	Compositions are a template for creating Crossplane resources

Compositions are a template for creating multiple managed resources as a single object.

A Composition composes individual managed resources together into a larger, reusable, solution.

An example Composition may combine a virtual machine, storage resources and networking policies. A Composition template links all these individual resources together.

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

• Compositions - This page. A template to define how to create resources.
• [Composite Resource Definition]({{<ref "./composite-resource-definitions">}}) (XRD) - A custom API specification.
• [Composite Resource]({{<ref "./composite-resources">}}) (XR) - 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. {{}}

Creating Compositions

Creating Compositions consists of:

• Resource templates defining the resources to create.
• Enabling Composite Resources to use this Composition template.

Optionally, Compositions also support:

• Modifying and patching resource settings.
• Storing connection details and secrets generated by the managed resources.
• Using Composition Functions to template resources using custom programs.
• Creating a custom check of when a resource is ready to use.

Resource templates

The {{}}resources{{}} field of a Composition's {{}}spec{{}} defines the set of things that a Composite Resource creates.

{{<hint "note" >}} Read more about Composite Resources in the [Composite Resources page]({{<ref "./composite-resources" >}}). {{< /hint >}}

For example, a Composition can define a template to create a virtual machine and an associated storage bucket at the same time.

The {{}}resources{{}} field lists the individual resources with a {{}}name{{}}.
This name identifies the resource inside the Composition and isn't related to the external name used with the Provider.

Template a managed resource

The contents of the {{}}base{{}} are identical to creating a standalone [managed resource]({{<ref "./managed-resources">}}).

This example uses Upbound's Provider AWS to define a S3 storage {{}}Bucket{{}} and EC2 compute {{}}Instance{{}}.

After defining the {{}}apiVersion{{}} and {{}}kind{{}}, define the {{}}spec.forProvider{{}} fields defining the settings of the resource.

apiVersion: apiextensions.crossplane.io/v1
kind: Composition
spec:
  resources:
    - name: StorageBucket
      base:
        apiVersion: s3.aws.upbound.io/v1beta1
        kind: Bucket
        spec:
          forProvider:
            region: "us-east-2"
    - name: VM
      base:
        apiVersion: ec2.aws.upbound.io/v1beta1
        kind: Instance
        spec:
          forProvider:
            ami: ami-0d9858aa3c6322f73
            instanceType: t2.micro
            region: "us-east-2"

When a [Composite Resource]({{<ref "./composite-resources" >}}) uses this Composition template, the Composite Resource creates two new managed resources with all the provided {{}}spec.forProvider{{}} settings.

The {{}}spec{{}} supports any settings used in a managed resource including applying annotations and labels or using a specific providerConfigRef.

{{<hint "note" >}} Compositions allow applying a metadata.name to a resource's {{}}spec{{}} but ignores it. The metadata.name field doesn't influence the name of the managed resource in Crossplane or the external resource inside the Provider.

Use the crossplane.io/external-name annotation on the resource to influence the external resource name. {{< /hint >}}

Template a ProviderConfig

Compositions can define a ProviderConfig like it defines managed resources. Generating a ProviderConfig may be useful in providing unique credentials to each deployment.

apiVersion: apiextensions.crossplane.io/v1
kind: Composition
spec:
  resources:
    - name: my-aws-provider-config
      base:
        apiVersion: aws.upbound.io/v1beta1
        kind: ProviderConfig
        spec:
          source: Secret
          secretRef:
            namespace: crossplane-system
            name: aws-secret
            key: creds

Template another Composite Resource

Compositions can use other Composite Resources to define more complicated templates.

A common use case is a Composition that uses other Compositions. For example, creating a Composition to create a standard set of networking resources that other Compositions reference.

{{< hint "note" >}} Both Compositions must have corresponding XRDs. {{< /hint >}}

This example networking Composition defines the set of resources required to create a new AWS virtual network. This includes a {{}}VPC{{}}, {{}}InternetGateway{{}} and {{}}Subnet{{}}.

apiVersion: apiextensions.crossplane.io/v1
kind: Composition
spec:
  resources:
    - name: vpc-resource
      base:
        apiVersion: ec2.aws.upbound.io/v1beta1
        kind: VPC
        # Removed for Brevity
    - name: gateway-resource
      base:
        apiVersion: ec2.aws.upbound.io/v1beta1
        kind: InternetGateway
        # Removed for Brevity
    - name: subnet-resource
      base:
        apiVersion: ec2.aws.upbound.io/v1beta1
        kind: Subnet
        # Removed for Brevity
  compositeTypeRef:
    apiVersion: aws.platformref.upbound.io/v1alpha1
    kind: XNetwork

The {{}}compositeTypeRef{{}} gives this Composition an {{}}apiVersion{{}} and {{}}kind{{}} to reference in another Composition.

{{<hint "note" >}} The Enabling a Composite Resource section describes the {{}}compositeTypeRef{{}} field. {{< /hint >}}

A second Composition, defining other resources, in this example, an AWS Elastic Kubernetes Cluster, can reference the previous {{}}XNetwork{{}}

apiVersion: apiextensions.crossplane.io/v1
kind: Composition
spec:
  resources:
    - name: nested-network-composition
      base:
        apiVersion: aws.platformref.upbound.io/v1alpha1
        kind: XNetwork
        # Removed for brevity
    - name: eks-cluster-resource
      base:
        apiVersion: eks.aws.upbound.io/v1beta1
        kind: Cluster
        # Removed for brevity

When a Composite Resource creates all the managed resources from this Composition, the resources defined by the {{}}XNetwork{{}} get created along with the EKS {{}}cluster{{}}.

{{<hint "note" >}} This abbreviated example is from the Upbound AWS Reference Platform.

View the complete Compositions in the reference platform's package directory. {{}}

Cross-resource references

Inside a Composition some resources use identifiers or names of other resources. For example, creating a new network and applying the network identifier to a virtual machine.

Resources inside a Composition can cross-reference other resources by matching a label or a controller reference.

{{<hint "note" >}} Providers allow matching of labels and controller references on a per-resource basis. Check the documentation for the specific Provider resource to see what's supported.

Matching labels and controllers isn't supported across different Providers. {{< /hint >}}

Match resource labels

To match a resource label, first apply a {{}}label{{}} to the resource to match and use {{}}matchLabels{{}} in the second resource.

This example creates a AWS {{}}Role{{}} and applies a {{}}label{{}}. The second resource is a {{}}RolePolicyAttachment{{}}, which requires attaching to an existing Role.

Using the resource's {{}}roleSelector.matchLabels{{}} ensures this {{}}RolePolicyAttachment{{}} references the matching {{}}Role{{}}, even if the unique role identifier isn't known.

apiVersion: apiextensions.crossplane.io/v1
kind: Composition
spec:
  resources:
    - base:
        apiVersion: iam.aws.upbound.io/v1beta1
        kind: Role
        name: iamRole
        metadata:
          labels:
            role: controlplane
    - base:
        apiVersion: iam.aws.upbound.io/v1beta1
        kind: RolePolicyAttachment
        name: iamPolicy
        spec:
          forProvider:
            roleSelector:
              matchLabels:
                role: controlplane
  # Removed for brevity

Match a controller reference

Matching a controller reference ensures that the matching resource is in the same composite resource.

Matching only a controller reference simplifies the matching process without requiring labels or more information.

For example, creating an AWS {{}}InternetGateway{{}} requires a {{}}VPC{{}}.

The {{}}InternetGateway{{}} could match a label, but every VPC created by this Composition share the same label.

Using {{}}matchControllerRef{{}} matches only the VPC created in the same composite resource that created the {{}}InternetGateway{{}}.

apiVersion: apiextensions.crossplane.io/v1
kind: Composition
spec:
  resources:
    - base:
        apiVersion: ec2.aws.upbound.io/v1beta1
        kind: VPC
        name: my-vpc
        spec:
          forProvider:
          # Removed for brevity
    - base:
        apiVersion: ec2.aws.upbound.io/v1beta1
        kind: InternetGateway
        name: my-gateway
        spec:
          forProvider:
            vpcIdSelector:
              matchControllerRef: true
# Removed for brevity

Resources can match both labels and a controller reference to match a specific resource in the larger composite resource.

For example, this Composition creates two {{}}VPC{{}} resources, but the {{}}InternetGateway{{}} must match only one.

Applying a {{}}label{{}} to the second {{}}VPC{{}} allows the {{}}InternetGateway{{}} to match the label {{}}type: internet{{}} and only match objects in the same composite resource with {{}}matchControllerRef{{}}.

apiVersion: apiextensions.crossplane.io/v1
kind: Composition
spec:
  resources:
    - base:
        apiVersion: ec2.aws.upbound.io/v1beta1
        kind: VPC
        name: my-first-vpc
        metadata:
          labels:
            type: backend
        spec:
          forProvider:
          # Removed for brevity
    - base:
        apiVersion: ec2.aws.upbound.io/v1beta1
        kind: VPC
        name: my-second-vpc
        metadata:
          labels:
            type: internet
        spec:
          forProvider:
          # Removed for brevity
    - base:
        apiVersion: ec2.aws.upbound.io/v1beta1
        kind: InternetGateway
        name: my-gateway
        spec:
          forProvider:
            vpcIdSelector:
              matchControllerRef: true
              matchLabels:
                type: internet
# Removed for brevity

Enabling Composite Resources

A Composition is only a template defining how to create managed resources. A Composition limits which Composite Resources can use this template.

A Composition's {{}}compositeTypeRef{{}} defines which Composite Resource type can use this Composition.

{{<hint "note" >}} Read more about Composite Resources in the [Composite Resources page]({{<ref "./composite-resources" >}}). {{< /hint >}}

Inside a Composition's {{}}spec{{}} define the Composite Resource {{}}apiVersion{{}} and {{}}kind{{}} that the Composition allows to use this template.

apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata:
  name: dynamodb-with-bucket
spec:
  compositeTypeRef:
    apiVersion: custom-api.example.org/v1alpha1
    kind: database
  # Removed for brevity

Changing resource fields

Most Compositions require customizing the fields of the resources. This can include applying unique passwords, modifying where to deploy resources, or applying labels or annotations.

The primary method to change resources is using a resource [patch and transform]({{<ref "./patch-and-transform" >}}). Patch and transforms allow matching specific input fields, modifying them and applying them to the managed resource.

{{<hint "important" >}} The details of creating patch and transforms and their options are in the [Patch and Transform page]({{<ref "./patch-and-transform" >}}).

This section describes applying patches and transforms to Compositions. {{< /hint >}}

Apply patches to individual resources with the {{}}patches{{}} field.

For example, taking the {{}}location{{}} provided in a Claim and applying it to the {{}}region{{}} value in the managed resource.

apiVersion: example.org/v1alpha1
kind: ExampleClaim
metadata:
  name: my-example-claim
spec:
  location: "eu-north-1"

The Composition patch uses the {{}}fromFieldPath{{}} to match the {{}}location{{}} field in the Claim and the {{}}toFieldPath{{}} to define which field to change inside the Composition.

apiVersion: apiextensions.crossplane.io/v1
kind: Composition
# Removed for Brevity
spec:
  resources:
    - name: s3Bucket
      base:
        apiVersion: s3.aws.upbound.io/v1beta1
        kind: Bucket
        spec:
          forProvider:
            region: "us-east-2"
      patches:
      - type: FromCompositeFieldPath
        fromFieldPath: "spec.location"
        toFieldPath: "spec.forProvider.region"

Patch sets

Some Compositions have resources which need identical patches applied. Instead of repeating the same patches field, resources can reference a single patchSet.

Define a {{}}patchSet{{}} with a {{}}name{{}} and {{}}patch{{}} operations.

Then apply the {{}}patchSet{{}} to each resource with {{}}type: patchSet{{< /hover >}}, referencing the {{}}name{{< /hover >}} in the {{}}patchSetName{{< /hover >}} field.

apiVersion: apiextensions.crossplane.io/v1
kind: Composition
# Removed for Brevity
spec:
  patchSets:
    - name: reusable-patch
      patches:
      - type: FromCompositeFieldPath
        fromFieldPath: "location"
        toFieldPath: "spec.forProvider.region"
  resources:
    - name: first-resource
      base:
      # Removed for Brevity
      patches:
        - type: PatchSet
          patchSetName: reusable-patch
    - name: second-resource
      base:
      # Removed for Brevity
      patches:
        - type: PatchSet
          patchSetName: reusable-patch

Patch with EnvironmentConfigs

Crossplane uses EnvironmentConfigs to create in-memory data stores. Compositions can read and write from this data store as part of the patch process.

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

EnvironmentConfigs can predefine data that Compositions can use or a Composite Resource can write data to their in-memory environment for other resources to read.

{{< hint "note" >}}

Read the [EnvironmentConfigs]({{<ref "./environment-configs" >}}) page for more information on using EnvironmentConfigs. {{< /hint >}}

To apply a patch using EnvironmentConfigs, first define which EnvironmentConfigs to use with {{}}environment.environmentConfigs{{}}.

Use either a [reference]({{<ref "./managed-resources#matching-by-name-reference" >}}) or a [selector]({{<ref "./managed-resources#matching-by-selector" >}}) to identify the EnvironmentConfigs to use.

apiVersion: apiextensions.crossplane.io/v1
kind: Composition
# Removed for Brevity
spec:
  environment:
    environmentConfigs:
      - ref:
          name: example-environment
  resources:
  # Removed for Brevity

Patch a composite resource

To patch between the composite resource and the in-memory environment use {{< hover label="xrpatch" line="7">}}patches{{}} inside of the {{< hover label="xrpatch" line="5">}}environment{{}}.

Use the {{< hover label="xrpatch" line="5">}}ToCompositeFieldPath{{}} to copy data from the in-memory environment to the composite resource.
Use the {{< hover label="xrpatch" line="5">}}FromCompositeFieldPath{{}} to copy data from the composite resource to the in-memory environment.

apiVersion: apiextensions.crossplane.io/v1
kind: Composition
# Removed for Brevity
spec:
  environment:
  # Removed for Brevity
      patches:
      - type: ToCompositeFieldPath
        fromFieldPath: tags
        toFieldPath: metadata.labels[envTag]
      - type: FromCompositeFieldPath
        fromFieldPath: metadata.name
        toFieldPath: newEnvironmentKey

Individual resources can use any data written to their in-memory environment.

Patch an individual resource

To patch an individual resource, inside the {{}}patches{{}} of the resource, use {{}}ToEnvironmentFieldPath{{}} to copy data from the resource to the in-memory environment.
Use {{}}FromEnvironmentFieldPath{{}} to copy data to the resource from the in-memory environment.

apiVersion: apiextensions.crossplane.io/v1
kind: Composition
# Removed for Brevity
spec:
  environment:
  # Removed for Brevity
  resources:
  # Removed for Brevity
    - name: vpc
      base:
        apiVersion: ec2.aws.upbound.io/v1beta1
        kind: VPC
        spec:
          forProvider:
            cidrBlock: 172.16.0.0/16
      patches:
        - type: ToEnvironmentFieldPath
          fromFieldPath: status.atProvider.id
          toFieldPath: vpcId
        - type: FromEnvironmentFieldPath
          fromFieldPath: tags
          toFieldPath: spec.forProvider.tags

The [EnvironmentConfigs]({{<ref "./environment-configs" >}}) page has more information on EnvironmentConfigs options and usage.

Use composition functions

Composition functions (or just functions, for short) are custom programs that template Crossplane resources. You can write a function to template resources using a general purpose programming language like Go or Python. Using a general purpose programming language allows a function to use more advanced logic to template resources, like loops and conditionals.

{{<hint "important" >}} Composition functions is a beta feature. Crossplane enables beta functions by default. The [Composition Functions]({{<ref "./composition-functions#disable-composition-functions">}}) page explains how to disable composition functions. {{< /hint >}}

To use composition functions set the Composition {{}}mode{{}} to {{}}Pipeline{{}}.

Define a {{}}pipeline{{}} of {{}}steps{{}}. Each {{}}step{{}} calls a Function.

Each {{}}step{{}} uses a {{}}functionRef{{}} to reference the {{}}name{{}} of the Function to call.

Some Functions also allow you to specify an {{}}input{{}}.
The function defines the {{}}kind{{}} of input.

{{<hint "important" >}} Compositions using {{}}mode: Pipeline{{}} can't specify resource templates with a resources field.

Use function "Patch and Transform" to create resource templates. {{< /hint >}}

This example uses Function Patch and Transform. Function Patch and Transform is a function that implements Crossplane resource templates. You can use Function Patch and Transform to specify resource templates in a pipeline with other Functions.

apiVersion: apiextensions.crossplane.io/v1
kind: Composition
# Removed for Brevity
spec:
  # Removed for Brevity
  mode: Pipeline
  pipeline:
  - step: patch-and-transform
    functionRef:
      name: function-patch-and-transform
    input:
      apiVersion: pt.fn.crossplane.io/v1beta1
      kind: Resources
      resources:
      - name: storage-bucket
        base:
          apiVersion: s3.aws.upbound.io/v1beta1
          kind: Bucket
          spec:
            forProvider:
              region: "us-east-2"

Read the [composition functions]({{<ref "./composition-functions">}}) page for details on building and using composition functions.

Storing connection details

Some managed resources generate unique details like usernames, passwords, IP addresses, ports or other connection details.

When resources inside a Composition create connection details Crossplane creates a Kubernetes secret object for each managed resource generating connection details.

{{<hint "note">}} This section discusses creating Kubernetes secrets.
Crossplane also supports using external secret stores like HashiCorp Vault.

Read the [external secrets store guide]({{<ref "../guides/vault-as-secret-store">}}) for more information on using Crossplane with an external secret store. {{}}

Composite resource combined secret

Crossplane can combine all the secrets generated by the resources inside a Composition into a single Kubernetes secret and optionally copy the secret object for [Claims]({{<ref "./claims#claim-connection-secrets">}}).

Set the value of {{}}writeConnectionSecretsToNamespace{{}} to the namespace where Crossplane should store the combined secret object.

apiVersion: apiextensions.crossplane.io/v1
kind: Composition
# Removed for Brevity
spec:
  writeConnectionSecretsToNamespace: my-namespace
  resources:
  # Removed for brevity

Composed resource secrets

Inside the {{}}spec{{}} of each resource producing connection details, define the {{}}writeConnectionSecretToRef{{}}, with a {{}}namespace{{}} and {{}}name{{}} of the secret object for the resource.

If a {{}}writeConnectionSecretToRef{{}} isn't defined, Crossplane doesn't write any keys to the secret.

apiVersion: apiextensions.crossplane.io/v1
kind: Composition
spec:
  writeConnectionSecretsToNamespace: other-namespace
  resources:
    - name: key
      base:
        apiVersion: iam.aws.upbound.io/v1beta1
        kind: AccessKey
        spec:
          forProvider:
          # Removed for brevity
          writeConnectionSecretToRef:
            namespace: docs
            name: key1

Crossplane saves a secret with the {{}}name{{}} in the {{}}namespace{{}} provided.

kubectl get secrets -n docs
NAME   TYPE                                DATA   AGE
key1   connection.crossplane.io/v1alpha1   4      4m30s

{{<hint "tip" >}}

Crossplane recommends using a [Patch]({{<ref "./patch-and-transform">}}) to create a unique name for each secret.

For example, a {{}}patch{{}} to add the unique identifier of the resource as the key name.

apiVersion: apiextensions.crossplane.io/v1
kind: Composition
spec:
  # Removed for brevity
  resources:
    - name: key
      base:
        apiVersion: iam.aws.upbound.io/v1beta1
        kind: AccessKey
        spec:
        # Removed for brevity
          writeConnectionSecretToRef:
            namespace: docs
            name: key1
      patches:
        - fromFieldPath: "metadata.uid"
          toFieldPath: "spec.writeConnectionSecretToRef.name"
          transforms:
            - type: string
              string:
                fmt: "%s-secret"

{{< /hint >}}

Define secret keys

A Composition must define the specific secret keys a resource creates with the {{}}connectionDetails{{}} object.

{{<table "table table-sm" >}}

Secret Type	Description
{{}}fromConnectionSecretKey{{}}	Create a secret key matching the key of a secret generated by the resource.
{{}}fromFieldPath{{}}	Create a secret key matching a field path of the resource.
{{}}value{{}}	Create a secret key with a predefined value.
{{< /table >}}

{{<hint "note">}} The {{}}value{{}} type must use a string value.

The {{}}value{{}} isn't added to the individual resource secret object. The {{}}value{{}} only appears in the combined composite resource secret. {{< /hint >}}

kind: Composition
spec:
  writeConnectionSecretsToNamespace: other-namespace
  resources:
    - name: key
      base:
        # Removed for brevity
        spec:
          forProvider:
          # Removed for brevity
          writeConnectionSecretToRef:
            namespace: docs
            name: key1
      connectionDetails:
        - name: myUsername
          fromConnectionSecretKey: username
        - name: myFieldSecret
          fromFieldPath: spec.forProvider.user
        - name: myStaticSecret
          value: "docs.crossplane.io"

The {{}}connectionDetails{{}} in a resource can reference a secret from a resource with {{}}fromConnectionSecretKey{{}},
from another field in the resource with {{}}fromFieldPath{{}}
or a statically defined value with {{}}value{{}}.

Crossplane sets the secret key to the {{}}name{{}} value.

Describe the secret to view the secret keys inside the secret object.

{{<hint "tip" >}} If more than one resource generates secrets with the same secret key name, Crossplane only saves one value.

Use a custom {{}}name{{}} to create unique secret keys. {{< /hint >}}

{{<hint "important">}} Crossplane only adds connection details listed in the {{}}connectionDetails{{}} to the combined secret object.
Any connection secrets in a managed resource, not defined in the {{}}connectionDetails{{}} aren't added to the combined secret object.
{{< /hint >}}

kubectl describe secret
Name:         my-access-key-secret
Namespace:    default
Labels:       <none>
Annotations:  <none>

Type:  connection.crossplane.io/v1alpha1

Data
====
myUsername:      20 bytes
myFieldSecret:   24 bytes
myStaticSecret:  18 bytes

{{<hint "note" >}} The CompositeResourceDefinition can also limit which keys Crossplane stores from the composite resources.
By default an XRD writes all secret keys listed in the composed resources connectionDetails to the combined secret object.

Read the [CompositeResourceDefinition documentation]({{<ref "composite-resource-definitions#manage-connection-secrets">}}) for more information on restricting secret keys. {{< /hint >}}

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

{{<hint "warning">}} You can't change the {{}}connectionDetails{{}} of a Composition.
You must delete and recreate the Composition to change the {{}}connectionDetails{{}} . {{}}

Save connection details to an external secret store

Crossplane [External Secret Stores]({{<ref "../guides/vault-as-secret-store" >}}) write secrets and connection details to external secret stores like HashiCorp Vault.

{{<hint "important" >}} External Secret Stores are an alpha feature.

They're not recommended for production use. Crossplane disables External Secret Stores by default. {{< /hint >}}

Use {{}}publishConnectionDetailsWithStoreConfigRef{{}} in place of writeConnectionSecretsToNamespace to define the {{}}StoreConfig{{}} to save connection details to.

For example, using a {{}}StoreConfig{{}} with the {{}}name{{}} "vault," use {{}}publishConnectionDetailsWithStoreConfigRef.name{{}} matching the {{}}StoreConfig.name{{}}, in this example, "vault."

apiVersion: gcp.crossplane.io/v1alpha1
kind: StoreConfig
metadata:
  name: vault
# Removed for brevity.
---
apiVersion: apiextensions.crossplane.io/v1
kind: Composition
# Removed for Brevity
spec:
  publishConnectionDetailsWithStoreConfigRef: 
    name: vault
  resources:
  # Removed for brevity

For more details read the [External Secret Stores]({{<ref "../guides/vault-as-secret-store" >}}) integration guide.

Resource readiness checks

By default Crossplane considers a Composite Resource or Claim as READY when the status of all created resource are Type: Ready and Status: True

Some resources, for example, a ProviderConfig, don't have a Kubernetes status and are never considered Ready.

Custom readiness checks allow Compositions to define what custom conditions to meet for a resource to be Ready.

{{< hint "tip" >}} Use multiple readiness checks if a resource must meet multiple conditions for it to be Ready. {{< /hint >}}

Define a custom readiness check with the {{}}readinessChecks{{}} field on a resource.

Checks have a {{}}type{{}} defining how to match the resource and a {{}}fieldPath{{}} of which field in the resource to compare.

apiVersion: apiextensions.crossplane.io/v1
kind: Composition
# Removed for Brevity
spec:
  resources:
  # Removed for Brevity
    - name: my-resource
      base:
        # Removed for brevity
      readinessChecks:
        - type: <match type>
          fieldPath: <resource field>

Compositions support matching resource fields by:

• string match
• integer match
• non-empty match
• always ready
• condition match
• boolean match

Match a string

{{}}MatchString{{}} considers the composed resource to be ready when the value of a field in that resource matches a specified string.

{{<hint "note" >}}

Crossplane only supports exact string matches. Substrings and regular expressions aren't supported in a readiness check.

{{}}

For example, matching the string {{}}Online{{}} in the resource's {{}}status.atProvider.state{{}} field.

apiVersion: apiextensions.crossplane.io/v1
kind: Composition
# Removed for Brevity
spec:
  resources:
  # Removed for Brevity
    - name: my-resource
      base:
        # Removed for brevity
      readinessChecks:
        - type: MatchString
          fieldPath: status.atProvider.state
          matchString: "Online"

Match an integer

{{}}MatchInteger{{}} considers the composed resource to be ready when the value of a field in that resource matches a specified integer.

{{<hint "note" >}}

Crossplane doesn't support matching 0.

{{}}

For example, matching the number {{}}4{{}} in the resource's {{}}status.atProvider.state{{}} field.

apiVersion: apiextensions.crossplane.io/v1
kind: Composition
# Removed for Brevity
spec:
  resources:
  # Removed for Brevity
    - name: my-resource
      base:
        # Removed for brevity
      readinessChecks:
        - type: MatchInteger
          fieldPath: status.atProvider.state
          matchInteger: 4

Match that a field exists

{{}}NonEmpty{{}} considers the composed resource to be ready when a field exists with a value.

{{<hint "note" >}}

Crossplane considers a value of 0 or an empty string as empty. {{}}

For example, to check that a resource's {{}}status.atProvider.state{{}} field isn't empty.

apiVersion: apiextensions.crossplane.io/v1
kind: Composition
# Removed for Brevity
spec:
  resources:
  # Removed for Brevity
    - name: my-resource
      base:
        # Removed for brevity
      readinessChecks:
        - type: NonEmpty
          fieldPath: status.atProvider.state

{{<hint "tip" >}} Checking {{}}NonEmpty{{}} doesn't require setting any other fields. {{< /hint >}}

Always consider a resource ready

{{}}None{{}} considers the composed resource to be ready as soon as it's created. Crossplane doesn't wait for any other conditions before declaring the resource ready.

For example, consider {{}}my-resource{{}} ready as soon as it's created.

apiVersion: apiextensions.crossplane.io/v1
kind: Composition
# Removed for Brevity
spec:
  resources:
  # Removed for Brevity
    - name: my-resource
      base:
        # Removed for brevity
      readinessChecks:
        - type: None

Match a condition

{{}}Condition{{}} considers the composed resource to be ready when it finds the expected condition type, with the expected status for it in its status.conditions.

For example, consider {{}}my-resource{{}}, which is ready if there is a condition of type {{}}MyType{{}} with a status of {{}}Success{{}}.

apiVersion: apiextensions.crossplane.io/v1
kind: Composition
# Removed for Brevity
spec:
  resources:
  # Removed for Brevity
    - name: my-resource
      base:
        # Removed for brevity
      readinessChecks:
        - type: MatchCondition
          matchCondition:
            type: MyType
            status: Success

Match a boolean

Two types of checks exist for matching boolean fields:

• MatchTrue
• MatchFalse

MatchTrue considers the composed resource to be ready when the value of a field inside that resource is true.

MatchFalse considers the composed resource to be ready when the value of a field inside that resource is false.

For example, consider {{}}my-resource{{}}, which is ready if {{}} status.atProvider.manifest.status.ready{{}} is {{}}true{{}}.

apiVersion: apiextensions.crossplane.io/v1
kind: Composition
# Removed for Brevity
spec:
  resources:
  # Removed for Brevity
    - name: my-resource
      base:
        # Removed for brevity
      readinessChecks:
        - type: MatchTrue
          fieldPath: status.atProvider.manifest.status.ready

{{<hint "tip" >}} Checking {{}}MatchTrue{{}} doesn't require setting any other fields. {{< /hint >}}

MatchFalse matches fields that express readiness with the value false.

For example, consider {{}}my-resource{{}}, is ready if {{}} status.atProvider.manifest.status.pending{{}} is {{}}false{{}}.

apiVersion: apiextensions.crossplane.io/v1
kind: Composition
# Removed for Brevity
spec:
  resources:
  # Removed for Brevity
    - name: my-resource
      base:
        # Removed for brevity
      readinessChecks:
        - type: MatchFalse
          fieldPath: status.atProvider.manifest.status.pending

{{<hint "tip" >}} Checking {{}}MatchFalse{{}} doesn't require setting any other fields. {{< /hint >}}

Verify a Composition

View all available Compositions with kubectl get composition.

kubectl get composition
NAME                                       XR-KIND        XR-APIVERSION                         AGE
xapps.aws.platformref.upbound.io           XApp           aws.platformref.upbound.io/v1alpha1   123m
xclusters.aws.platformref.upbound.io       XCluster       aws.platformref.upbound.io/v1alpha1   123m
xeks.aws.platformref.upbound.io            XEKS           aws.platformref.upbound.io/v1alpha1   123m
xnetworks.aws.platformref.upbound.io       XNetwork       aws.platformref.upbound.io/v1alpha1   123m
xservices.aws.platformref.upbound.io       XServices      aws.platformref.upbound.io/v1alpha1   123m
xsqlinstances.aws.platformref.upbound.io   XSQLInstance   aws.platformref.upbound.io/v1alpha1   123m

The XR-KIND lists the Composite Resource kind that's allowed to use the Composition template.
The XR-APIVERSION lists the Composite Resource API versions allowed to use the Composition template.

{{<hint "note" >}} The output of kubectl get composition is different than kubectl get composite.

kubectl get composition lists all available Compositions.

kubectl get composite lists all created Composite Resources and their related Composition. {{< /hint >}}

Composition validation

When creating a Composition, Crossplane automatically validates its integrity, checking that the Composition is well formed, for example:

If using mode: Resources:

• The resources field isn't empty.
• All resources either use a name or don't. Compositions can't use both named and unnamed resources.
• No duplicate resource names.
• Patch sets must have names.
• Patches that require a fromFieldPath value provide it.
• Patches that require a toFieldPath value provide it.
• Patches that require a combine field provide it.
• Readiness checks using matchString aren't empty.
• Readiness checks using matchInteger isn't 0.
• Readiness checks requiring a fieldPath value provide it.

If using mode: Pipeline (Composition Functions):

• The pipeline field isn't empty.
• No duplicate step names.

Composition schema aware validation

Crossplane also performs schema aware validation of Compositions. Schema validation checks that patches, readinessChecks and connectionDetails are valid according to the resource schemas. For example, checking that the source and destination fields of a patch are valid according to the source and destination resource schema.

{{<hint "note" >}} Composition schema aware validation is a beta feature. Crossplane enables beta features by default.

Disable schema aware validation by setting the --enable-composition-webhook-schema-validation=false flag on the Crossplane pod.

The [Crossplane Pods]({{<ref "./pods#edit-the-deployment">}}) page has more information on enabling Crossplane flags. {{< /hint >}}

Schema aware validation modes

Crossplane always rejects Compositions in case of integrity errors.

Set the schema aware validation mode to configure how Crossplane handles both missing resource schemas and schema aware validation errors.

{{<hint "note" >}} If a resource schema is missing, Crossplane skips schema aware validation but still returns an error for integrity errors and a warning or an error for the missing schemas. {{< /hint >}}

The following modes are available:

{{< table "table table-sm table-striped" >}}

Mode	Missing Schema	Schema Aware Error	Integrity Error
warn	Warning	Warning	Error
loose	Warning	Error	Error
strict	Error	Error	Error
{{< /table >}}

Change the validation mode for a Composition with the {{}}crossplane.io/composition-schema-aware-validation-mode{{}} annotation.

If not specified, the default mode is warn.

For example, to enable loose mode checking set the annotation value to {{}}loose{{}}.

apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata:
  annotations:
    crossplane.io/composition-schema-aware-validation-mode: loose
  # Removed for brevity
spec:
  # Removed for brevity

{{<hint "important" >}} Validation modes also apply to Compositions defined by Configuration packages.

Depending on the mode configured in the Composition, schema aware validation issues may result in warnings or the rejection of the Composition.

View the Crossplane logs for validation warnings.

Crossplane sets a Configuration as unhealthy if there are validation errors. View the Configuration details with kubectl describe configuration to see the specific errors. {{< /hint >}}