Crossplane extends Kubernetes so that cloud resources become Kubernetes objects. You install a provider (for AWS, say), and a bucket, a database or an IoT thing becomes a custom resource you can kubectl apply, keep in Git and watch with the same tools as a Deployment. Controllers then keep the real resource matching the object, the way Kubernetes keeps Pods matching a Deployment.
Its second half is for platform teams: you define your own higher-level API (an ObjectStore with just a region and a retention setting), describe in a composition which cloud resources that expands into, and application teams consume the simple API without learning every cloud setting.
CNCF daily · Sprint 5, post 11 of 14 · Orchestration & Management
At a glance
| Category | Orchestration & Management, subcategory Scheduling & Orchestration (CNCF Landscape) |
| CNCF status | Graduated. Accepted in 2020, Incubating in 2021; the graduation was announced on 6 November 2025 |
| Created by | Upbound, open-sourced in 2018 |
| Written in | Go. Runs as controllers (a core pod and an RBAC manager pod) in a Kubernetes cluster |
| License | Apache-2.0 |
| Current release line | v2.4 (released 20 August 2026). The newest patch I found is v2.4.3, in an Upbound release note dated 22 October 2026. The release table lists v2.5 for November 2026, so a newer release may already exist |
| Release cadence | A minor release roughly every three months. v1.20 reaches end of life in November 2026, when v2.5 ships |
| Core building blocks | Providers, managed resources (MRs), composite resource definitions (XRDs), compositions, composite resources (XRs), functions, ProviderConfigs, Operations |
| Providers | AWS, Azure, GCP, Kubernetes, Helm, Terraform, GitHub, Vault, Datadog and many more, from Upbound and the community. The AWS family alone covers hundreds of resource types |
| Install route | Helm chart crossplane-stable/crossplane, then Provider and Function packages |
| State | No separate state file. The Kubernetes API (etcd) is the source of truth |
The problem Crossplane solves
Provisioning and running are different tools. Many teams create cloud resources with an apply-and-exit tool and run applications with Kubernetes, so infrastructure drift is found by accident rather than corrected by a loop.
Developers do not want 40 settings. A database request should be “small, in region X”. Platform teams need a way to publish that smaller API and hide the networking, encryption and tags behind it.
Two sources of truth. If infrastructure lives in one workflow and applications in another, access control, approvals and GitOps are done twice.
Crossplane makes infrastructure another set of Kubernetes APIs, reconciled continuously, and gives the platform team a way to define those APIs themselves.
Key concepts
| Term | Meaning |
|---|---|
| Provider | A package that adds custom resource definitions and controllers for one external service, such as AWS S3. It translates Kubernetes objects into API calls and owns create, update and delete |
| ProviderConfig | Settings and credentials for a provider, for example how to authenticate to AWS. In v2 there is a namespaced form |
| Managed resource (MR) | A Kubernetes object that represents a real external resource, such as one S3 bucket. Deleting it deletes the real resource, unless a deletion or management policy says otherwise |
| Composite resource definition (XRD) | The schema of an API you define, for example ObjectStore |
| Composite resource (XR) | An instance of that API. It stands for a set of resources |
| Composition | The template that says which resources an XR becomes. In current releases a composition runs a pipeline of functions |
| Function | A small program Crossplane calls, in order, to compute the desired resources. Examples: Go templates, KCL, CUE, Python, CEL-based or kro-style composition |
| Claim | The older namespaced handle for a cluster-scoped XR. In v2 XRs can be namespaced themselves, and claims are kept for backwards compatibility |
| Operation | A v2 feature for operational workflows, beyond creating resources |
| Package | A Provider, Function or Configuration delivered as an OCI image |
Architecture
The platform team writes the XRD and Composition once; application teams create resources of the new kind and Crossplane does the rest. Blue is the application team, purple is Crossplane, grey is the platform team or a provider and green is the cloud. Open the zoomable diagram, or download it as SVG or PNG.
| Component | Responsibility |
|---|---|
| Crossplane core | Reconciles XRs, runs composition pipelines, manages packages and revisions. Two pods: Crossplane and the RBAC manager |
| RBAC manager | Creates roles for the resources that packages and XRDs add |
| Providers | Run as pods (one controller process per provider package) holding the credentials to reach the external API |
| Functions | Run as pods that Crossplane calls over gRPC with the observed and desired state |
| XRDs and compositions | The platform team’s API and implementation, stored as ordinary Kubernetes resources |
| etcd | Holds all desired and observed state. There is no separate Crossplane database |
Design principle. Reuse the Kubernetes control plane. Authentication, RBAC, admission, watches, GitOps and observability already exist; Crossplane adds new resource types and controllers rather than a separate system.
From a small spec to AWS resources
The loop keeps running, so drift in AWS is corrected back to the spec. Open the zoomable diagram, or download it as SVG or PNG.
- A user creates an XR with a small spec.
- Crossplane calls each function in the Composition’s pipeline in order. Each function reads the XR and the observed resources and returns the desired state.
- Crossplane applies the desired resources. A function can compose any Kubernetes resource in v2, not just Crossplane’s own.
- The provider reconciles each managed resource with AWS and reports state. Crossplane writes readiness (and any connection details) back to the XR. When the pipeline says all composed resources are ready, the XR is marked ready.
Crossplane documentation · What’s new in v2
Install Crossplane
Commands follow the project’s documentation and common AWS guides. I did not run them here. Replace placeholder versions.
Core, with Helm
helm repo add crossplane-stable https://charts.crossplane.io/stable
helm repo update
helm install crossplane crossplane-stable/crossplane \
--namespace crossplane-system --create-namespace --wait
kubectl get pods -n crossplane-system
The CLI
The crossplane CLI installs packages, renders compositions locally, traces resources and scaffolds control-plane projects. Install it from the project’s releases page and check crossplane --help for your version.
An AWS provider
apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
name: provider-aws-s3
spec:
package: xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:<version>
Providers are split by AWS service (S3, RDS, EC2 and so on), so install only the families you use. Documentation examples also use crossplane xpkg install provider <package> <name>.
Credentials: prefer a role over a key
On EKS use IAM Roles for Service Accounts (IRSA) or Pod Identity. The Upbound guide shows a provider runtime config that attaches the role to the provider’s service account and then a ProviderConfig:
apiVersion: aws.m.upbound.io/v1beta1
kind: ProviderConfig
metadata:
name: default
namespace: default
spec:
credentials:
source: IRSA
aws.m.upbound.io is the namespaced (v2) form. Older guides use aws.upbound.io with a cluster-scoped ProviderConfig, and some use InjectedIdentity or a Secret; match the example to your provider version.
Install a function
apiVersion: pkg.crossplane.io/v1
kind: Function
metadata:
name: function-go-templating
spec:
package: xpkg.crossplane.io/crossplane-contrib/function-go-templating:<version>
---
apiVersion: pkg.crossplane.io/v1
kind: Function
metadata:
name: function-auto-ready
spec:
package: xpkg.crossplane.io/crossplane-contrib/function-auto-ready:<version>
Using Crossplane
Snippets are adapted from the official guides and are untested here.
One managed resource
apiVersion: s3.aws.m.upbound.io/v1beta1
kind: Bucket
metadata:
name: example-bucket
namespace: default
spec:
forProvider:
region: eu-west-1
providerConfigRef:
kind: ProviderConfig
name: default
kubectl apply -f bucket.yaml
kubectl get buckets.s3.aws.m.upbound.io -n default
The object is ready when READY and SYNCED are both True. Bucket names are globally unique in AWS, so use a unique name. Deleting the object deletes the bucket.
Define your own API (XRD)
apiVersion: apiextensions.crossplane.io/v2
kind: CompositeResourceDefinition
metadata:
name: objectstores.example.org
spec:
scope: Namespaced
group: example.org
names:
kind: ObjectStore
plural: objectstores
versions:
- name: v1alpha1
served: true
referenceable: true
schema:
openAPIV3Schema:
type: object
properties:
spec:
type: object
properties:
region:
type: string
default: eu-west-1
required: [region]
In the v2 XRD API the scope field defaults to Namespaced; set Cluster for a cluster-scoped XR.
Implement it with a composition and functions
apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata:
name: objectstore-aws
spec:
compositeTypeRef:
apiVersion: example.org/v1alpha1
kind: ObjectStore
mode: Pipeline
pipeline:
- step: create-bucket
functionRef:
name: function-go-templating
input:
apiVersion: gotemplating.fn.crossplane.io/v1beta1
kind: GoTemplate
source: Inline
inline:
template: |
apiVersion: s3.aws.m.upbound.io/v1beta1
kind: Bucket
metadata:
annotations:
gotemplating.fn.crossplane.io/composition-resource-name: bucket
spec:
forProvider:
region: {{ .observed.composite.resource.spec.region }}
- step: mark-ready
functionRef:
name: function-auto-ready
mode: Pipeline makes each step call a function by functionRef. In a namespaced XR do not set metadata.namespace in templates; Crossplane uses the XR’s namespace. function-auto-ready marks the XR ready when its composed resources are ready.
Request it
apiVersion: example.org/v1alpha1
kind: ObjectStore
metadata:
name: shipments-archive
namespace: team-a
spec:
region: eu-west-1
Compose things that are not cloud resources
In v2, a composition can include any Kubernetes resource. The “get started” guide builds an App XR from a Deployment and a Service using function-go-templating, so one XR can create the database, the cloud bucket and the Deployment together.
Test locally
crossplane render runs a composition against an XR on your machine and prints the resources it would create, without a cluster. This is how compositions are unit-tested and reviewed in pull requests. crossplane beta trace shows the tree beneath a resource. I did not re-verify the exact flags in this pass.
Features
| Area | What you get |
|---|---|
| Providers | Managed resources for AWS, Azure, GCP and many other services, generated from Terraform providers (through Upjet) or written by hand |
| Continuous reconciliation | Drift in the cloud is corrected back to the declared spec |
| Composition | Build higher-level APIs from many resources with function pipelines |
| Functions | Pick the language: Go templates, KCL, CUE, Python, a kro-style YAML-and-CEL function, or write your own |
| Namespaced XRs and MRs (v2) | Default scope for composite and managed resources, giving ordinary Kubernetes multi-tenancy |
| Compose any Kubernetes resource (v2) | Applications and infrastructure in one abstraction |
| Operations (v2) | Declarative operational workflows. I did not research their details here |
| Connection details | Pass generated credentials to a Secret for the application |
| Packaging | Providers, functions and whole configurations ship as OCI packages and are versioned |
| Scalable composition | XRDs can expose a scale subresource |
| Management and deletion policies | Control which operations Crossplane may perform on a resource and whether deleting the object deletes the cloud resource |
| Upgrade readiness | A CLI upgrade check helps tell if a v1 control plane is ready for v2 |
Configuration reference
| Object or setting | Purpose |
|---|---|
Provider (pkg.crossplane.io/v1) |
Installs a provider package; spec.package is the OCI reference |
Function |
Installs a composition function |
ProviderConfig |
How a provider authenticates; credentials.source can be IRSA, WebIdentity, Secret, InjectedIdentity and others by provider |
providerConfigRef on an MR |
Which ProviderConfig the resource uses. Compositions can patch it per tenant |
CompositeResourceDefinition (apiextensions.crossplane.io/v2) |
Schema and scope (Namespaced or Cluster) of your API |
Composition |
compositeTypeRef, mode: Pipeline and pipeline[] steps with functionRef and input |
crossplane-system namespace |
Default home of the core pods and package pods |
| Helm values | Replicas, resources, args and feature flags for Crossplane; check the chart for your version |
writeConnectionSecretToRef |
Where to write connection details for an XR |
Production reference design
- One control plane per boundary. Many teams use a dedicated management cluster for Crossplane, kept small and well backed up.
- Install only the provider families you use, and pin versions of providers and functions. Upgrade providers like any other production dependency.
- Authenticate with roles, not keys. Use IRSA or Pod Identity for the provider and scope the IAM policy to what the compositions create.
- Use namespaces for tenancy. In v2, namespaced XRs and MRs plus Kubernetes RBAC give teams their own area, and compositions can pick a ProviderConfig per namespace.
- Keep XRDs small and stable. Treat them as public APIs and version them.
- Test compositions in CI with local render and a throwaway account.
- Drive it from Git with Argo CD or Flux so the cluster, not a laptop, applies changes.
- Protect important resources. Use deletion and management policies, and AWS-side protections such as bucket versioning, so deleting an object by mistake does not delete data.
- Size the control plane. Many managed resources mean many reconcilers; the project’s October 2026 blog post on client caching reports large provider memory reductions in crossplane-runtime v2.4, so watch memory.
Security
| Area | What to know |
|---|---|
| Cloud credentials | The provider pod holds credentials to create and delete real infrastructure. Prefer short-lived role credentials and a minimal IAM policy |
| Blast radius | Deleting an object can delete a database or bucket. Use deletion policy, management policy and cloud-side protections |
| Multi-tenancy | Use namespaced XRs and MRs, Kubernetes RBAC and per-namespace ProviderConfigs so a team can only use its own account or credentials |
| RBAC manager | Generates roles for new resource types; review them, since access to an XR can mean access to cloud spend |
| Supply chain | Providers and functions are OCI images that run in your cluster with powerful credentials. Pin versions and digests and prefer trusted publishers |
| Secrets | Connection details land in Secrets; restrict access and consider an external secret store |
| Patching | Upbound’s UXP release notes for 22 October 2026 mention updates for a Go toolchain vulnerability and dependency fixes. Stay on a supported minor |
Monitoring and day-2 operations
| Task | How |
|---|---|
| Check readiness | kubectl get on the XR and MRs; look at READY, SYNCED and conditions |
| Find why a composition is stuck | kubectl describe the XR, then trace its tree; read function and provider logs |
| Upgrade Crossplane | One minor at a time; read the upgrade guide and run the upgrade check before v1 to v2 |
| Upgrade providers | Update spec.package; managed resource API versions can change |
| Roll a composition | Compositions can be revisioned so existing XRs keep a known revision while you test a new one |
| Watch load | Provider memory and API rate limits grow with resource count |
| Adopt existing resources | Use observe-only management or an external name to import resources already in AWS |
| Symptom | First checks |
|---|---|
MR SYNCED false |
Provider logs and the resource’s conditions; usually IAM permission or an invalid field |
MR READY false for long |
AWS is still creating it, or a dependency is missing |
| XR never ready | A function returned an error, or function-auto-ready is missing from the pipeline |
| Composition error about namespace | A namespaced XR must not set metadata.namespace in templates |
| Authentication errors | ProviderConfig source and the role bound to the provider’s service account |
| Package pod not starting | Package image reference, version and cluster pull access |
Usage cases
- Self-service platform. Publish
Database,ObjectStoreorEnvironmentAPIs with sensible defaults and guardrails. - Multi-account, multi-region. One control plane managing many AWS accounts through ProviderConfigs.
- GitOps infrastructure. Commit infrastructure to Git and let Argo CD or Flux apply it to the control plane.
- App plus infrastructure in one API. A single object that creates a Deployment, a Service and the database it needs.
- Control planes for products. Software vendors expose their own APIs on top of Crossplane.
- Cold-chain sprint project. The Sprint 5 final project exposes AWS resources such as S3 Object Lock buckets and IoT things as Kubernetes APIs.
Operational considerations
- Learning curve. Compositions, functions and provider behaviour take time to learn; InfoQ’s graduation coverage notes early adopters reported a steep learning curve and debugging challenges when compositions or providers misbehaved.
- Another control plane to run. A cluster, its backup and upgrades become part of your infrastructure path.
- v1 to v2 migration. Namespaced MRs live in new API groups (
.m.groups), existing compositions work with minimal changes, and claims remain supported, but provider and API versions need a plan. - Provider coverage and drift. Providers generated from Terraform providers can lag behind new AWS features.
- Scale. Large numbers of managed resources raise memory and API-call volume.
- Deletion semantics. Mistakes at the Kubernetes layer become real deletions in AWS.
- Not every team needs it. If one team runs a handful of stable stacks, a plan-and-apply tool may be simpler.
Adoption
The Crossplane graduation announcement says the project has over 70 public adopters, including Nike, Nokia, Grafana, NASA Science Cloud, Elastic, Akamai, SAP and IBM. It also says Crossplane ranks 13th of 231 CNCF projects by number of PR authors. Upbound’s press release says it is trusted by more than a thousand teams; that is a vendor figure, so treat it as marketing.
Alternatives
| Solution | Model | Best suited to |
|---|---|---|
| OpenTofu (and Terraform) | Plan-and-apply from HCL with a state file; OpenTofu is the open-source Terraform fork | Teams that want the largest provider ecosystem and an explicit plan and review step; no cluster required. Crossplane’s Terraform provider can also run Terraform modules |
| Pulumi | Infrastructure in general-purpose languages, with managed state | Teams that want real programming languages; offers a Kubernetes operator for GitOps-style reconcile |
| AWS Controllers for Kubernetes (ACK) | Kubernetes controllers that map AWS services one to one | AWS-only teams that want native AWS objects without compositions |
| Config Connector and Azure Service Operator | The same idea for Google Cloud and Azure | Single-cloud shops on those clouds |
| CloudFormation and AWS CDK | AWS-native stacks | AWS-only teams who want the vendor’s tooling |
| kro | Kubernetes-native resource graphs; a Crossplane function brings its model into pipelines | Teams that only need to group Kubernetes resources |
Strengths and limitations
| Strengths | Limitations |
|---|---|
| Continuous reconciliation corrects drift | Needs a Kubernetes control plane to run and protect |
| Platform teams publish simple self-service APIs | Compositions and providers are hard to debug |
| One model for apps and infrastructure in v2 | v1 to v2 migration and API-group changes |
| Standard Kubernetes RBAC, GitOps and tooling | Provider coverage can lag new cloud features |
| No external state file | Resource-heavy at large scale |
| CNCF Graduated with a broad adopter base | A destructive delete is one kubectl delete away |
Project status and roadmap
Crossplane was open-sourced in 2018, accepted into CNCF in 2020, moved to Incubating in 2021 and Graduated with an announcement on 6 November 2025. Version 2.0 shipped in August 2025 with namespaced composite and managed resources, composition of any Kubernetes resource and Operations. Minor releases followed: v2.1 in November 2025, v2.2 in February 2026, v2.3 in May 2026 and v2.4 in August 2026, with v2.5 scheduled for November 2026 and v2.6 for February 2027. The project also publishes a roadmap page I did not read in full.
Recommendation
Adopt Crossplane if you run a platform team that wants to give application teams self-service infrastructure APIs, already runs Kubernetes and GitOps, and will invest in learning compositions and functions. Trial it on one resource type (for example object storage) alongside your existing tooling before moving anything critical. Assess OpenTofu or Pulumi if you do not need continuous reconciliation or a self-service layer, and ACK if you only want AWS services as Kubernetes objects. Before production: use roles for provider credentials, protect important resources with deletion and cloud-side safeguards, pin providers and functions, test compositions in CI and plan the v2 upgrade.
References: Crossplane documentation · What’s new in v2 · Compositions · Get started with composition · Get started with managed resources · Upgrade to Crossplane v2 · Concepts (v1.20) · Multi-tenant Crossplane · Announcing Crossplane 2.0 · Crossplane CNCF graduation · CNCF graduation announcement · AWS IRSA authentication (Upbound) · function-go-templating · function-auto-ready · Crossplane README and release table · CNCF project page

