docs/content/v2.0/whats-new/_index.md

title	weight	description
What's New in v2?	4	Learn what's new in Crossplane v2

Crossplane v2 makes Crossplane more useful, more intuitive, and less opinionated.

Crossplane v2 makes four major changes:

• Composite resources are now namespaced
• Managed resources are now namespaced
• Composition supports any Kubernetes resource
• Operations enable operational workflows

Crossplane v2 is better suited to building control planes for applications, not just infrastructure. It removes the need for awkward abstractions like claims and provider-kubernetes Objects.

flowchart LR
  user(User)

  subgraph ns [my-namespace]
    direction LR
    xr("App (XR)")
  	dply("Deployment")
    svc("Service")
    rds("RDSInstance (MR)")
  end

  user --create-->xr
  xr compose-dply@--compose--> dply
  xr compose-svc@--compose--> svc
  xr compose-rds@--compose--> rds
compose-dply@{animate: true}

compose-dply@{animate: true}
compose-svc@{animate: true}
compose-rds@{animate: true}

{{<hint "tip">}} Most users can upgrade to Crossplane v2 without breaking changes.

Read about Crossplane v2's backward compatibility. {{}}

{{<hint "note">}} This page assumes you're familiar with Crossplane. New to Crossplane? Read [What's Crossplane]({{<ref "../whats-crossplane">}}) instead. {{}}

Namespaced composite resources

Crossplane v2 makes composite resources (XRs) namespaced by default.

A namespaced XR can compose any resource (not just Crossplane resources) in its namespace.

A namespaced XR looks like this:

apiVersion: example.crossplane.io/v1
kind: App
metadata:
  namespace: default
  name: my-app
spec:
  image: nginx
  crossplane:
    compositionRef:
      name: app-kcl
    compositionRevisionRef:
      name: app-kcl-41b6efe
    resourceRefs:
    - apiVersion: apps/v1
      kind: Deployment
      name: my-app-9bj8j
    - apiVersion: v1
      kind: Service
      name: my-app-bflc4

{{<hint "note">}} Crossplane v2 moves all an XR's "Crossplane machinery" under spec.crossplane. This makes it easier for users to tell which fields are important to them, and which are just "Crossplane stuff" they can ignore. {{}}

Composite resource definitions (XRDs) now have a scope field. The scope field defaults to Namespaced in the new v2 version of the XRD API.

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
  # Removed for brevity

You can also set the scope field to Cluster to create a cluster scoped XR. A cluster scoped XR can compose any cluster scoped resource. A cluster scoped XR can also compose any namespaced resource in any namespace.

With namespaced XRs there's no longer a need for claims. The new namespaced and cluster scoped XRs in Crossplane v2 don't support claims.

{{<hint "tip">}} Crossplane v2 is backward compatible with v1-style XRs.

When you use v1 of the XRD API scope defaults to a special LegacyCluster mode. LegacyCluster XRs support claims and don't use spec.crossplane.

Read more about Crossplane v2's backward compatibility. {{}}

Namespaced managed resources

Crossplane v2 makes all managed resources (MRs) namespaced.

This enables a namespaced XR to by composed entirely of namespaced resources - whether they're a Crossplane MR like an RDSInstance, a Kubernetes resource like a Deployment, or a third party custom resource like a Cluster API Cluster.

A namespaced MR looks like this:

apiVersion: s3.aws.m.upbound.io/v1beta1
kind: Bucket
metadata:
  namespace: default
  generateName: my-bucket
spec:
  forProvider:
    region: us-east-2

Namespaced MRs work great with or without composition. Crossplane v2 isn't opinionated about using composition and MRs together. Namespaces enable fine grained access control over who can create what MRs.

{{<hint "note">}} Namespaced AWS managed resources are fully available in Crossplane v2.

Maintainers are actively working to update managed resources for other systems including Azure, GCP, Terraform, Helm, GitHub, etc to support namespaced MRs.

{{}}

{{<hint "tip">}} Crossplane v2 is backward compatible with v1-style cluster scoped MRs.

New provider releases will support both namespaced and cluster scoped MRs. Crossplane v2 considers cluster scoped MRs a legacy feature. Crossplane will deprecate and remove cluster scoped MRs at a future date.

Read more about Crossplane v2's backward compatibility. {{}}

Crossplane v2 also introduces [managed resource definitions]({{<ref "../managed-resources/managed-resource-definitions">}}) for selective activation of provider resources, reducing cluster overhead by installing only the managed resources you actually need.

Compose any resource

Crossplane v2 isn't opinionated about using composition together with managed resources.

You can create a composite resource (XR) that composes any resource, whether it's a Crossplane MR like an RDSInstance, a Kubernetes resource like a Deployment, or a third party custom resource like a CloudNativePG PostgreSQL Cluster.

flowchart LR
  user(User)

  subgraph ns [my-namespace]
    direction LR
    xr("App (XR)")
  	dply("Deployment")
    svc("Service")
    pg("CloudNativePG Cluster")
  end

  user --create-->xr
  xr compose-dply@--compose--> dply
  xr compose-svc@--compose--> svc
  xr compose-pg@--compose--> pg
compose-dply@{animate: true}

compose-dply@{animate: true}
compose-svc@{animate: true}
compose-pg@{animate: true}

This opens composition to exciting new use cases - for example building custom app models with Crossplane.

{{<hint "tip">}} You must grant Crossplane access to compose resources that aren't Crossplane resources like MRs or XRs. Read [the composition documentation]({{<ref "../composition/compositions#grant-access-to-composed-resources">}}) to learn how to grant Crossplane access. {{}}

Operations enable operational workflows

Crossplane v2 introduces Operations - a new way to run operational tasks using function pipelines.

Operations handle tasks that don't fit the typical resource creation pattern. Things like certificate monitoring, rolling upgrades, scheduled maintenance, or responding to resource changes.

Operations run function pipelines to completion, like a Kubernetes Job. Instead of continuously managing resources, they perform specific tasks and report the results.

apiVersion: ops.crossplane.io/v1alpha1
kind: CronOperation
metadata:
  name: cert-monitor
spec:
  schedule: "0 6 * * *"  # Daily at 6 AM
  mode: Pipeline
  pipeline:
  - step: check-certificates
    functionRef:
      name: crossplane-contrib-function-python
    # function checks SSL certificates and reports status

Operations support three modes:

• Operation - Run once to completion
• CronOperation - Run on a scheduled basis
• WatchOperation - Run when resources change

Operations can read existing resources and optionally change them. This enables workflows like annotating resources with operational data, triggering maintenance tasks, or implementing custom operational policies.

{{<hint "note">}} Operations are an alpha feature in Crossplane v2. {{}}

Backward compatibility

Crossplane v2 makes the following breaking changes:

• It removes native patch and transform composition.
• It removes the ControllerConfig type.
• It removes support for external secret stores.
• It removes the default registry for Crossplane Packages.

Crossplane deprecated native patch and transform composition in Crossplane v1.17. It's replaced by composition functions.

Crossplane deprecated the ControllerConfig type in v1.11. It's replaced by the DeploymentRuntimeConfig type.

Crossplane added external secret stores in v1.7. External secret stores have remained in alpha for over two years and are now unmaintained.

Crossplane v2 drops the --registry flag that allowed users to specify a default registry value and now requires users to always specify a fully qualified URL when installing packages, both directly via spec.package and indirectly as dependencies. Using fully qualified images was already a best practice, but it's now enforced to avoid confusion and unexpected behavior, to ensure users are aware of the registry used by their packages.

{{<hint "important">}} As long as you're not using these deprecated or alpha features, Crossplane v2 is backward compatible with Crossplane v1.x. {{}}

{{<hint "important">}} Before upgrading to Crossplane v2, please ensure all your Packages are using fully qualified images that explicitly specify a registry (registry.example.com/repo/package:tag).

Run kubectl get pkg to look for any packages that aren't fully qualified, then update or rebuild any Packages to use fully qualified images as needed. {{}}

Crossplane v2 supports legacy v1-style XRs and MRs. Most users can upgrade from v1.x to Crossplane v2 without breaking changes.

Existing Compositions require minor updates to work with Crossplane v2 style XRs and MRs. Follow the [Crossplane v2 upgrade guide]({{<ref "../guides/upgrade-to-crossplane-v2">}}) for step-by-step migration instructions.