Claims

Claims represents a set of managed resources as a single Kubernetes object, inside a namespace.

Users create claims when they access the custom API, defined in the CompositeResourceDefinition.

Creating a Claim

Creating a Claim requires a Composition and a CompositeResourceDefinition (XRD) already installed.

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

For example, this CompositeResourceDefinition creates a composite resource API endpoint xmydatabases.example.org and enables a Claim API endpoint database.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  claimNames:
11    kind: Database
12    plural: databases
13  # Removed for brevity

The Claim uses the XRD’s kind API endpoint to request resources.

The Claim’s apiVersion matches the XRD group and the kind matches the XRD claimNames.kind

1apiVersion: example.org/v1alpha1
2kind: database
3metadata:
4  name: my-claimed-database
5spec:
6  # Removed for brevity

When a user creates a Claim in a namespace Crossplane also creates a composite resource.

Use kubectl describe on the Claim to view the related composite resource.

The Resource Ref is the composite resource Crossplane created for this Claim.

 1kubectl describe database.example.org/my-claimed-database
 2Name:         my-claimed-database
 3API Version:  example.org/v1alpha1
 4Kind:         database
 5Spec:
 6  Resource Ref:
 7    API Version:  example.org/v1alpha1
 8    Kind:         XMyDatabase
 9    Name:         my-claimed-database-rr4ll
10# Removed for brevity.

Use kubectl describe on the composite resource to view the Claim Ref linking the composite resource to the original Claim.

 1kubectl describe xmydatabase.example.org/my-claimed-database-rr4ll
 2Name:         my-claimed-database-rr4ll
 3API Version:  example.org/v1alpha1
 4Kind:         XMyDatabase
 5Spec:
 6  Claim Ref:
 7    API Version:  example.org/v1alpha1
 8    Kind:         database
 9    Name:         my-claimed-database
10    Namespace:    default

Claiming existing composite resources

By default, creating a Claim creates a new composite resource. Claims can also link to existing composite resources.

A use case for claiming existing composite resources may be slow to provision resources. Composite resources can be pre-provisioned and a Claim can use those resources without waiting for their creation.

Set the Claim’s resourceRef and match the pre-existing composite resource name.

1apiVersion: example.org/v1alpha1
2kind: database
3metadata:
4  name: my-claimed-database
5spec:
6  resourceRef:
7    apiVersion: example.org/v1alpha1
8    kind: XMyDatabase
9    name: my-pre-created-xr

If a Claim specifies a resourceRef that doesn’t exist, Crossplane doesn’t create a composite resource.

Claim connection secrets

If a Claim expects connection secrets the Claim must define a writeConnectionSecretToRef object.

The writeConnectionSecretToRef object defines the name of the Kubernetes secret object where Crossplane saves the connection details.

For example, to a new secret object named my-claim-secret use writeConnectionSecretToRef with the name: my-claim-secret.

1apiVersion: example.org/v1alpha1
2kind: database
3metadata:
4  name: my-claimed-database
5spec:
6  writeConnectionSecretToRef:
7    name: my-claim-secret

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