Compositions

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.

Crossplane has four core components that users commonly mix up:

Compositions - This page. A template to define how to create resources.
Composite Resource Definition (XRD) - A custom API specification.
Composite Resource (XR) - Created by using the custom API defined in a Composite Resource Definition. XRs use the Composition template to create new managed resources.
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.

Note

Read more about Composite Resources in the Composite Resources page.

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.

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.

 1apiVersion: apiextensions.crossplane.io/v1
 2kind: Composition
 3spec:
 4  resources:
 5    - name: StorageBucket
 6      base:
 7        apiVersion: s3.aws.upbound.io/v1beta1
 8        kind: Bucket
 9        spec:
10          forProvider:
11            region: "us-east-2"
12    - name: VM
13      base:
14        apiVersion: ec2.aws.upbound.io/v1beta1
15        kind: Instance
16        spec:
17          forProvider:
18            ami: ami-0d9858aa3c6322f73
19            instanceType: t2.micro
20            region: "us-east-2"

When a Composite Resource 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.

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.

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.

 1apiVersion: apiextensions.crossplane.io/v1
 2kind: Composition
 3spec:
 4  resources:
 5    - name: my-aws-provider-config
 6      base:
 7        apiVersion: aws.upbound.io/v1beta1
 8        kind: ProviderConfig
 9        spec:
10          source: Secret
11          secretRef:
12            namespace: crossplane-system
13            name: aws-secret
14            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.

Note

Both Compositions must have corresponding XRDs.

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

 1apiVersion: apiextensions.crossplane.io/v1
 2kind: Composition
 3spec:
 4  resources:
 5    - name: vpc-resource
 6      base:
 7        apiVersion: ec2.aws.upbound.io/v1beta1
 8        kind: VPC
 9        # Removed for Brevity
10    - name: gateway-resource
11      base:
12        apiVersion: ec2.aws.upbound.io/v1beta1
13        kind: InternetGateway
14        # Removed for Brevity
15    - name: subnet-resource
16      base:
17        apiVersion: ec2.aws.upbound.io/v1beta1
18        kind: Subnet
19        # Removed for Brevity
20  compositeTypeRef:
21    apiVersion: aws.platformref.upbound.io/v1alpha1
22    kind: XNetwork

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

Note

The Enabling a Composite Resource section describes the compositeTypeRef field.

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

 1apiVersion: apiextensions.crossplane.io/v1
 2kind: Composition
 3spec:
 4  resources:
 5    - name: nested-network-composition
 6      base:
 7        apiVersion: aws.platformref.upbound.io/v1alpha1
 8        kind: XNetwork
 9        # Removed for brevity
10    - name: eks-cluster-resource
11      base:
12        apiVersion: eks.aws.upbound.io/v1beta1
13        kind: Cluster
14        # 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.

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.

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.

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.

 1apiVersion: apiextensions.crossplane.io/v1
 2kind: Composition
 3spec:
 4  resources:
 5    - base:
 6        apiVersion: iam.aws.upbound.io/v1beta1
 7        kind: Role
 8        name: iamRole
 9        metadata:
10          labels:
11            role: controlplane
12    - base:
13        apiVersion: iam.aws.upbound.io/v1beta1
14        kind: RolePolicyAttachment
15        name: iamPolicy
16        spec:
17          forProvider:
18            roleSelector:
19              matchLabels:
20                role: controlplane
21  # 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.

 1apiVersion: apiextensions.crossplane.io/v1
 2kind: Composition
 3spec:
 4  resources:
 5    - base:
 6        apiVersion: ec2.aws.upbound.io/v1beta1
 7        kind: VPC
 8        name: my-vpc
 9        spec:
10          forProvider:
11          # Removed for brevity
12    - base:
13        apiVersion: ec2.aws.upbound.io/v1beta1
14        kind: InternetGateway
15        name: my-gateway
16        spec:
17          forProvider:
18            vpcIdSelector:
19              matchControllerRef: true
20# 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.

 1apiVersion: apiextensions.crossplane.io/v1
 2kind: Composition
 3spec:
 4  resources:
 5    - base:
 6        apiVersion: ec2.aws.upbound.io/v1beta1
 7        kind: VPC
 8        name: my-first-vpc
 9        metadata:
10          labels:
11            type: backend
12        spec:
13          forProvider:
14          # Removed for brevity
15    - base:
16        apiVersion: ec2.aws.upbound.io/v1beta1
17        kind: VPC
18        name: my-second-vpc
19        metadata:
20          labels:
21            type: internet
22        spec:
23          forProvider:
24          # Removed for brevity
25    - base:
26        apiVersion: ec2.aws.upbound.io/v1beta1
27        kind: InternetGateway
28        name: my-gateway
29        spec:
30          forProvider:
31            vpcIdSelector:
32              matchControllerRef: true
33              matchLabels:
34                type: internet
35# 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.

Note

Read more about Composite Resources in the Composite Resources page.

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

1apiVersion: apiextensions.crossplane.io/v1
2kind: Composition
3metadata:
4  name: dynamodb-with-bucket
5spec:
6  compositeTypeRef:
7    apiVersion: custom-api.example.org/v1alpha1
8    kind: database
9  # 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. Patch and transforms allow matching specific input fields, modifying them and applying them to the managed resource.

Important

The details of creating patch and transforms and their options are in the Patch and Transform page.

This section describes applying patches and transforms to Compositions.

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.

1apiVersion: example.org/v1alpha1
2kind: ExampleClaim
3metadata:
4  name: my-example-claim
5spec:
6  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.

 1apiVersion: apiextensions.crossplane.io/v1
 2kind: Composition
 3# Removed for Brevity
 4spec:
 5  resources:
 6    - name: s3Bucket
 7      base:
 8        apiVersion: s3.aws.upbound.io/v1beta1
 9        kind: Bucket
10        spec:
11          forProvider:
12            region: "us-east-2"
13      patches:
14      - type: FromCompositeFieldPath
15        fromFieldPath: "spec.location"
16        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, referencing the name in the patchSetName field.

 1apiVersion: apiextensions.crossplane.io/v1
 2kind: Composition
 3# Removed for Brevity
 4spec:
 5  patchSets:
 6    - name: reusable-patch
 7      patches:
 8      - type: FromCompositeFieldPath
 9        fromFieldPath: "location"
10        toFieldPath: "spec.forProvider.region"
11  resources:
12    - name: first-resource
13      base:
14      # Removed for Brevity
15      patches:
16        - type: PatchSet
17          patchSetName: reusable-patch
18    - name: second-resource
19      base:
20      # Removed for Brevity
21      patches:
22        - type: PatchSet
23          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.

Important

EnvironmentConfigs are an alpha feature. Alpha features aren’t enabled by default.

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.

Note

Read the EnvironmentConfigs page for more information on using EnvironmentConfigs.

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

Use either a reference or a selector to identify the EnvironmentConfigs to use.

 1apiVersion: apiextensions.crossplane.io/v1
 2kind: Composition
 3# Removed for Brevity
 4spec:
 5  environment:
 6    environmentConfigs:
 7      - ref:
 8          name: example-environment
 9  resources:
10  # Removed for Brevity

Patch a composite resource

To patch between the composite resource and the in-memory environment use patches inside of the environment.

Use the ToCompositeFieldPath to copy data from the in-memory environment to the composite resource.
Use the FromCompositeFieldPath to copy data from the composite resource to the in-memory environment.

 1apiVersion: apiextensions.crossplane.io/v1
 2kind: Composition
 3# Removed for Brevity
 4spec:
 5  environment:
 6  # Removed for Brevity
 7      patches:
 8      - type: ToCompositeFieldPath
 9        fromFieldPath: tags
10        toFieldPath: metadata.labels[envTag]
11      - type: FromCompositeFieldPath
12        fromFieldPath: metadata.name
13        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.

 1apiVersion: apiextensions.crossplane.io/v1
 2kind: Composition
 3# Removed for Brevity
 4spec:
 5  environment:
 6  # Removed for Brevity
 7  resources:
 8  # Removed for Brevity
 9    - name: vpc
10      base:
11        apiVersion: ec2.aws.upbound.io/v1beta1
12        kind: VPC
13        spec:
14          forProvider:
15            cidrBlock: 172.16.0.0/16
16      patches:
17        - type: ToEnvironmentFieldPath
18          fromFieldPath: status.atProvider.id
19          toFieldPath: vpcId
20        - type: FromEnvironmentFieldPath
21          fromFieldPath: tags
22          toFieldPath: spec.forProvider.tags

The EnvironmentConfigs 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.

Important

Composition functions is a beta feature. Crossplane enables beta functions by default. The Composition Functions page explains how to disable composition functions.

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.

Important

Compositions using mode: Pipeline can’t specify resource templates with a resources field.

Use function “Patch and Transform” to create resource templates.

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.

 1apiVersion: apiextensions.crossplane.io/v1
 2kind: Composition
 3# Removed for Brevity
 4spec:
 5  # Removed for Brevity
 6  mode: Pipeline
 7  pipeline:
 8  - step: patch-and-transform
 9    functionRef:
10      name: function-patch-and-transform
11    input:
12      apiVersion: pt.fn.crossplane.io/v1beta1
13      kind: Resources
14      resources:
15      - name: storage-bucket
16        base:
17          apiVersion: s3.aws.upbound.io/v1beta1
18          kind: Bucket
19          spec:
20            forProvider:
21              region: "us-east-2"

Read the 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.

Note

This section discusses creating Kubernetes secrets.
Crossplane also supports using external secret stores like HashiCorp Vault.

Read the external secrets store guide 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.

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

1apiVersion: apiextensions.crossplane.io/v1
2kind: Composition
3# Removed for Brevity
4spec:
5  writeConnectionSecretsToNamespace: my-namespace
6  resources:
7  # 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.

 1apiVersion: apiextensions.crossplane.io/v1
 2kind: Composition
 3spec:
 4  writeConnectionSecretsToNamespace: other-namespace
 5  resources:
 6    - name: key
 7      base:
 8        apiVersion: iam.aws.upbound.io/v1beta1
 9        kind: AccessKey
10        spec:
11          forProvider:
12          # Removed for brevity
13          writeConnectionSecretToRef:
14            namespace: docs
15            name: key1

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

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

Tip

Crossplane recommends using a Patch to create a unique name for each secret.

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

 1apiVersion: apiextensions.crossplane.io/v1
 2kind: Composition
 3spec:
 4  # Removed for brevity
 5  resources:
 6    - name: key
 7      base:
 8        apiVersion: iam.aws.upbound.io/v1beta1
 9        kind: AccessKey
10        spec:
11        # Removed for brevity
12          writeConnectionSecretToRef:
13            namespace: docs
14            name: key1
15      patches:
16        - fromFieldPath: "metadata.uid"
17          toFieldPath: "spec.writeConnectionSecretToRef.name"
18          transforms:
19            - type: string
20              string:
21                fmt: "%s-secret"

Define secret keys

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

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.

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.

 1kind: Composition
 2spec:
 3  writeConnectionSecretsToNamespace: other-namespace
 4  resources:
 5    - name: key
 6      base:
 7        # Removed for brevity
 8        spec:
 9          forProvider:
10          # Removed for brevity
11          writeConnectionSecretToRef:
12            namespace: docs
13            name: key1
14      connectionDetails:
15        - name: myUsername
16          fromConnectionSecretKey: username
17        - name: myFieldSecret
18          fromFieldPath: spec.forProvider.user
19        - name: myStaticSecret
20          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.

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.

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.

 1kubectl describe secret
 2Name:         my-access-key-secret
 3Namespace:    default
 4Labels:       <none>
 5Annotations:  <none>
 6
 7Type:  connection.crossplane.io/v1alpha1
 8
 9Data
10====
11myUsername:      20 bytes
12myFieldSecret:   24 bytes
13myStaticSecret:  18 bytes

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 for more information on restricting secret keys.

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

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 write secrets and connection details to external secret stores like HashiCorp Vault.

Important

External Secret Stores are an alpha feature.

They’re not recommended for production use. Crossplane disables External Secret Stores by default.

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.”

 1apiVersion: gcp.crossplane.io/v1alpha1
 2kind: StoreConfig
 3metadata:
 4  name: vault
 5# Removed for brevity.
 6---
 7apiVersion: apiextensions.crossplane.io/v1
 8kind: Composition
 9# Removed for Brevity
10spec:
11  publishConnectionDetailsWithStoreConfigRef: 
12    name: vault
13  resources:
14  # Removed for brevity

For more details read the External Secret Stores 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.

Tip

Use multiple readiness checks if a resource must meet multiple conditions for it to be Ready.

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.

 1apiVersion: apiextensions.crossplane.io/v1
 2kind: Composition
 3# Removed for Brevity
 4spec:
 5  resources:
 6  # Removed for Brevity
 7    - name: my-resource
 8      base:
 9        # Removed for brevity
10      readinessChecks:
11        - type: <match type>
12          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.

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.

 1apiVersion: apiextensions.crossplane.io/v1
 2kind: Composition
 3# Removed for Brevity
 4spec:
 5  resources:
 6  # Removed for Brevity
 7    - name: my-resource
 8      base:
 9        # Removed for brevity
10      readinessChecks:
11        - type: MatchString
12          fieldPath: status.atProvider.state
13          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.

Note

Crossplane doesn’t support matching 0.

For example, matching the number 4 in the resource’s status.atProvider.state field.

 1apiVersion: apiextensions.crossplane.io/v1
 2kind: Composition
 3# Removed for Brevity
 4spec:
 5  resources:
 6  # Removed for Brevity
 7    - name: my-resource
 8      base:
 9        # Removed for brevity
10      readinessChecks:
11        - type: MatchInteger
12          fieldPath: status.atProvider.state
13          matchInteger: 4

Match that a field exists

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

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.

 1apiVersion: apiextensions.crossplane.io/v1
 2kind: Composition
 3# Removed for Brevity
 4spec:
 5  resources:
 6  # Removed for Brevity
 7    - name: my-resource
 8      base:
 9        # Removed for brevity
10      readinessChecks:
11        - type: NonEmpty
12          fieldPath: status.atProvider.state

Tip

Checking NonEmpty doesn’t require setting any other fields.

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.

 1apiVersion: apiextensions.crossplane.io/v1
 2kind: Composition
 3# Removed for Brevity
 4spec:
 5  resources:
 6  # Removed for Brevity
 7    - name: my-resource
 8      base:
 9        # Removed for brevity
10      readinessChecks:
11        - 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.

 1apiVersion: apiextensions.crossplane.io/v1
 2kind: Composition
 3# Removed for Brevity
 4spec:
 5  resources:
 6  # Removed for Brevity
 7    - name: my-resource
 8      base:
 9        # Removed for brevity
10      readinessChecks:
11        - type: MatchCondition
12          matchCondition:
13            type: MyType
14            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.

 1apiVersion: apiextensions.crossplane.io/v1
 2kind: Composition
 3# Removed for Brevity
 4spec:
 5  resources:
 6  # Removed for Brevity
 7    - name: my-resource
 8      base:
 9        # Removed for brevity
10      readinessChecks:
11        - type: MatchTrue
12          fieldPath: status.atProvider.manifest.status.ready

Tip

Checking MatchTrue doesn’t require setting any other fields.

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.

 1apiVersion: apiextensions.crossplane.io/v1
 2kind: Composition
 3# Removed for Brevity
 4spec:
 5  resources:
 6  # Removed for Brevity
 7    - name: my-resource
 8      base:
 9        # Removed for brevity
10      readinessChecks:
11        - type: MatchFalse
12          fieldPath: status.atProvider.manifest.status.pending

Tip

Checking MatchFalse doesn’t require setting any other fields.

Verify a Composition

View all available Compositions with kubectl get composition.

1kubectl get composition
2NAME                                       XR-KIND        XR-APIVERSION                         AGE
3xapps.aws.platformref.upbound.io           XApp           aws.platformref.upbound.io/v1alpha1   123m
4xclusters.aws.platformref.upbound.io       XCluster       aws.platformref.upbound.io/v1alpha1   123m
5xeks.aws.platformref.upbound.io            XEKS           aws.platformref.upbound.io/v1alpha1   123m
6xnetworks.aws.platformref.upbound.io       XNetwork       aws.platformref.upbound.io/v1alpha1   123m
7xservices.aws.platformref.upbound.io       XServices      aws.platformref.upbound.io/v1alpha1   123m
8xsqlinstances.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.

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.

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.

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 page has more information on enabling Crossplane flags.

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.

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.

The following modes are available:

Mode	Missing Schema	Schema Aware Error	Integrity Error
`warn`	Warning	Warning	Error
`loose`	Warning	Error	Error
`strict`	Error	Error	Error

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.

1apiVersion: apiextensions.crossplane.io/v1
2kind: Composition
3metadata:
4  annotations:
5    crossplane.io/composition-schema-aware-validation-mode: loose
6  # Removed for brevity
7spec:
8  # Removed for brevity

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.

Compositions

Confused about Compositions, XRDs, XRs and Claims?

Creating Compositions

Resource templates

Template a managed resource

Template a ProviderConfig

Template another Composite Resource

Cross-resource references

Match resource labels

Match a controller reference

Enabling Composite Resources

Changing resource fields

Patch sets

Patch with EnvironmentConfigs

Patch a composite resource

Patch an individual resource

Use composition functions

Storing connection details

Composite resource combined secret

Composed resource secrets

Define secret keys

Save connection details to an external secret store

Resource readiness checks

Match a string

Match an integer

Match that a field exists

Always consider a resource ready

Match a condition

Match a boolean

Verify a Composition

Composition validation

Composition schema aware validation

Schema aware validation modes