Terminology

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.