Building reusable cloud APIs with Crossplane Compositions

Crossplane turns Kubernetes into a control plane for cloud infrastructure — but the real power for platform teams comes from Compositions: a way to design reusable, opinionated infrastructure APIs that developers consume as simple Kubernetes resources. This article walks through the what, the why, and a compact “get started” pattern using Compositions to provision an RDS database and an S3 bucket behind a single, developer-friendly Composite resource.

Why Compositions matter

• They let platform engineers define higher-level, cloud-agnostic APIs (CompositeResourceDefinitions) that map to one or more managed cloud resources.
• They reduce cognitive load for app teams: instead of learning multiple cloud consoles or Terraform modules, developers create a single composite resource like MySQLInstance or StorageBundle.
• They enable policy, tenancy, and lifecycle rules to live in the platform layer while keeping application manifests simple and declarative.

Crossplane’s composition model and patterns are documented in the official guides and include templated YAML, CEL transforms, and composition functions for advanced logic. (docs.crossplane.io)

Key concepts (brief)

• Provider: the implementation that talks to a cloud API (for example, provider-aws). Providers are installed into the control plane and need credentials (ProviderConfig). (docs.crossplane.io)
• Managed Resources: the low-level CRDs provided by a Provider (e.g., RDSInstance or S3 Bucket).
• CompositeResourceDefinition (XRD): a custom API that represents a higher-level intent (e.g., CompositeDatabase).
• Composition: a template describing which managed resources are created and how fields are composed/mapped.
• Composite Resource: an instance of an XRD that Crossplane reconciles into the managed resources defined by its Composition. Composition lifecycle features like CompositionRevisions let platform teams evolve compositions safely. (docs.crossplane.io)

Why GitOps + Crossplane is a natural fit Crossplane plays well with GitOps operators (Flux, ArgoCD): Git becomes the source of truth for both application and infra manifests, and Crossplane reconciles the cluster-side resources with the cloud. Several community and vendor guides show practical Flux + Crossplane workflows that let teams manage infrastructure entirely from Git. (oneuptime.com)

A compact example: one composite that creates an RDS + S3 bundle Imagine a Composite resource called StorageDB that provisions:

• an RDS instance for the app data, and
• an S3 bucket for backups and assets.

At a high level you need:

1. An XRD that defines the API surface developers will use.
2. A Composition that maps fields from the composite to provider-managed resources.
3. A Provider (provider-aws) and ProviderConfig so Crossplane can create AWS resources.

Minimal XRD (conceptual)

apiVersion: apiextensions.crossplane.io/v1
kind: CompositeResourceDefinition
metadata:
  name: storagedatabases.example.org
spec:
  group: example.org
  names:
    kind: StorageDatabase
    plural: storagedatabases
  claimNames:
    kind: StorageDBClaim
    plural: storagedbclaims
  versions:
    - name: v1
      served: true
      referenceable: true
      schema:
        openAPIV3Schema:
          properties:
            spec:
              properties:
                engine:
                  type: string
                size:
                  type: string
                bucketName:
                  type: string

Compact Composition (conceptual)

apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata:
  name: storagedb-composition
spec:
  compositeTypeRef:
    apiVersion: example.org/v1
    kind: StorageDatabase
  resources:
    - name: db
      base:
        apiVersion: database.aws.crossplane.io/v1beta1
        kind: RDSInstance
        spec:
          forProvider:
            allocatedStorage: 20
            engine: mysql
            instanceClass: db.t3.medium
      patches:
        - fromFieldPath: "spec.engine"
          toFieldPath: "spec.forProvider.engine"
        - fromFieldPath: "spec.size"
          toFieldPath: "spec.forProvider.instanceClass"
    - name: bucket
      base:
        apiVersion: s3.aws.crossplane.io/v1beta1
        kind: Bucket
        spec:
          forProvider:
            acl: private
      patches:
        - fromFieldPath: "spec.bucketName"
          toFieldPath: "spec.forProvider.name"

Notes

• This Composition creates two managed resources: an RDSInstance and an S3 Bucket, mapping fields from the composite’s spec into provider specs using patches.
• Real production compositions include more mapping, secrets handling, finalizers, and status propagation.

How to wire credentials and install providers

• Install Crossplane (Helm or YAML) and add the AWS provider package into the Crossplane installation. The Crossplane docs include quickstarts for installing providers and setting up ProviderConfig objects that point at Kubernetes Secrets for credentials. (docs.crossplane.io)
• For multi-tenant or more secure setups, use ProviderConfig patterns and secret injection (Vault or similar) so provider controllers run without storing long-lived plaintext credentials in application namespaces. Crossplane docs include guidance on Vault credential injection and multi-tenant patterns. (docs.crossplane.io)

A few practical tips from experience

• Start small: expose only a few fields in the XRD. Platform APIs should be opinionated; hiding complexity is the goal.
• Use CompositionRevisions: they give a safe rollout story when you update a composition — Crossplane can create a new revision and you can migrate XR instances over time. (docs.crossplane.io)
• Keep secrets lifecycle clear: have the composition write connection secrets into a controlled namespace where apps can access them, and apply RBAC so teams only see their own secrets.
• Use GitOps: store XRDs, Compositions, and ProviderConfig in Git and let Flux/Argo manage the cluster state. This enables auditable changes and easier rollbacks. (oneuptime.com)

Where Compositions shine (and where to be cautious)

• Shine: platform engineering, multi-cloud abstractions, developer self-service, reusable APIs, lifecycle automation.
• Caution: complexity can creep in. Compositions are powerful and can hide real cost/billing or operational constraints; platform teams must ensure observability, quotas, and cost controls are part of the design. Also, provider maturity varies — test provider behaviors (timeouts, API limits) before rolling into production.

Resources and where to read next

• Crossplane Composition docs and the “Get started with composition” guide are the canonical references for templates, patches, and advanced composition functions. (docs.crossplane.io)
• Provider quickstarts (for AWS, GCP, Azure) cover installing provider packages and configuring ProviderConfig objects for credentials. (docs.crossplane.io)
• Community and vendor guides describe common GitOps patterns combining Crossplane with Flux and ArgoCD. (oneuptime.com)

Parting thought Compositions let platform teams model infrastructure as higher-level Kubernetes APIs — think of them as building a bespoke, versioned “infrastructure API” tailored to your organization. The initial investment in designing XRDs and safe compositions pays off in developer velocity and predictable, auditable infrastructure deployments. Crossplane’s documentation and community guides make the path practical: start with a focused composite (like StorageDB above), validate provider behavior, and iterate toward a curated platform API that keeps app teams productive and operations predictable. (docs.crossplane.io)