docs/content/v1.20/concepts/claims.md

title	weight	description
Claims	60	Claims are a way to consume Crossplane resources with namespace scoping

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.

{{< hint "tip" >}}

Claims are like [composite resources]({{<ref "./composite-resources">}}). The difference between Claims and composite resources is Crossplane can create Claims in a namespace, while composite resources are cluster scoped. {{< /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 Resources]({{<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 (XRC) - This page. Like a Composite Resource, but with namespace scoping. {{}}

Creating a Claim

Creating a Claim requires a [Composition]({{<ref "./compositions">}}) and a [CompositeResourceDefinition]({{<ref "./composite-resource-definitions">}}) (XRD) already installed.

{{<hint "note" >}} The XRD must [enable Claims]({{<ref "./composite-resource-definitions#enable-claims">}}). {{< /hint >}}

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{{}}

apiVersion: apiextensions.crossplane.io/v1
kind: CompositeResourceDefinition
metadata: 
  name: xmydatabases.example.org
spec:
  group: example.org
  names:
    kind: XMyDatabase
    plural: xmydatabases
  claimNames:
    kind: Database
    plural: databases
  # 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{{}}

apiVersion: example.org/v1alpha1
kind: database
metadata:
  name: my-claimed-database
spec:
  # 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.

kubectl describe database.example.org/my-claimed-database
Name:         my-claimed-database
API Version:  example.org/v1alpha1
Kind:         database
Spec:
  Resource Ref:
    API Version:  example.org/v1alpha1
    Kind:         XMyDatabase
    Name:         my-claimed-database-rr4ll
# Removed for brevity.

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

kubectl describe xmydatabase.example.org/my-claimed-database-rr4ll
Name:         my-claimed-database-rr4ll
API Version:  example.org/v1alpha1
Kind:         XMyDatabase
Spec:
  Claim Ref:
    API Version:  example.org/v1alpha1
    Kind:         database
    Name:         my-claimed-database
    Namespace:    default

{{<hint "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. {{< /hint >}}

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{{}}.

apiVersion: example.org/v1alpha1
kind: database
metadata:
  name: my-claimed-database
spec:
  resourceRef:
    apiVersion: example.org/v1alpha1
    kind: XMyDatabase
    name: my-pre-created-xr

If a Claim specifies a {{}}resourceRef{{}} that doesn't exist, Crossplane doesn't create a composite resource.

{{<hint "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. {{< /hint >}}

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.

{{<hint "note" >}} The Crossplane creates the secret object in the same namespace as the Claim. {{< /hint >}}

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

apiVersion: example.org/v1alpha1
kind: database
metadata:
  name: my-claimed-database
spec:
  writeConnectionSecretToRef:
    name: my-claim-secret

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