How do you design a self-service platform using Crossplane with namespace-scoped Claims?

Designing a self-service platform with Crossplane Claims creates a clean separation between platform engineering teams who define infrastructure blueprints and application teams who consume them. The architecture follows a producer-consumer model where the platform team authors XRDs and Compositions at the cluster scope, and development teams like payments-api, user-auth-service, and order-processing-service submit Claims in their respective namespaces to provision infrastructure on demand. This model mirrors the organizational boundary between infrastructure ownership and application ownership.

The foundation is the CompositeResourceDefinition (XRD), which defines both the cluster-scoped Composite Resource (XR) and the namespace-scoped Claim (XRC) API. The XRD schema specifies what parameters application teams can configure, such as database size, region, engine version, and backup retention, while hiding implementation details like subnet placement, security group rules, and encryption configuration. For the checkout-service team, the Claim API might expose a simple interface with fields like size (small, medium, large), environment, and team, while the underlying Composition translates these into dozens of managed resources across multiple providers.

Compositions define the implementation behind Claims. A single XRD can have multiple Compositions selected by composition selectors or labels. For example, a PostgreSQLInstance XRD might have compositions for AWS Aurora, GCP Cloud SQL, and Azure Database for PostgreSQL. When the order-processing-service team submits a Claim with a cloud: aws label, Crossplane selects the AWS composition and provisions an RDS Aurora cluster with the appropriate VPC configuration, parameter groups, and IAM authentication. The composition patches map Claim spec fields to managed resource fields, with transforms for value conversion and string formatting.

Namespace-scoped Claims provide natural RBAC boundaries. Kubernetes RBAC controls which teams can create Claims in which namespaces. The payments-api team might have permission to create DatabaseInstance and CacheCluster Claims in the payments namespace, while the user-auth-service team can only create DatabaseInstance Claims in the auth namespace. Connection details such as endpoints, usernames, and passwords are published as Secrets in the Claim's namespace, making them accessible only to pods in that namespace. This prevents cross-team credential leakage without any additional secret management infrastructure.

The self-service workflow integrates with existing developer tools. Teams can define Claims in their GitOps repositories alongside application manifests, so ArgoCD or Flux deploys both the application and its infrastructure dependencies. The platform team maintains a service catalog documenting available Claim types with examples. When the inventory-sync team needs a new Redis cache, they add a CacheCluster Claim to their GitOps repo, open a pull request, and after review and merge, ArgoCD applies the Claim, Crossplane provisions the ElastiCache cluster, and connection details appear as a Secret that the inventory-sync deployment mounts.

Production considerations for self-service platforms include implementing resource quotas using Crossplane's Usage resources or OPA Gatekeeper policies to prevent teams from over-provisioning, setting up Crossplane's composition functions for complex logic that patches alone cannot express (like conditional resource creation based on environment), monitoring Claim readiness with custom Prometheus metrics scraped from the Crossplane controllers, and establishing a clear upgrade path for XRD schema evolution that maintains backward compatibility with existing Claims across the checkout-service, payments-api, and order-processing-service namespaces.