How do you build a complete internal developer platform (IDP) using Crossplane?

Building a complete internal developer platform (IDP) using Crossplane involves assembling a layered architecture where Crossplane serves as the infrastructure API and reconciliation engine, integrated with complementary tools that provide developer experience, GitOps automation, observability, and governance. The goal is to create a golden path where developers on teams like payments-api, user-auth-service, order-processing-service, checkout-service, and inventory-sync can provision complete application environments through a self-service interface without filing infrastructure tickets or learning cloud-specific APIs.

The API layer is where Crossplane provides the most value. Platform engineers design XRDs that represent the organization's infrastructure primitives: DatabaseInstance, CacheCluster, MessageQueue, ObjectStorage, and ApplicationEnvironment. The ApplicationEnvironment is the highest-level abstraction: a single Claim that provisions an entire application stack including a Kubernetes namespace, database, cache, message queue, DNS entry, and TLS certificate. The Composition for ApplicationEnvironment uses nested composite resources, where each sub-resource (database, cache) is itself an XR backed by its own Composition. This creates a Composition hierarchy that is maintainable and testable at each level. When a developer on the checkout-service team requests an ApplicationEnvironment, Crossplane provisions 15-20 managed resources across multiple providers, all from a single Claim with five fields.

The developer portal layer, typically Backstage, provides the UI and service catalog. Backstage templates map to Crossplane Claim types: a 'New Microservice' template generates a Git repository with application scaffolding, a Claim YAML file for the infrastructure, and an ArgoCD Application manifest for deployment. Developers fill out a form in Backstage specifying their service name, team, environment, and resource requirements. Backstage creates a pull request with the generated files, and after review and merge, ArgoCD deploys the Claim into the Crossplane control plane. The developer never writes YAML manually and does not need to understand Crossplane, Kubernetes, or cloud provider APIs.

The GitOps layer connects Backstage's output to Crossplane's input. ArgoCD watches the Git repository containing Claim manifests and syncs them to the Crossplane control plane cluster. Each team's Claims are stored in team-specific directories or repositories, with ArgoCD ApplicationSets generating Applications per team. This GitOps approach provides audit trails (every infrastructure change is a Git commit), rollback capability (revert a commit to undo a Claim), and drift detection (ArgoCD alerts when the cluster state diverges from Git). The order-processing-service team manages their Claims alongside their application manifests, creating a single source of truth for both application code and infrastructure.

The observability layer provides feedback to developers about their provisioned infrastructure. Crossplane's status conditions on Claims indicate whether resources are ready, synced, or in error. A custom Kubernetes operator or Prometheus exporter translates Claim status into metrics that power Grafana dashboards. Developers see a dashboard showing their database endpoint, connection status, storage utilization, and cost estimate, all linked from their Backstage service page. When the payments-api team's database Claim enters a degraded state, an alert fires in their PagerDuty rotation with a link to the Backstage service page showing the affected infrastructure.

The governance layer ensures that the golden path remains compliant and cost-effective. Kyverno policies enforce tagging standards, resource size limits, and required security configurations on Claims. Crossplane's composition functions add runtime logic like checking available budget before provisioning expensive resources. The platform team publishes a monthly cost report per team, generated by correlating cloud billing data with Claim ownership tags. The entire IDP operates as a product, with the platform team treating developers as customers: collecting feedback, iterating on Claim APIs based on usage patterns, and publishing a changelog when XRD schemas or Compositions are updated. This product mindset differentiates a successful IDP from a collection of tools that happens to include Crossplane.