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.

Tip
Claims are like composite resources. The difference between Claims and composite resources is Crossplane can create Claims in a namespace, while composite resources are cluster scoped.

Crossplane has four core components that users commonly mix up:

  • Compositions - A template to define how to create resources.
  • Composite Resource Definition (XRD) - A custom API specification.
  • 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 (XRC) - This page. Like a Composite Resource, but with namespace scoping.

Creating a Claim

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

Note
The XRD must enable Claims.

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

Diagram of the relationship of Crossplane components

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
Note

Crossplane supports directly creating composite resources. Claims allow namespace scoping and isolation for users consuming the custom APIs.

If you don’t use namespaces in your Kubernetes deployment Claims aren’t necessary.

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.

Note
All Claims have a resourceRef. Manually defining the resourceRef isn’t required. Crossplane fills in the resourceRef with the information from the composite resource created for the Claim.

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.

Note
The Crossplane creates the secret object in the same namespace as the Claim.

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.