Guides 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.

Metrics

Crossplane produces Prometheus style metrics for effective monitoring and alerting in your environment. These metrics are essential for helping to identify and resolve potential issues. This page offers explanations of all these metrics gathered from Crossplane. Understanding these metrics helps you maintain the health and performance of your resources. Please note that this document focuses on Crossplane specific metrics and doesn’t cover standard Go metrics.

To enable the export of metrics it’s necessary to configure the --set metrics.enabled=true option in the helm chart.

Function Patch and Transform

Function Patch and Transform allows you to write a Composition that specifies managed resource (MR) templates, and uses “patch and transform” operations to fill them out. Crossplane fills the templates out with values copied from a composite resource (XR).

A patch copies a value from one resource and patches it onto another resource. A transform modifies the values before applying the patch.

Tip

All Compositions used Patch and Transform before Crossplane added support for composition functions.

Releasing Crossplane Extensions

Distributing Crossplane extensions

Crossplane provides a packaging specification for extending a Crossplane instance with APIs and business logic for composing resources.

Building a Crossplane extension involves creating OCI images in the xpkg format. Authors and maintainers of Crossplane extensions must push their packages to an OCI registry before users can reference and use them.

The release process for Crossplane extensions grew organically in the community and developed its own conventions and common configurations. Authors of these extensions should follow this guide to enable automation for building and pushing their packages as part of their git workflow.

Write a Composition Function in Go

Composition functions (or just functions, for short) are custom programs that template Crossplane resources. Crossplane calls composition functions to determine what resources it should create when you create a composite resource (XR). Read the concepts page to learn more about composition functions.

You can write a function to template resources using a general purpose programming language. Using a general purpose programming language allows a function to use advanced logic to template resources, like loops and conditionals. This guide explains how to write a composition function in Go.

Write a Composition Function in Python

Configuring Crossplane with Argo CD

Argo CD and Crossplane are a great combination. Argo CD provides GitOps while Crossplane turns any Kubernetes cluster into a Universal Control Plane for all of your resources. Configuration details are required in order for the two to work together properly. This doc will help you understand these requirements. It is recommended to use Argo CD version 2.4.8 or later with Crossplane.

Argo CD synchronizes Kubernetes resource manifests stored in a Git repository with those running in a Kubernetes cluster (GitOps). Argo CD has different ways to configure how it tracks resources. With Crossplane, you need to configure Argo CD to use Annotation based resource tracking. See the Argo CD docs for additional detail.

Self-Signed CA Certs

Using self-signed certificates isn’t advised in production, it’s recommended to only use self-signed certificates for testing.

When Crossplane loads Configuration and Provider Packages from private registries, it must be configured to trust the CA and Intermediate certs.

Crossplane needs to be installed via the Helm chart with the registryCaBundleConfig.name and registryCaBundleConfig.key parameters defined. See Install Crossplane.

Configure

Create a CA Bundle (A file containing your Root and Intermediate certificates in a specific order). This can be done with any text editor or from the command line, so long as the resulting file contains all required crt files in the proper order. In many cases, this will be either a single self-signed Root CA crt file, or an Intermediate crt and Root crt file. The order of the crt files should be from lowest to highest in signing order. For example, if you have a chain of two certificates below your Root certificate, you place the bottom level Intermediate cert at the beginning of the file, then the Intermediate cert that singed that cert, then the Root cert that signed that cert.

Troubleshoot Crossplane

Requested Resource Not Found

If you use the Crossplane CLI to install a Provider or Configuration (for example, crossplane xpkg install provider xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v1.21.1) and get the server could not find the requested resource error, more often than not, that’s an indicator that the Crossplane CLI you’re using is outdated. In other words some Crossplane API has been graduated from alpha to beta or stable and the old plugin isn’t aware of this change.

Upgrade Crossplane

The recommended upgrade method for an existing Crossplane install is to use Helm.

Prerequisites

Helm version v3.2.0 or later

Add the Crossplane Preview Helm repository

Verify Helm has the Crossplane repository.

1helm repo add crossplane-preview https://charts.crossplane.io/preview

Update the Helm Preview repository

Update the local Crossplane Helm chart with helm repo update.

Uninstall Crossplane

Warning

Resources created by Crossplane aren’t deleted if Crossplane isn’t uninstalled in order.

This can leave cloud resources running, requiring manual deletion.

Ordered Crossplane uninstall

Most Crossplane resources have dependencies on other Crossplane resources.

For example, a managed resource is dependent on the provider.

Failure to delete Crossplane resources in order may prevent Crossplane from deleting provisioned external resources.