Concepts on Crossplane

Crossplane Pods

The base Crossplane installation consists of two pods, the crossplane pod and the crossplane-rbac-manager pod. Both pods install in the crossplane-system namespace by default.

Crossplane pod

Init container

Before starting the core Crossplane container an init container runs. The init container installs the core Crossplane Custom Resource Definitions (CRDs), configures Crossplane webhooks and installs any supplied Providers or Configurations.

Providers

Providers enable Crossplane to provision infrastructure on an external service. Providers create new Kubernetes APIs and map them to external APIs.

Providers are responsible for all aspects of connecting to non-Kubernetes resources. This includes authentication, making external API calls and providing Kubernetes Controller logic for any external resources.

Examples of providers include:

Providers define every external resource they can create in Kubernetes as a Kubernetes API endpoint. These endpoints are Managed Resources.

Managed Resources

A managed resource (MR) represents an external service in a Provider. When users create a new managed resource, the Provider reacts by creating an external resource inside the Provider’s environment. Every external service managed by Crossplane maps to a managed resource.

Note

Crossplane calls the object inside Kubernetes a managed resource and the external object inside the Provider an external resource.

Examples of managed resources include:

Compositions

Compositions are a template for creating multiple managed resources as a single object.

A Composition composes individual managed resources together into a larger, reusable, solution.

An example Composition may combine a virtual machine, storage resources and networking policies. A Composition template links all these individual resources together.

Here’s an example Composition. When you create an AcmeBucket composite resource (XR) that uses this Composition, Crossplane uses the template to create the Amazon S3 Bucket managed resource.

Composition Revisions

This guide discusses the use of “Composition Revisions” to safely make and roll back changes to a Crossplane Composition. It assumes familiarity with Crossplane, and particularly with Compositions.

A Composition configures how Crossplane should reconcile a Composite Resource (XR). Put otherwise, when you create an XR the selected Composition determines what managed resources Crossplane will create in response. Let’s say for example that you define a PlatformDB XR, which represents your organisation’s common database configuration of an Azure MySQL Server and a few firewall rules. The Composition contains the ‘base’ configuration for the MySQL server and the firewall rules that are extended by the configuration for the PlatformDB.

Composite Resource Definitions

Composite resource definitions (XRDs) define the schema for a custom API.
Users create composite resources (XRs) and Claims (XCs) using the API schema defined by an XRD.

Note

Read the composite resources page for more information about composite resources.

Read the Claims page for more information about Claims.

Crossplane has four core components that users commonly mix up:

Composite Resources

A composite resource represents a set of managed resources as a single Kubernetes object. Crossplane creates composite resources when users access a custom API, defined in the CompositeResourceDefinition.

Tip

Composite resources are a composite of managed resources.
A Composition defines how to compose the managed resources together.

Crossplane has four core components that users commonly mix up:

Claims

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.

Tip

Claims are like composite resources. The difference between Claims and composite resources is Crossplane can create Claims in a namespace, while composite resources are cluster scoped.

Crossplane has four core components that users commonly mix up:

Environment Configurations

A Crossplane EnvironmentConfig is a cluster-scoped, strongly typed, ConfigMap-like resource used by Compositions. Compositions can use the environment to store information from individual resources or to apply patches.

Crossplane supports multiple EnvironmentConfigs, each acting as a unique data store.

When Crossplane creates a composite resource, Crossplane merges all the EnvironmentConfigs referenced in the associated Composition and creates a unique in-memory environment for that composite resource.

The composite resource can read and write data to their unique in-memory environment.

Usages

A Usage is a Crossplane resource that defines a usage relationship for a Managed Resource or a Composite Resource. Two main use cases for the Usages are as follows:

Protecting a resource from accidental deletion.
Deletion ordering by ensuring that a resource isn’t deleted before the deletion of its dependent resources.

See the section Usage for Deletion Protection for the first use case and the section Usage for Deletion Ordering for the second one.

Connection Details

Using connection details in Crossplane requires the following components:

Defining the writeConnectionSecretToRef.name in a Claim.
Defining the writeConnectionSecretsToNamespace value in the Composition.
Define the writeConnectionSecretToRef name and namespace for each resource in the Composition.
Define the list of secret keys produced by each composed resource with in the Composition.
Optionally, define the connectionSecretKeys in a CompositeResourceDefinition.

Note

This guide discusses creating Kubernetes secrets. Crossplane also supports using external secret stores like HashiCorp Vault.

Configuration Packages

A Configuration package is an OCI container image containing a collection of Compositions, Composite Resource Definitions and any required Providers or Functions.

Configuration packages make your Crossplane configuration fully portable.

Important

Crossplane Providers and Functions are also Crossplane packages.

This document describes how to install and manage configuration packages.

Refer to the Provider and Composition Functions chapters for details on their usage of packages.

Install a Configuration

Install a Configuration with a Crossplane Configuration object by setting the spec.package value to the location of the configuration package.

Server-Side Apply

Crossplane can use server-side apply to sync claims with composite resources (XRs), and to sync composite resources with composed resources.

When Crossplane uses server-side apply, the Kubernetes API server helps sync resources. Using server-side apply makes syncing more predictable and less buggy.

Tip

Server-side apply is a Kubernetes feature. Read more about server-side apply in the Kubernetes documentation.

Use server-side apply to sync claims with composite resources

When you create a claim, Crossplane creates a corresponding composite resource. Crossplane keeps the claim in sync with the composite resource. When you change the claim, Crossplane reflects those changes on the composite resource.

Image Configs

ImageConfig is an API for centralized control over the configuration of Crossplane package images. It allows you to configure package manager behavior for images globally, without needing to be referenced by other objects.

Matching image references

spec.matchImages is a list of image references that the ImageConfig applies to. Each item in the list specifies the type and configuration of the image reference to match. The only supported type is Prefix, which matches the prefix of the image reference. No wildcards are supported. The type defaults to Prefix and can be omitted.

Concepts on Crossplane

Crossplane Pods

Crossplane pod

Init container

Providers

Managed Resources

Compositions

Composition Revisions

Composite Resource Definitions

Confused about Compositions, XRDs, XRs and Claims?

Composite Resources

Confused about Compositions, XRDs, XRs and Claims?

Claims

Confused about Compositions, XRDs, XRs and Claims?

Environment Configurations

Usages

Connection Details

Configuration Packages

Install a Configuration

Server-Side Apply

Use server-side apply to sync claims with composite resources

Image Configs

Matching image references