---
title: Terminology
weight: 110
---
## A Note on Style

Each type of Kubernetes resource has a ‘Pascal case’ name - i.e. a title case
name with no spaces between each word. Examples include ‘DaemonSet’ and
‘PersistentVolumeClaim’. Often these names are written using fixed width fonts
to draw attention to the fact that they’re a concrete type of resource within
the API - e.g. `PersistentVolumeClaim`.

Crossplane follows this convention. We often use names like RDSInstance or
CompositeResourceDefinition when discussing Crossplane types. Crossplane also
has “classes of types” - i.e. concepts that aren’t a distinct type of API
resource, but rather describe a group of conceptually similar types. For example
there is no ManagedResource type in Crossplane - instead types like RDSInstance
and GKECluster are said to be “a managed resource”.

Use your discretion as to whether you use pascal case when writing about a
distinct type - e.g. “RDS Instance” and “RDSInstance” are both fine. The pascal
case form makes more sense in contexts like documentation where you’re referring
to Crossplane’s RDSInstance managed resource rather than the general concept of
“an RDS instance”. Avoid using Pascal case when talking about classes of types -
i.e. always write “managed resource”, not “ManagedResource”. Each of the below
terms clarify whether they correspond to a single type, or a class of types.

### Why 'X'?

You may notice that Crossplane uses “X” as shorthand for “Crossplane” and/or
“Composite”. This is because some of our concepts - specifically Composite
Resources (XRs) and Composite Resource Definitions (XRDs) are modelled on
similar Kubernetes concepts - Custom Resources (CRs) and Custom Resource
Definitions (CRDs). We chose to abbreviate to (e.g.) XRD instead of CRD to avoid
confusion.

## Crossplane Terms

The below terms are commonly used in the Crossplane ecosystem.

### Composition

The term Composition has two related but distinct meanings.

“Composition” refers broadly to the feature of Crossplane that allows teams to
define their own opinionated platform APIs.

“A Composition” or `Composition` (fixed width) refers to the key Crossplane API
type that configures how Crossplane should compose resources into a higher level
“composite resource”. A Composition tells Crossplane “when someone creates
composite resource X, you should respond by creating resources Y and Z”.

The latter use of Composition represents a distinct Crossplane API type so
Pascal case and fixed width fonts are appropriate. We also tend to capitalise
the former use, representing the feature in general, but fixed width fonts are
not appropriate in that context.

> Folks accustomed to Terraform might think of a Composition as a Terraform
> module; the HCL code that describes how to take input variables and use them
> to create resources in some cloud API. Folks accustomed to Helm might think of
> a Composition as a Helm chart’s templates; the moustache templated YAML files
> that describe how to take Helm chart values and render Kubernetes resources.

### Composite Resource

A “Composite Resource” or “XR” is an API type defined using Crossplane. A
composite resource’s API type is arbitrary - dictated by the concept the author
wishes to expose as an API, for example an “AcmeCoDB”. A common convention is
for types to start with "X" - e.g. "XAcmeCoDB".

We talk about Crossplane being a tool teams can use to define their own
opinionated platform APIs. Those APIs are made up of composite resources; when
you are interacting with an API that your platform team has defined, you’re
interacting with composite resources.

A composite resource can be thought of as the interface to a Composition. It
provides the inputs a Composition uses to compose resources into a higher level
concept. In fact, the composite resource _is_ the high level concept.

The term “Composite Resource” refers to a class of types, so avoid using Pascal
case - “Composite Resource” not CompositeResource. Use pascal case when
referring to a distinct type of composite resource - e.g. a XAcmeCoDB.

> Folks accustomed to Terraform might think of a composite resource as a
> `tfvars` file that supplies values for the variables a Terraform module uses
> to create resources in some cloud API. Folks accustomed to Helm might think of
> a composite resource as the `values.yaml` file that supplies inputs to a Helm
> chart’s templates.

### Composite Resource Claim

A “Composite Resource Claim”, “XRC”, or just “a claim” is also an API type
defined using Crossplane. Each type of claim corresponds to a type of composite
resource, and the pair have nearly identical schemas. Like composite resources,
the type of a claim is arbitrary.

We talk about Crossplane being a tool platform teams can use to offer
opinionated platform APIs to the application teams they support. The platform
team offers those APIs using claims. It helps to think of the claim as an
application team’s interface to a composite resource. You could also think of
claims as the public (app team) facing part of the opinionated platform API,
while composite resources are the private (platform team) facing part.

A common convention is for a claim to be of the same type as its corresponding
composite resource, but without the "X" prefix. So an "AcmeCoDB" would be a type
of claim, and a "XAcmeCoDB" would be the corresponding type of composite
resource. This allows claim consumers to be relatively ignorant of Crossplane
and composition, and to instead simply think about managing “an AcmeCo DB” while
the platform team worries about the implementation details.

The term “Composite Resource Claim” refers to a class of types, so avoid using
Pascal case - “Composite Resource Claim” not CompositeResourceClaim. Use Pascal
case when referring to a distinct type of composite resource claim - e.g. an
AcmeCoDB.

> Claims map to the same concepts as described above under the composite
> resource heading; i.e. `tfvars` files and Helm `values.yaml` files. Imagine
> that some `tfvars` files and some `values.yaml` files were only accessible to
> the platform team while others were offered to application teams; that’s the
> difference between a composite resource and a claim.

### Composite Resource Definition

A “Composite Resource Definition” or “XRD” is the API type used to define new
types of composite resources and claims. Types of composite resources and types
of claims exist because they were defined into existence by an XRD. The XRD
configures Crossplane with support for the composite resources and claims that
make up a platform API.

XRDs are often conflated with composite resources (XRs) - try to avoid this.
When someone uses the platform API to create infrastructure they’re not creating
XRDs but rather creating composite resources (XRs). It may help to think of a
composite resource as a database entry, while an XRD is a database schema. For
those familiar with Kubernetes, the relationship is very similar to that between
a Custom Resource Definition (CRD) and a Custom Resource (CR).

A `CompositeResourceDefinition` is a distinct Crossplane API type, so Pascal
case and fixed width fonts are appropriate.

> There isn’t a direct analog to XRDs in the Helm ecosystem, but they’re a
> little bit like the variable blocks in a Terraform module that define which
> variables exist, whether those variables are strings or integers, whether
> they’re required or optional, etc.

### Managed Resource

Managed resources are granular, high fidelity Crossplane representations of a
resource in an external system - i.e. resources that are managed by Crossplane.
Managed resources are what Crossplane enables platform teams to compose into
higher level composite resources, forming an opinionated platform API. They're
the building blocks of Crossplane.

You’ll often hear three related terms used in the Crossplane ecosystem; composed
resource, managed resource, and external resource. While there are some subtle
contextual differences, these all broadly refer to the same thing. Take an
RDSInstance for example; it is a managed resource. A distinct resource within
the Crossplane API that represents an AWS RDS instance. When we make a
distinction between the managed resource and an external resource we’re simply
making the distinction between Crossplane’s representation of the thing (the
`RDSInstance` in the Kubernetes API), and the actual thing in whatever external
system Crossplane is orchestrating (the RDS instance in AWS's API). When we
mention composed resources, we mean a managed resource of which a composite
resource is composed.

Managed resources are a class of resource, so avoid using Pascal case - “managed
resource” not “ManagedResource”.

> Managed resources are similar to Terraform resource blocks, or a distinct
> Kubernetes resource within a Helm chart.

### Package

Packages extend Crossplane, either with support for new kinds of composite
resources and claims, or support for new kinds of managed resources. There are
two types of Crossplane package; configurations and providers.

A package is not a distinct type in the Crossplane API, but rather a class of
types. Therefore Pascal case is not appropriate.

### Configuration

A configuration extends Crossplane by installing conceptually related groups of
XRDs and Compositions, as well as dependencies like providers or further
configurations. Put otherwise, it configures the opinionated platform API
that Crossplane exposes.

A `Configuration` is a distinct type in the Crossplane API, therefore Pascal
case and fixed width fonts are appropriate.

### Provider

A provider extends Crossplane by installing controllers for new kinds of managed
resources. Providers typically group conceptually related managed resources; for
example the AWS provider installs support for AWS managed resources like
RDSInstance and S3Bucket.

A `Provider` is a distinct type in the Crossplane API, therefore Pascal case and
fixed width fonts are appropriate. Note that each Provider package has its own
configuration type, called a `ProviderConfig`. Don’t confuse the two; the former
installs the provider while the latter specifies configuration that is relevant
to all of its managed resources.

> Providers are directly analogous to Terraform providers.

### Crossplane Resource Model

The Crossplane Resource Model or XRM is neither a distinct Crossplane API type,
or a class of types. Rather it represents the fact that Crossplane has a
consistent, opinionated API. The strict definition of the XRM is currently
somewhat vague, but it could broadly be interpreted as a catchall term referring
to all of the concepts mentioned on this page.
