Crossplane Fundamentals

Crossplane is a framework for building control planes on Kubernetes. A control plane exposes an API, accepts a desired state, and keeps the systems behind that API aligned with the request. Crossplane supplies reusable controllers and a composition engine, so you can design platform APIs without writing every controller yourself.

The useful mental model is an API factory plus continuous reconciliation. A platform team defines an API such as App or Database. A developer creates one object through the Kubernetes API. Crossplane turns that request into Kubernetes resources, external services, or both. It then watches those resources and corrects drift.

Why Crossplane exists

Kubernetes gives you an API, custom resources, and controllers. Building a production controller for every internal platform service still takes substantial engineering. Crossplane moves much of that work into configuration and reusable function pipelines.

This separation gives two groups a clean contract:

• A platform team defines supported APIs, policies, and implementation details.
• An API user requests an outcome without choosing every underlying resource.

For example, a platform team can expose one App API. A Composition can turn each App into a Deployment, a Service, and a managed database. The user works with one object while the platform owns the resource graph.

The four parts of the system

Crossplane v2 presents four major components. You can adopt them together or use only the parts you need.

Composition builds custom APIs. A CompositeResourceDefinition, or XRD, defines the schema and scope of a custom API. An instance of that API is a composite resource, or XR. A Composition selects the resources that an XR should create. A pipeline of Functions calculates the desired composed resources.

Managed resources represent external services as Kubernetes objects. A Provider installs managed resource APIs and runs the controller that talks to an external API. The Kubernetes object holds the desired configuration. The external object might be a cloud database, storage bucket, or repository.

Operations run function pipelines once, on a schedule, or after a watched resource changes. Operations are an alpha feature in Crossplane v2. Treat them as optional and expect their API to change.

The package manager installs Providers and Functions. It also installs Configuration packages, which can bundle Crossplane APIs and their dependencies for reuse across control planes.

From request to resource

Follow one request through the system:

1. The platform team applies an XRD. Crossplane creates the custom API described by that XRD.
2. The platform team applies a Composition whose type reference matches that API.
3. A user creates an XR through the Kubernetes API.
4. Crossplane runs the Composition's Function pipeline.
5. The pipeline returns the desired composed resources.
6. Crossplane creates or updates those resources and keeps reconciling them.
7. Providers reconcile any managed resources with their external systems.

In Crossplane v2, XRs are namespaced by default. A namespaced XR can compose resources in its namespace. Managed resources are also namespaced in v2. Cluster-scoped and legacy v1-style resources remain relevant during migration, so check the API version and scope before reusing examples.

Direct managed resources or a platform API

You do not need Composition to use a managed resource. A team can create a managed resource directly when the provider API is an acceptable interface.

Composition earns its place when you need a stable platform contract. It can hide provider-specific fields, apply organization defaults, combine several resources, and let the implementation change without forcing every user to learn the underlying APIs.

That abstraction has a cost. Every custom API becomes a product your platform team must version, document, test, and support. Start with a real repeated need. Do not create a wrapper for every provider object just because Crossplane can.

Where Crossplane fits

Crossplane runs inside an existing Kubernetes cluster. It extends the Kubernetes API rather than replacing it. Existing Kubernetes tools can apply and observe Crossplane objects, while GitOps systems can deliver their manifests.

Crossplane is a strong fit when your organization already operates Kubernetes and wants declarative platform APIs across Kubernetes and external systems. It is less attractive when Kubernetes is absent, the target system has no suitable Provider, or a short-lived provisioning script is genuinely enough.

Crossplane also does not remove provider knowledge. Platform authors still need to understand credentials, lifecycle behavior, quotas, dependencies, deletion policies, and failure modes. Crossplane changes who handles that complexity and where it is encoded.

A safe learning sequence

First, understand Providers and managed resources. Next, define a small namespaced XR with an XRD. Then connect it to one Composition and render the output locally. Add credentials, policies, package distribution, and advanced Functions only after the resource lifecycle is clear.