Crossplane Explained: Kubernetes-Native Infra Provisioning

How Crossplane works: providers, managed resources, XRDs, compositions and functions, a working install and example, and what changed in Crossplane v2.

Aug 18, 2025 - 15:21
Nov 8, 2026 - 00:41
 0  60
Crossplane Explained: Kubernetes-Native Infra Provisioning

Crossplane turns a Kubernetes cluster into a control plane for infrastructure. Providers add custom resources for cloud services, compositions bundle them into your own APIs, and controllers keep reconciling the real world to match what you declared. You create an S3 bucket or a database with kubectl, the same way you create a Deployment.

This guide explains the moving parts, shows a working install and a custom API, and covers what changed in Crossplane v2. It focuses on how the system works. For the Git-driven delivery angle, read why Crossplane is a key GitOps provisioning tool.

Key takeaways

  • Crossplane is a control plane framework built on Kubernetes. You get new custom resources without writing controllers, because compositions are pipelines of functions.
  • Managed resources map one to one to an external object, such as an S3 bucket. Composite resources (XRs) bundle several resources behind one API that your platform team designs.
  • Crossplane v2 adds namespaced composite resources, Operations (alpha) and fully qualified package names, and removes native patch and transform, ControllerConfig and external secret stores. The Crossplane docs show v2.4 as the latest version.
  • Compositions run in Pipeline mode only. Older compositions that use mode: Resources must be converted to function pipelines.
  • The CNCF lists Crossplane as a graduated project, reached on 28 October 2025.
  • Crossplane suits teams that build self-service platforms on Kubernetes. If you only manage a few cloud resources, a tool such as Terraform may be simpler.

The idea in plain terms

Kubernetes already knows how to keep a desired state. You declare three replicas, and controllers create pods until three exist and replace any that die. Crossplane applies that loop to things outside the cluster. You declare "a bucket in this region", and a provider's controller calls the cloud API until the bucket exists and matches. If someone changes it by hand, the controller notices and puts it back.

That has two consequences. Your infrastructure is described in the same YAML style as your applications, so it fits the same review and delivery process. And because the Kubernetes API is the interface, access control (RBAC), audit logs and tools like kubectl work on infrastructure too.

The core concepts

ConceptWhat it doesWho touches it
Provider (package)Installs controllers and CRDs for one external system, such as AWS S3Platform team
ProviderConfig / ClusterProviderConfigTells a provider how to authenticate, for example from a Kubernetes SecretPlatform team
Managed resource (MR)A custom resource that represents one external object, such as a BucketPlatform team, or users in simple setups
Composite resource definition (XRD)Defines the schema of your own APIPlatform team
CompositionDescribes which resources an XR creates, using a pipeline of functionsPlatform team
Composite resource (XR)One instance of your API; "a set of Kubernetes resources as a single object"Application teams
FunctionA plugin in the pipeline that returns declarative configuration (YAML, KCL, Python and Go are listed options)Platform team
OperationA function pipeline that runs to completion like a Job; alpha in v2Platform team

The split is the point. The platform team writes XRDs and compositions once. Application teams then create an XR with a few fields and never touch cloud-specific details. The same idea sits behind Kubernetes operators, except Crossplane lets you build the API declaratively.

Step 1: install Crossplane

You need a running Kubernetes cluster that is a supported version and Helm 3.2.0 or later.

helm repo add crossplane-stable https://charts.crossplane.io/stable
helm repo update
helm install crossplane \
  --namespace crossplane-system \
  --create-namespace crossplane-stable/crossplane

kubectl get pods -n crossplane-system

The output should list a crossplane pod and a crossplane-rbac-manager pod, both Running. Pin the chart version in real environments with --version and upgrade deliberately. If you are new to Helm, see the role of Helm in Kubernetes deployment management.

Step 2: add a provider and credentials

A provider is a package. This example installs the S3 provider from the Crossplane docs:

apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
  name: crossplane-contrib-provider-aws-s3
spec:
  package: xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v2.0.0
kubectl apply -f provider.yaml
kubectl get providers

Right after you apply it, INSTALLED is True and HEALTHY is Unknown. When the provider is ready, HEALTHY turns True. If it stays False, run kubectl describe providerrevisions to find the reason.

Next, tell the provider how to authenticate. The docs example reads credentials from a Secret and uses a cluster-wide config:

apiVersion: aws.m.upbound.io/v1beta1
kind: ClusterProviderConfig
metadata:
  name: default
spec:
  credentials:
    source: Secret
    secretRef:
      namespace: crossplane-system
      name: aws-secret
      key: creds

A long-lived access key in a Secret is fine for a lab, but for production prefer short-lived credentials from your cluster's cloud identity mechanism where the provider supports it. Credentials for the provider are powerful, so scope the IAM permissions to only the resources you intend Crossplane to manage.

Step 3: create a managed resource

A managed resource is the lowest level. This Bucket comes from the Crossplane docs:

apiVersion: s3.aws.m.upbound.io/v1beta1
kind: Bucket
metadata:
  namespace: default
  generateName: crossplane-bucket-
spec:
  forProvider:
    region: us-east-2
kubectl create -f bucket.yaml
kubectl get buckets.s3.aws.m.upbound.io

It uses generateName because S3 bucket names are globally unique, and you use create rather than apply for that reason. Crossplane has created the bucket when SYNCED and READY both show True. Deleting the managed resource deletes the bucket in AWS, so delete resources before you uninstall the provider or you will need to clean up by hand.

Note the .m. in the API group (aws.m.upbound.io). In v2 the namespaced managed resources use a group with that infix.

Step 4: build your own API with a composition

Managed resources expose every cloud setting. Most application teams want a small, safe surface, so the platform team defines an XRD. The example below is from the Crossplane "get started with composition" guide and defines an App API with one required field.

apiVersion: apiextensions.crossplane.io/v2
kind: CompositeResourceDefinition
metadata:
  name: apps.example.crossplane.io
spec:
  scope: Namespaced
  group: example.crossplane.io
  names:
    kind: App
    plural: apps
  versions:
  - name: v1
    served: true
    referenceable: true
    schema:
     openAPIV3Schema:
       type: object
       properties:
        spec:
          type: object
          properties:
            image:
              description: The app's OCI container image.
              type: string
          required:
          - image
        status:
          type: object
          properties:
            replicas:
              type: integer

Compositions use functions. First install a function package, such as the patch-and-transform function used in the docs:

apiVersion: pkg.crossplane.io/v1
kind: Function
metadata:
  name: crossplane-contrib-function-patch-and-transform
spec:
  package: xpkg.crossplane.io/crossplane-contrib/function-patch-and-transform:v0.8.2

Then write the composition. This trimmed version creates only the Deployment, copying the XR's name and image into it and reporting available replicas back to the XR status:

apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata:
  name: app-yaml
spec:
  compositeTypeRef:
    apiVersion: example.crossplane.io/v1
    kind: App
  mode: Pipeline
  pipeline:
  - step: create-deployment
    functionRef:
      name: crossplane-contrib-function-patch-and-transform
    input:
      apiVersion: pt.fn.crossplane.io/v1beta1
      kind: Resources
      resources:
      - name: deployment
        base:
          apiVersion: apps/v1
          kind: Deployment
          spec:
            replicas: 2
            template:
              spec:
                containers:
                - name: app
                  ports:
                  - containerPort: 80
        patches:
        - type: FromCompositeFieldPath
          fromFieldPath: metadata.name
          toFieldPath: metadata.labels[example.crossplane.io/app]
        - type: FromCompositeFieldPath
          fromFieldPath: metadata.name
          toFieldPath: spec.selector.matchLabels[example.crossplane.io/app]
        - type: FromCompositeFieldPath
          fromFieldPath: metadata.name
          toFieldPath: spec.template.metadata.labels[example.crossplane.io/app]
        - type: FromCompositeFieldPath
          fromFieldPath: spec.image
          toFieldPath: spec.template.spec.containers[0].image
        - type: ToCompositeFieldPath
          fromFieldPath: status.availableReplicas
          toFieldPath: status.replicas
        readinessChecks:
        - type: MatchCondition
          matchCondition:
            type: Available
            status: "True"

A user now asks for an application with three lines:

apiVersion: example.crossplane.io/v1
kind: App
metadata:
  namespace: default
  name: demo-app
spec:
  image: nginx:1.27
kubectl apply -f app.yaml
kubectl get apps.example.crossplane.io -n default
kubectl describe apps.example.crossplane.io demo-app -n default

This example composes plain Kubernetes objects so you can try it on any cluster. In real platforms the same pipeline step creates managed resources, for instance a Bucket plus an IAM policy plus a bucket policy, all behind one Storage API. A composition can contain several function steps, and Crossplane uses the result returned by the last function.

How reconciliation works

  1. You apply an XR. Crossplane matches its group and kind to a composition through compositeTypeRef.
  2. The function pipeline runs and returns the desired composed resources.
  3. Crossplane creates or updates them and labels each composed resource with crossplane.io/composite, naming its owning XR.
  4. Provider controllers see the managed resources and call the cloud API.
  5. Status flows back. The XR shows a Synced condition (reconciliation succeeded) and a Ready condition (the pipeline reports every composed resource ready).

When something is wrong, read conditions from the top down: the XR first, then its composed resources, then the provider pod logs. A Synced=False on a managed resource usually carries the cloud API error message, such as a missing permission or an invalid name.

What changed in Crossplane v2

Areav1 behaviorv2 change per the upgrade guide
ScopeXRs were cluster scoped; XRDs default to LegacyClusterXRs can be namespaced; v1-style resources keep working and are not migrated automatically
Managed resource API groupsCluster scopedNamespaced managed resources use groups with .m, such as s3.aws.m.upbound.io
Native patch and transformCompositions with mode: ResourcesRemoved (deprecated in v1.17); move to function pipelines
ControllerConfigUsed to tune provider podsRemoved; use DeploymentRuntimeConfig
External secret storesAlpha featureRemoved; use Kubernetes Secrets or External Secrets Operator
Composite connection detailsNative on XRsRemoved on XRs; managed resources still support writeConnectionSecretToRef
Package namesRegistry could be set with a flagThe --registry flag is removed; use fully qualified names that include the registry host
OperationsNot availableOperation, CronOperation and WatchOperation (alpha) run pipelines to completion

If you are upgrading a v1 setup, plan it as a migration, not a version bump. Convert compositions first, rename package references, and test on a non-production control plane. The Crossplane CLI can convert some resources, and the guide names the versions that support it.

Crossplane and Terraform

QuestionCrossplaneTerraform
Where does it run?Inside a Kubernetes cluster as controllersFrom a CLI or CI job
When does it act?Continuously reconcilesWhen you run plan and apply
Interface for usersKubernetes API and kubectlHCL files and workspaces
Self-service APIsCore feature (XRDs and compositions)Modules, usually with a wrapper or portal
Best fitPlatform teams already running KubernetesGeneral infrastructure provisioning, any team

They are not exclusive. See infrastructure as code tools compared and Terraform in production. Crossplane adds a cluster you must run and upgrade, and its control plane becomes critical infrastructure, so weigh that cost.

Operating it well

  • Keep XRDs, compositions and function versions in Git and deploy them with a GitOps tool, as described in what GitOps is and GitOps deployment best practices.
  • Pin provider and function package versions. A moving tag changes your infrastructure without a pull request.
  • Decide deletion behavior deliberately. Removing a resource from Git can delete real infrastructure, so review that path before enabling pruning.
  • Back up the control plane state or be able to rebuild it from Git. Losing the cluster that tracks external objects is a serious incident.
  • Limit who can create XRs and managed resources with RBAC, and keep provider credentials scoped.

Crossplane assumes you are comfortable with Kubernetes objects, CRDs and RBAC. The CKA course builds that base, and the Terraform course covers the main alternative approach. Both run in the classroom in Kharadi, Pune and live online.

Frequently asked questions

What is Crossplane in simple terms?

Crossplane is a Kubernetes add-on that lets you create and manage cloud resources with Kubernetes YAML. Providers add resource types, compositions let you design your own APIs on top, and controllers keep reality matching your declaration.

What is the difference between a managed resource and a composite resource?

A managed resource represents one external object, such as one S3 bucket. A composite resource represents a group of resources behind an API you define, created by a composition. Application teams usually use composite resources.

Do I still need Terraform if I use Crossplane?

Not necessarily, but many teams run both. Crossplane works well where a Kubernetes-based platform with self-service APIs is the goal. Terraform often remains for foundation resources and teams that do not run Kubernetes.

What changed in Crossplane v2?

Composite resources can be namespaced, Operations were added as alpha, and package names must be fully qualified. Native patch and transform, ControllerConfig, external secret stores and XR connection details were removed.

Is Crossplane a CNCF project?

Yes. The CNCF lists it as accepted on 25 June 2020, incubating from 14 September 2021, and graduated on 28 October 2025.

What is a Crossplane function?

A function is a plugin step in a composition pipeline. It receives the composite resource and returns the desired resources. Functions can be written in several languages, and the docs list YAML, KCL, Python and Go as options.

How do I debug a Crossplane resource that is not ready?

Check the Synced and Ready conditions on the composite resource with kubectl describe, then inspect its composed resources, then provider logs. A Synced=False condition usually carries the cloud API error text.

Official references

What's Your Reaction?

Like Like 0
Dislike Dislike 0
Love Love 0
Funny Funny 0
Angry Angry 0
Sad Sad 0
Wow Wow 0
Mridul I am a passionate technology enthusiast with a strong focus on DevOps, Cloud Computing, and Cybersecurity. Through my blogs at DevOps Training Institute, I aim to simplify complex concepts and share practical insights for learners and professionals. My goal is to empower readers with knowledge, hands-on tips, and industry best practices to stay ahead in the ever-evolving world of DevOps.