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.

The Crossplane Pod

When installed in a Kubernetes cluster Crossplane creates an initial set of Custom Resource Definitions (CRDs) of the core Crossplane components.

 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, the Upbound Provider 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.

The Upbound Marketplace contains 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.

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.

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.

1apiVersion: apiextensions.crossplane.io/v1
2kind: CompositeResourceDefinition

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 to define the apiVersion in a Composite Resource .
• The versions.name that defines the version used in a Composite Resource.
• A names.kind to define the Composite Resource kind.
• A versions.schema section to define the Composite Resource 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: myResource
6spec:
7  storage: "large"

A Composite Resource Definition schema defines the Composite Resource spec parameters.

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 storage parameter. The storage is a string and the OpenAPI oneOf requires the options to be either small or large.

 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 claimNames.kind allows the creation of Claims of 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.

The previous Composite Resource Definition allows the creation of Claims of the kind
computeClaim.

Claims use the same apiVersion defined in Composite Resource Definition and also used by Composite Resources.

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 apiVersion matches the group in the Composite Resource Definition.

The Claim kind matches the Composite Resource Definition claimNames.kind.

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 namespace.
The Composite Resource Definition defines the spec options the same way it does for a Composite Resource spec.

1# Composite Resource (XR)
2apiVersion: test.example.org/v1alpha1
3kind: myComputeResource
4metadata:
5  name: myResource
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.

• Azure Quickstart
• AWS Quickstart
• GCP Quickstart