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.

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

Connection Details Composition

This guide shows how to expose connection details for composite resources (XRs). Because composite resources can compose multiple resources, the connection details they expose are often an aggregate of the connection details from their composed resources.

The recommended approach is to include a Kubernetes Secret resource in your Composition that aggregates the connection details from other resources and exposes them for the XR.

Disabling Unused Managed Resources

Important

This guide uses managed resource definitions and managed resource activation policies, which Crossplane v2.0+ enables by default. To disable this behavior, set --enable-custom-to-managed-resource-conversion=false when installing Crossplane.

Large Crossplane providers can install 100+ managed resource CRDs, consuming significant cluster resources even when you only need one or two resource types. This guide shows how to use ManagedResourceDefinitions and ManagedResourceActivationPolicies to install only the provider resources you actually need.

Implementing safe-start in Providers

This guide shows provider developers how to implement safe-start capability in their Crossplane providers. safe-start enables disabling unused managed resources through ManagedResourceDefinitions, improving performance and reducing resource overhead.

Important

safe-start requires Crossplane v2.0+ and crossplane-runtime v2.0+. Implementing safe-start involves code changes that affect provider startup behavior.

What safe-start provides

safe-start changes how your provider handles CRD installation:

Import Existing Resources

If you have resources that are already provisioned in a Provider, you can import them as managed resources and let Crossplane manage them. A managed resource’s managementPolicies field enables importing external resources into Crossplane.

Import resources in observe only mode

Start by importing external resources with an Observe management policy.

Crossplane imports observe only resources but never changes or deletes the resources.

Crossplane with Workload Identity

When running Crossplane on managed Kubernetes clusters (EKS, AKS, GKE), you can use Kubernetes Workload Identity to grant Crossplane access to pull packages from private cloud container registries. This allows Crossplane to install providers, functions, and configurations from registries like AWS ECR, Azure ACR, and Google Artifact Registry without managing static credentials.

Important

This guide configures the Crossplane package manager to pull packages from private registries. Packages reference container images that run as separate pods (providers and functions).

Change Logs

The change logs feature helps users of Crossplane Providers understand what changes a provider makes to the resources it manages. Whenever a provider creates, updates, or deletes a managed resource, the provider records an entry explaining the details of the change in its change log.

Change logs are important for awareness of the changes that a provider is making to its managed resources. Due to the nature of Crossplane’s active reconciliation, it’s possible for a provider to make changes to managed resources without any user interaction. Consider the scenario when someone updates a resource outside of Crossplane, for example via the AWS console or gcloud CLI. When Crossplane detects this configuration drift, it enforces the declared state and corrects the unexpected change without any user interaction.

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

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:v2.0.0) and get the server could not find the requested resource error, more often than not, that’s an indicator that your Crossplane CLI needs updating. In other words Crossplane graduated some API 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.

Important

Always upgrade Crossplane one minor version at a time, using the most recent patch version available for each.

For example, if you are on v1.18 and want to upgrade to v2.0, you should first upgrade to v1.19, then v1.20, before finally upgrading to v2.0. The upgrade path in this example looks like v1.18 → v1.19 → v1.20 → v2.0.

Upgrade to Crossplane v2

Crossplane v2 introduces significant improvements while maintaining backward compatibility with most v1 configurations. This guide helps you upgrade from Crossplane v1.x to v2.

Learn about new features in Crossplane v2 including namespaced resources, the ability to compose any Kubernetes resource, and new operational workflows.

Important

Only upgrade to Crossplane v2 from Crossplane v1.20, the final v1.x release. If you’re running an earlier version, upgrade to v1.20 first.

Important

Always upgrade Crossplane one minor version at a time, using the most recent patch version available for each.

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.

Install Crossplane from source code

Building Crossplane from the source code gives you complete control over the build and installation process.

You build the Crossplane container image and Helm chart directly from the source code, push the image to your own registry, and install to your Kubernetes cluster.

Important

Installing Crossplane from source is an advanced installation path for users who require complete control over the build and deployment process. Most users should follow the standard installation instructions

This approach is useful when you want to: