Crossplane Introduction
Crossplane connects your Kubernetes cluster to external, non-Kubernetes resources, and allows platform teams to build custom Kubernetes APIs to consume those resources.
Crossplane creates Kubernetes
Custom Resource Definitions
(CRDs) to represent the external resources as native
Kubernetes objects.
As native Kubernetes objects, you can use standard commands like kubectl create
and kubectl describe. The full
Kubernetes API is available
for every Crossplane resource.
Crossplane also acts as a Kubernetes Controller to watch the state of the external resources and provide state enforcement. If something modifies or deletes a resource outside of Kubernetes, Crossplane reverses the change or recreates the deleted resource.
Crossplane also allows the creation of custom Kubernetes APIs. Platform teams can combine external resources and simplify or customize the APIs presented to the platform consumers.
Crossplane components overview
This table provides a summary of Crossplane components and their roles.
| Component | Abbreviation | Scope | Summary |
|---|---|---|---|
| Provider | cluster | Creates new Kubernetes Custom Resource Definitions for an external service. | |
| ProviderConfig | PC | cluster | Applies settings for a Provider. |
| Managed Resource | MR | cluster | A Provider resource created and managed by Crossplane inside the Kubernetes cluster. |
| Composition | cluster | A template for creating multiple managed resources at once. | |
| Composite Resources | XR | cluster | Uses a Composition template to create multiple managed resources as a single Kubernetes object. |
| CompositeResourceDefinitions | XRD | cluster | Defines the API schema for Composite Resources and Claims |
| Claims | XC | namespace | Like a Composite Resource, but namespace scoped. |
The Crossplane Pod
When installed in a Kubernetes cluster Crossplane creates an initial set of
Custom Resource Definitions (CRDs) of the core Crossplane components.
After installing Crossplane use kubectl get crds to view the Crossplane
installed CRDs.
1❯ kubectl get crd
2NAME
3compositeresourcedefinitions.apiextensions.crossplane.io
4compositionrevisions.apiextensions.crossplane.io
5compositions.apiextensions.crossplane.io
6configurationrevisions.pkg.crossplane.io
7configurations.pkg.crossplane.io
8controllerconfigs.pkg.crossplane.io
9deploymentruntimeconfigs.pkg.crossplane.io
10environmentconfigs.apiextensions.crossplane.io
11functionrevisions.pkg.crossplane.io
12functions.pkg.crossplane.io
13locks.pkg.crossplane.io
14providerrevisions.pkg.crossplane.io
15providers.pkg.crossplane.io
16storeconfigs.secrets.crossplane.io
17usages.apiextensions.crossplane.io
The following sections describe the functions of some of these CRDs.
Providers
A Crossplane Provider creates a second set of CRDs that define how Crossplane connects to a non-Kubernetes service. Each external service relies on its own Provider. For example, AWS, Azure and GCP are different providers for each cloud service.
For example, an AWS Provider defines Kubernetes CRDs for AWS resources like EC2 compute instances or S3 storage buckets.
The Provider defines the Kubernetes API definition for the external resource.
For example,
provider-upjet-aws
defines a
bucket
resource for creating and managing AWS S3 storage buckets.
In the bucket CRD is a
spec.forProvider.region
value that defines which AWS region to deploy the bucket in.
Crossplane’s public package registries contain a large collection of Crossplane Providers.
More providers are available in the Crossplane Contrib repository.
Providers are cluster scoped and available to all cluster namespaces.
View all installed Providers with the command kubectl get providers.
Provider configurations
Providers have ProviderConfigs. ProviderConfigs configure settings related to the Provider like authentication or global defaults for the Provider.
The API endpoints for ProviderConfigs are unique to each Provider.
ProviderConfigs are cluster scoped and available to all cluster namespaces.
View all installed ProviderConfigs with the command kubectl get providerconfig.
Managed resources
A Provider’s CRDs map to individual resources inside the provider. When Crossplane creates and monitors a resource it’s a Managed Resource.
Using a Provider’s CRD creates a unique Managed Resource. For example,
using the Provider AWS’s bucket CRD, Crossplane creates a bucket Managed Resource
inside the Kubernetes cluster that’s connected to an AWS S3 storage bucket.
The Crossplane controller provides state enforcement for Managed Resources. Crossplane enforces the settings and existence of Managed Resources. This “Controller Pattern” is like how the Kubernetes kube-controller-manager enforces state for pods.
Managed Resources are cluster scoped and available to all cluster namespaces.
Use kubectl get managed to view all managed resources.
The kubectl get managed creates a lot of Kubernetes API queries.
Both the kubectl client and kube-apiserver throttle the API queries.
Depending on the size of the API server and number of managed resources, this command may take minutes to return or may timeout.
For more information, read Kubernetes issue #111880 and Crossplane issue #3459.
Compositions
A Composition is a template for a collection of managed resource. Compositions allow platform teams to define a set of managed resources as a single object.
For example, a compute managed resource may require the creation of a storage resource and a virtual network as well. A single Composition can define all three resources in a single Composition object.
Using Compositions simplifies the deployment of infrastructure made up of multiple managed resources. Compositions also enforce standards and settings across deployments.
Platform teams can define fixed or default settings for each managed resource inside a Composition or define fields and settings that users may change.
Using the previous example, the platform team may set a compute resource size and virtual network settings. But the platform team allows users to define the storage resource size.
Creating a Composition Crossplane doesn’t create any managed resources. The Composition is only a template for a collection of managed resources and their settings. A Composite Resource creates the specific resources.
Compositions are cluster scoped and available to all cluster namespaces.
Use kubectl get compositions to view all compositions.
Composite Resources
A Composite Resource (XR) is a set of provisioned managed resources. A
Composite Resource uses the template defined by a Composition and applies
any user defined settings.
Multiple unique Composite Resource objects can use the same Composition. For example, a Composition template can create a compute, storage and networking set of managed resources. Crossplane uses the same Composition template every time a user requests this set of resources.
If a Composition allows a user to define resource settings, users apply them in a Composite Resource.
Compositions are templates for a set of managed resources.
Composite Resources fill out the template and create managed resources.
Deleting a Composite Resource deletes all the managed resources it created.
Composite Resources are cluster scoped and available to all cluster namespaces.
Use kubectl get composite to view all Composite Resources.
Composite Resource Definitions
Composite Resource Definitions (XRDs) create custom Kubernetes APIs used by
Claims and Composite Resources.
Platform teams define the custom APIs.
These APIs can define specific values
like storage space in gigabytes, generic settings like small or large,
deployment options like cloud or onprem. Crossplane doesn’t limit the API definitions.
The Composite Resource Definition’s kind is from Crossplane.
The spec of a Composite Resource Definition creates the apiVersion,
kind and spec of a Composite Resource.
A Composite Resource Definition has four main spec parameters:
- A
group apiVersion - The
versions.name - A
names.kind kind - A
versions.schema spec
1# Composite Resource Definition (XRD)
2spec:
3 group: test.example.org
4 names:
5 kind: MyComputeResource
6 versions:
7 - name: v1alpha1
8 schema:
9 # Removed for brevity
A Composite Resource based on this Composite Resource Definition looks like this:
1# Composite Resource (XR)
2apiVersion: test.example.org/v1alpha1
3kind: MyComputeResource
4metadata:
5 name: my-resource
6spec:
7 storage: "large"
A Composite Resource Definition
These parameters are the new, custom APIs, that developers can use.
For example, creating a compute managed resource requires knowledge of a
cloud provider’s compute class names like AWS’s m6in.large or GCP’s
e2-standard-2.
A Composite Resource Definition can limit the choices to small or large.
A Composite Resource uses those options and the Composition maps them
to specific cloud provider settings.
The following Composite Resource Definition defines a
1# Composite Resource Definition (XRD)
2spec:
3 group: test.example.org
4 names:
5 kind: MyComputeResource
6 versions:
7 - name: v1alpha1
8 served: true
9 referenceable: true
10 schema:
11 openAPIV3Schema:
12 type: object
13 properties:
14 spec:
15 type: object
16 properties:
17 storage:
18 type: string
19 oneOf:
20 - pattern: '^small$'
21 - pattern: '^large$'
22 required:
23 - storage
A Composite Resource Definition can define a wide variety of settings and options.
Creating a Composite Resource Definition enables the creation of Composite Resources but can also create a Claim.
Composite Resource Definitions with a spec.claimNames allow developers to
create Claims.
For example, the
kind: computeClaim.
1# Composite Resource Definition (XRD)
2spec:
3 group: test.example.org
4 names:
5 kind: MyComputeResource
6 claimNames:
7 kind: computeClaim
8 # Removed for brevity
Claims
Claims are the primary way developers interact with Crossplane.
Claims access the custom APIs defined by the platform team in a Composite Resource Definition.
Claims look like Composite Resources, but they’re namespace scoped, while Composite Resources are cluster scoped.
Why does namespace scope matter?
Having namespace scoped Claims allows multiple teams, using unique namespaces,
to create the same types of resources, independent of each other. The compute
resources of team A are unique to the compute resources of team B.
Directly creating Composite Resources requires cluster-wide permissions,
shared with all teams.
Claims create the same set of resources, but on a namespace level.
The previous Composite Resource Definition allows the creation of Claims
of the kind
Claims use the same
1# Composite Resource Definition (XRD)
2spec:
3 group: test.example.org
4 names:
5 kind: MyComputeResource
6 claimNames:
7 kind: computeClaim
8 # Removed for brevity
In an example Claim the
The Claim
1# Claim
2apiVersion: test.example.org/v1alpha1
3kind: computeClaim
4metadata:
5 name: myClaim
6 namespace: devGroup
7spec:
8 size: "large"
A Claim can install in a
The Composite Resource Definition defines the
Only Claims can be in a
namespace Also the Composite Resource’s
kind kind The Composite Resource Definition defines the
kind 1# Composite Resource (XR)
2apiVersion: test.example.org/v1alpha1
3kind: MyComputeResource
4metadata:
5 name: my-resource
6spec:
7 storage: "large"
Claims are namespace scoped.
View all available Claims with the command kubectl get claim.
Next steps
Build your own Crossplane platform using one of the quickstart guides.