Guides on Crossplane

Disaster Recovery with Crossplane

AWS wrote a guide covering disaster recovery with Crossplane. The guide covers using Crossplane to provision resources and Velero for Kubernetes backup and recovery.

Read the guide on AWS.

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 claim or 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

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.

Crossplane can import resources either manually or automatically.

Import resources manually

Crossplane can discover and import existing Provider resources by matching the crossplane.io/external-name annotation in a managed resource.

To import an existing external resource in a Provider, create a new managed resource with the crossplane.io/external-name annotation. Set the annotation value to the name of the resource in the Provider.

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 is designed to help users of Crossplane Providers to understand what changes a provider is making to the resources it’s managing. Whenever a provider creates, updates, or deletes a managed resource, an entry explaining the details of the change is recorded in the provider’s 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 will enforce its source of truth to eventually correct this unexpected change without any user interaction.

Vault as an External Secret Store

This guide walks through the steps required to configure Crossplane and its Providers to use Vault as an External Secret Store (ESS) with ESS Plugin Vault.

Warning

External Secret Stores are an alpha feature.

They’re not recommended for production use. Crossplane disables External Secret Stores by default.

Crossplane uses sensitive information including Provider credentials, inputs to managed resources and connection details.

The Vault credential injection guide details using Vault and Crossplane for Provider credentials.

Vault Credential Injection

This guide is adapted from the Vault on Minikube and Vault Kubernetes Sidecar guides.

Most Crossplane providers support supplying credentials from at least the following sources:

Kubernetes Secret
Environment Variable
Filesystem

A provider may optionally support additional credentials sources, but the common sources cover a wide variety of use cases. One specific use case that’s popular among organizations that use Vault for secrets management is using a sidecar to inject credentials into the filesystem. This guide will demonstrate how to use the Vault Kubernetes Sidecar to provide credentials for provider-gcp and provider-aws.

Multi-Tenant Crossplane

This guide describes how to use Crossplane effectively in multi-tenant environments by utilizing Kubernetes primitives and compatible policy enforcement projects in the cloud native ecosystem.

Summary

Infrastructure operators in multi-tenant Crossplane environments typically utilize composition and Kubernetes RBAC to define lightweight, standardized policies that dictate what level of self-service developers are given when requesting infrastructure. This is primarily achieved through exposing abstract resource types at the namespace scope, defining Roles for teams and individuals within that namespace, and patching the spec.providerConfigRef of the underlying managed resources so that they use a specific ProviderConfig and credentials when provisioned from each namespace. Larger organizations, or those with more complex environments, may choose to incorporate third-party policy engines, or scale to multiple Crossplane clusters. The following sections describe each of these scenarios in greater detail.

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.