Happy Dussehra! May good always win. Merry Christmas! Warm wishes from Vizag. Happy New Year! Here’s to a great year ahead.

DevOps · CNCF daily

Crossplane: Cloud Infrastructure as Kubernetes APIs

CNCF Graduated. Turns a Kubernetes cluster into a control plane that provisions and continuously reconciles cloud resources, with providers for AWS and others, and compositions built from function pipelines that let a platform team publish simple self-service APIs.

18 min read

CNCF Graduated

  • Crossplane
  • Kubernetes
  • AWS
  • Compositions
  • Composition Functions
  • Providers
  • Helm
  • GitOps
CNCF project page

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

Crossplane architecture: an application team creates a resource with kubectl, Git or Argo CD. Crossplane controllers in the cluster read the XRD and Composition written by the platform team, run a pipeline of composition functions, and create managed resources. A provider turns managed resources into API calls to AWS.

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

Crossplane flow: a composite resource with a small spec goes into a function pipeline, which returns the desired managed resources. The provider applies them to AWS and reports state back, which Crossplane writes to the composite resource status as ready and synced. The loop keeps running so drift is corrected.

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.

  1. A user creates an XR with a small spec.
  2. 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.
  3. Crossplane applies the desired resources. A function can compose any Kubernetes resource in v2, not just Crossplane’s own.
  4. 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, ObjectStore or Environment APIs 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

Spotted something wrong or out of date?Suggest a correction. I review every suggestion before changing the page.