Crossplane vs. Cluster API: Draw the Boundary Before AI Draws It for You

An AI agent can open a pull request, call an API, and ask for a GPU-backed environment in seconds. That does not make the resulting infrastructure model simple. It makes the ownership boundary urgent.

Crossplane and Cluster API both present declarative Kubernetes APIs. Both use controllers, providers, desired state, and reconciliation. From a distance, that resemblance can invite a costly category error: treating them as two interchangeable ways to provision “infrastructure.” They are not. They operate at different layers of the platform.

The reader promise of this article is a concrete boundary map: which controller should own a cluster, a machine, a cloud service, and a tenant-facing application request. The short version appears before the terminology because it is the part an AI-era platform needs to make explicit.

This is not merely a naming exercise. A controller is a promise about who gets to continuously change a thing. If two layers each believe they own the same object, the result is not extra automation; it is competing reconciliation, unclear credentials, and incident response that begins with “which controller changed this?”

Same control-loop grammar, different nouns​

Cluster API (CAPI) is a Kubernetes subproject for provisioning, upgrading, and operating Kubernetes clusters. Its documentation defines a management cluster that stores CAPI resources and runs providers, and workload clusters whose lifecycle it manages. Its core Machine object expresses the intent for a host that will become a Kubernetes Node; a provider creates, replaces, or deletes the backing host to match that intent. The Cluster API introduction and its concepts guide describe that lifecycle boundary.

That scope includes more than a VM create call. A CAPI configuration connects a cluster object, a control-plane provider, bootstrap data, and infrastructure-provider objects. A worker MachineDeployment handles a fleet of MachineSets and can roll a machine template forward while respecting availability settings. When scaling down, CAPI drains the Node and waits for attached volumes before deleting the infrastructure where the relevant timeouts permit it. CAPI's scaling guide makes the order explicit.

Crossplane is a control-plane framework for platform engineering. Its managed resources represent external services in a provider: an EC2 instance, a GKE cluster, an Azure database, and many other provider-specific API objects. The spec.forProvider fields are the desired state; absent a different policy, the provider reconciles external console changes back to that state. Crossplane's managed-resources documentation describes that source-of-truth behavior.

Crossplane's additional move is composition. An XRD defines a custom API, and a Composition turns one composite resource into one or more managed or Kubernetes resources. A platform can therefore make TeamDatabase, InferenceEndpoint, or PreviewEnvironment a small, stable API even when its implementation spans a bucket, an identity binding, a database, and connection details. The Composition documentation uses the same pattern for a composite bucket API.

The difference is the noun each system treats as first-class. CAPI starts with a cluster and the machines that form it. Crossplane starts with a resource contract and the provider API or Kubernetes resources behind it. A CAPI provider may create networks, load balancers, and VMs because they are prerequisites for a Kubernetes cluster. A Crossplane provider may create a Kubernetes cluster because that is an external service. Those facts can overlap in implementation without erasing the difference in lifecycle authority.

Trace one AI application through the boundary​

Consider a team that needs a chat service, a background embedding worker, object storage for source documents, and a GPU-capable worker pool. This is a representative split because it contains all three layers: application operations, external services, and fleet operations.

1. The platform application API accepts a repository, build configuration, service settings, and an environment. It produces a release and a workload in a tenant namespace. That API owns the product concepts a developer actually asked for: deploy, rollback, custom domain, logs, and runtime configuration.
2. Kubernetes schedules the chat service and worker onto existing Nodes. If the GPU pool needs additional capacity, a cluster autoscaler can change a CAPI-managed MachineDeployment or MachinePool within declared limits. CAPI then turns the request for capacity into machines that become Nodes. CAPI documents the autoscaler annotations and capacity data it uses for this flow.
3. A Crossplane composition can represent the external pieces if the platform chooses to expose them declaratively: a bucket, a cloud database, a provider IAM role, or a hosted inference endpoint. The composition can publish only the safe knobs that the platform supports rather than every provider field.
4. The application receives a narrowly scoped connection detail or workload identity. It does not receive the management-cluster credentials that create nodes, nor a broadly privileged cloud key.

This sequence gives each reconciler a bounded question. CAPI asks, “Does the fleet have the clusters and machines declared by the platform operator?” Crossplane asks, “Do the provider resources described by this approved resource contract exist and match their declared state?” The application platform asks, “Does this tenant have a running release that matches its deployment request?”

AI changes the pressure on that model, not the model itself. CNCF's March 2026 article on Crossplane argues that agents need APIs rather than UI-driven handoffs, because the work after a git push includes provisioning, policy, drift, and coordination. That article is right to focus on an API surface. It does not follow that an agent should receive every raw CRD or cloud-provider credential. A useful API surface is small enough to authorize, audit, and reverse.

Where the two systems can meet—and where they should not race​

Crossplane v2 can compose any Kubernetes resource, including a Cluster API Cluster, in addition to its own managed resources. It also makes managed resources namespaced, which makes namespace-level access control possible for providers that support the v2 resource model. Crossplane's v2 documentation explicitly calls out both capabilities.

That makes a nested design technically possible: a Crossplane composite resource can create a CAPI cluster along with surrounding external resources. For example, a ResearchCluster API might result in a CAPI Cluster, a provider network, a storage bucket, and project-scoped identity. The nested shape is not a reason to give both projects independent authority over the same CAPI objects.

The ownership rule is straightforward:

The fourth row is the subtle one. An outer Crossplane resource can be the request interface, but the CAPI objects it creates still need one clear lifecycle story. Do not separately apply an unrelated CAPI manifest, a Crossplane composition, and an agent tool that all edit the same fields. Server-side apply can report field conflicts; it cannot decide which business policy should win.

The same caution applies in the other direction. CAPI already creates provider infrastructure related to a cluster, but that does not mean a platform should use CAPI as the tenant catalog for databases, queues, or arbitrary SaaS accounts. The resource types, identity model, and operational expectations differ. A machine replacement is a capacity event with node-drain semantics. A database plan change is an external-service contract with backup, data-migration, and connection-rotation consequences.

A custom API is an authorization boundary, not just nicer YAML​

The temptation in an agentic platform is to declare success once an LLM can emit valid YAML. That is the beginning of the interface-design problem, not the end. Crossplane compositions can hide provider-specific parameters, and CAPI templates can standardize machine choices, but neither automatically decides which actions a tenant agent may take.

Use the API shape to make the authorization question answerable. An agent request for a GPU pool can expose a class, minimum and maximum replicas, region, and an approved accelerator family. A platform controller can map that request to a CAPI template. An agent request for a document store can expose retention, region, and a bounded capacity class; a Crossplane Composition can translate that into provider resources. The agent tool should record the human or service principal, requested change, policy decision, generated resource IDs, and observed result.

Crossplane's own documentation highlights the privilege involved: its service account needs access to create and update the resources a Composition returns, and extra Kubernetes resource types require explicitly aggregated RBAC. Its composition RBAC guide is a useful reminder that a composition is executable authority, not a harmless template. CAPI's management credentials deserve the same treatment because they can create and replace the machines beneath tenant workloads.

For a platform such as Bex, the boundary also preserves an important product distinction. A Render-compatible application API can remain the deploy surface while Cluster API manages the owned fleet beneath it. Crossplane may be an implementation component for a deliberately supported external-resource API; it need not become a promise that the platform operates a managed database or every cloud service a tenant could name. The product API, its policy, and its support contract stay visible instead of leaking provider objects straight through to users.

Day-two operations reveal the real scope​

Provisioning demos make both tools look similar: create YAML, watch a controller make something. The distinction becomes clearer when the thing changes.

For CAPI, a Kubernetes version change or machine-template change can cause a rolling control-plane or worker rollout. CAPI documents that MachineDeployments manage MachineSets and Machines for scaling and rollout, with strategies such as RollingUpdate and OnDelete. The upgrade guide describes these mechanics. The operational question is cluster health: are replacement Nodes ready, are workloads drained safely, and is the control plane available?

For Crossplane, a provider resource's desired state is reconciled through the provider API. The operational question is resource contract health: did a provider accept the change, was an immutable field requested, did credentials expire, and did an out-of-band console edit get reconciled back? Crossplane notes that changing an immutable external-resource field does not itself cause deletion and recreation; its behavior is intentionally different from tools that replace an object on such a change. Its managed-resource lifecycle notes describe that boundary.

Neither operational model is “more declarative.” They are declarative about different systems, with different safe failure modes. A good runbook names the controller and the observable status for each object before an agent or a human makes the change.

Keep the stack legible as it grows​

AI workloads are likely to increase the number of resource requests: more preview environments, short-lived workers, GPU capacity, data stores, and identities. That growth makes a readable control-plane boundary more valuable, not less.

The durable pattern is to keep three questions separate: what service did the tenant ask for, what external dependency does that service need, and what cluster capacity runs it? An application platform answers the first; Crossplane can answer the second where an approved resource API is needed; Cluster API answers the third. Their APIs can be composed, but their ownership should remain visible in code, credentials, events, and incident runbooks.

That visibility is what lets an agent operate infrastructure without making infrastructure mysterious.

Sources​

• Crossplane: Managed Resources
• Crossplane: Compositions
• Crossplane v2: What's New
• Cluster API Book: Introduction
• Cluster API Book: Scaling Nodes
• CNCF: Crossplane and AI—The case for API-first infrastructure