# Crossplane > "Crossplane in Platform Engineering - Kubernetes-native control plane" for multi-cloud infrastructure - Skill: `paulpas/crossplane` (Agent Skill) - Install (CLI): `npx skillmds@latest add paulpas/crossplane` - Raw SKILL.md: https://api.skillmd.com/api/skills/paulpas/crossplane/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: DevOps & Infra - License: MIT - Author: paulpas (https://skillmd.com/u/paulpas) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/paulpas/crossplane --- related-skills: cncf-argo, cncf-artifact-hub, cncf-aws-eks, cncf-azure-aks # Crossplane in Cloud-Native Engineering **Category:** platform **Status:** Incubating **Stars:** 6,200 **Last Updated:** 2026-04-22 **Primary Language:** Go **Documentation:** [https://crossplane.io/](https://crossplane.io/) --- ## Purpose and Use Cases Crossplane is a CNCF incubating project that extends Kubernetes to enable platform teams to build custom control planes for managing infrastructure and services across any cloud. ### What Problem Does It Solve? Infrastructure as Code complexity and cloud fragmentation. Before Crossplane, platform teams had to manage separate tools (Terraform, CloudFormation, Cloud SDKs) for different cloud providers. Crossplane provides a unified Kubernetes API for infrastructure management. ### When to Use This Project Use Crossplane when you need: - Unified infrastructure management across multiple clouds - Self-service infrastructure for developers - GitOps-based infrastructure provisioning - Fine-grained access control for infrastructure resources - Custom infrastructure APIs that match your organization's needs ### Key Use Cases - **Multi-Cloud Platform**: Manage AWS, Azure, GCP with consistent APIs - **Self-Service Infrastructure**: Developers provision resources via Kubernetes manifests - **GitOps Infrastructure**: Infrastructure changes tracked in Git - **Custom Control Planes**: Build platform-specific APIs for your organization - **Legacy Modernization**: Migrate applications with infrastructure dependencies --- ## Architecture Design Patterns ### Crossplane Architecture ``` ┌─────────────────────────────────────────┐ │ Kubernetes API Server │ │ (Kubernetes API) │ └──────────────┬──────────────────────────┘ │ ▼ ┌─────────────────────────────────────────┐ │ Crossplane Core │ │ ┌──────────────┐ ┌─────────────────┐ │ │ │ Packages │ │ Configuration │ │ │ │ (Providers) │ │ (Compositions) │ │ │ └──────────────┘ └─────────────────┘ │ └──────────────┬──────────────────────────┘ │ ▼ ┌─────────────────────────────────────────┐ │ Cloud Provider APIs │ │ AWS Azure GCP Kubernetes │ └─────────────────────────────────────────┘ ``` ### Provider Configuration ```yaml # Provider configuration for external cloud apiVersion: pkg.crossplane.io/v1 kind: Provider metadata: name: provider-aws spec: package: crossplane/provider-aws:v0.36.0 registry: us-docker.pkg.dev/crossplane/releases revisionActivationPolicy: Automatic revisionHistoryLimit: 1 ``` ### Composition (Custom Resource Definition) ```yaml # Composition for custom API apiVersion: apiextensions.crossplane.io/v1 kind: Composition metadata: name: xpostgresqlinstances.postgresql.database.example.org spec: compositeTypeRef: apiVersion: database.example.org/v1alpha1 kind: XPostgreSQLInstance patchSets: - name: metadata patches: - fromFieldPath: metadata.labels resources: - name: postgresql base: apiVersion: database.aws.crossplane.io/v1beta1 kind: RDSInstance spec: forProvider: region: us-east-1 masterUsername: admin allocatedStorage: 20 engine: postgres engineVersion: "14" instanceClass: db.t3.micro patches: - fromFieldPath: metadata.name toFieldPath: spec.forProvider.dbName - fromFieldPath: spec.parameters.storage toFieldPath: spec.forProvider.allocatedStorage ``` ### Crossplane Resource Types #### 1. Composite Resources (XRs) ```yaml # Composite Resource - user-facing API apiVersion: database.example.org/v1alpha1 kind: XPostgreSQLInstance metadata: name: my-db spec: parameters: storage: 100 region: us-west-2 writeConnectionSecretToRef: name: my-db-creds namespace: production ``` #### 2. Claim Resources (XRCs) ```yaml # Claim Resource - namespace-scoped apiVersion: database.example.org/v1alpha1 kind: PostgreSQLInstance metadata: name: my-db-claim namespace: production spec: compositeRef: name: my-db writeConnectionSecretToRef: name: db-connection ``` #### 3. Provider Configurations ```yaml # ProviderConfig for AWS credentials apiVersion: aws.crossplane.io/v1beta1 kind: ProviderConfig metadata: name: aws-provider-config spec: credentials: source: Secret secretRef: namespace: crossplane-system name: aws-creds key: creds ``` --- related-skills: cncf-argo, cncf-artifact-hub, cncf-aws-eks, cncf-azure-aks ## Integration Approaches ### Kubernetes Native Integration #### 1. Installation ```bash # Install Crossplane via Helm helm repo add crossplane-stable https://charts.crossplane.io/stable helm repo update kubectl create namespace crossplane-system helm install crossplane --namespace crossplane-system crossplane-stable/crossplane ``` #### 2. Provider Setup ```yaml # Install AWS provider apiVersion: pkg.crossplane.io/v1 kind: Provider metadata: name: provider-aws spec: package: crossplane/provider-aws:v0.36.0 ``` ```bash # Create AWS credentials secret kubectl create secret generic aws-creds -n crossplane-system \ --from-file=creds= # Install provider kubectl apply -f provider-aws.yaml ``` ### Custom API Examples #### 1. Database Composition ```yaml # Define API group apiVersion: apiextensions.crossplane.io/v1 kind: CompositeResourceDefinition metadata: name: xpostgresqlinstances.database.example.org spec: group: database.example.org names: kind: XPostgreSQLInstance plural: xpostgresqlinstances versions: - name: v1alpha1 schema: openAPIV3Schema: type: object properties: spec: type: object properties: parameters: type: object properties: storage: type: integer description: Storage size in GB region: type: string description: AWS region served: true --- related-skills: cncf-argo, cncf-artifact-hub, cncf-aws-eks, cncf-azure-aks # Define composition apiVersion: apiextensions.crossplane.io/v1 kind: Composition metadata: name: xpostgresqlinstances.database.example.org spec: compositeTypeRef: apiVersion: database.example.org/v1alpha1 kind: XPostgreSQLInstance resources: - name: rds base: apiVersion: database.aws.crossplane.io/v1beta1 kind: RDSInstance spec: forProvider: region: us-east-1 masterUsername: admin engine: postgres engineVersion: "14" patches: - fromFieldPath: spec.parameters.storage toFieldPath: spec.forProvider.allocatedStorage - fromFieldPath: spec.parameters.region toFieldPath: spec.forProvider.region ``` #### 2. Network Composition ```yaml # VPC composition with subnets apiVersion: apiextensions.crossplane.io/v1 kind: CompositeResourceDefinition metadata: name: xvpcs.network.example.org spec: group: network.example.org names: kind: XVPC plural: xvpcs versions: - name: v1alpha1 served: true --- related-skills: cncf-argo, cncf-artifact-hub, cncf-aws-eks, cncf-azure-aks apiVersion: apiextensions.crossplane.io/v1 kind: Composition metadata: name: xvpcs.network.example.org spec: compositeTypeRef: apiVersion: network.example.org/v1alpha1 kind: XVPC resources: - name: vpc base: apiVersion: ec2.aws.crossplane.io/v1beta1 kind: VPC spec: forProvider: region: us-east-1 cidrBlock: "10.0.0.0/16" patches: - fromFieldPath: metadata.name toFieldPath: spec.forProvider.tags[0].Value - name: subnet-private base: apiVersion: ec2.aws.crossplane.io/v1beta1 kind: Subnet spec: forProvider: region: us-east-1 vpcIdSelector: matchControllerRef: true cidrBlock: "10.0.1.0/24" mapPublicIpOnLaunch: false - name: subnet-public base: apiVersion: ec2.aws.crossplane.io/v1beta1 kind: Subnet spec: forProvider: region: us-east-1 vpcIdSelector: matchControllerRef: true cidrBlock: "10.0.2.0/24" mapPublicIpOnLaunch: true ``` ### GitOps Integration ```yaml # GitOps workflow with Crossplane # 1. Developer creates claim in Git apiVersion: database.example.org/v1alpha1 kind: PostgreSQLInstance metadata: name: app-db namespace: production spec: compositeRef: name: app-db writeConnectionSecretToRef: name: app-db-creds # 2. GitOps syncs to cluster # 3. Crossplane creates composite resource # 4. Cloud resources provisioned # 5. Connection secret created ``` ### Multi-Cloud Support ```yaml # Multi-cloud composition example apiVersion: apiextensions.crossplane.io/v1 kind: Composition metadata: name: multicloud-buckets.objectstorage.example.org spec: compositeTypeRef: apiVersion: objectstorage.example.org/v1alpha1 kind: XObjectStorage resources: - name: aws-s3 condition: us-region base: apiVersion: s3.aws.crossplane.io/v1beta1 kind: Bucket spec: forProvider: region: us-east-1 - name: gcp-gcs condition: eu-region base: apiVersion: gcp.crossplane.io/v1beta1 kind: Bucket spec: forProvider: projectRef: from: name: gcp-project location: US ``` --- related-skills: cncf-argo, cncf-artifact-hub, cncf-aws-eks, cncf-azure-aks ## Common Pitfalls and How to Avoid Them ### 1. Provider Version Management **Pitfall:** Using outdated provider versions with breaking changes. ```yaml # ❌ Incorrect - no version pinning apiVersion: pkg.crossplane.io/v1 kind: Provider metadata: name: provider-aws spec: package: crossplane/provider-aws # ✅ Correct - version pinned apiVersion: pkg.crossplane.io/v1 kind: Provider metadata: name: provider-aws spec: package: crossplane/provider-aws:v0.36.0 # Pinned version ``` ### 2. Connection Secret Management **Pitfall:** Connection secrets not properly scoped. ```yaml # ❌ Incorrect - secret in wrong namespace apiVersion: database.example.org/v1alpha1 kind: PostgreSQLInstance metadata: name: my-db spec: writeConnectionSecretToRef: name: db-creds namespace: default # Should match app namespace --- related-skills: cncf-argo, cncf-artifact-hub, cncf-aws-eks, cncf-azure-aks apiVersion: database.example.org/v1alpha1 kind: PostgreSQLInstance metadata: name: my-db spec: writeConnectionSecretToRef: name: db-creds namespace: production # ✅ Correct - production namespace ``` ### 3. Composition Patching Errors **Pitfall:** Incorrect field paths in composition patches. ```yaml # ❌ Incorrect - wrong field path patches: - fromFieldPath: spec.params.storage toFieldPath: spec.forProvider.allocatedStorage # ✅ Correct - correct field path patches: - fromFieldPath: spec.parameters.storage toFieldPath: spec.forProvider.allocatedStorage ``` ### 4. Resource Deletion Protection **Pitfall:** Accidental deletion of managed resources. ```yaml # ❌ Incorrect - no deletion protection apiVersion: database.example.org/v1alpha1 kind: XPostgreSQLInstance metadata: name: my-db spec: deletionPolicy: Delete # Default - risky # ✅ Correct - with deletion protection apiVersion: database.example.org/v1alpha1 kind: XPostgreSQLInstance metadata: name: my-db annotations: crossplane.io/external-name: my-db-protected spec: deletionPolicy: Retain # Keep in case of error ``` ### 5. Resource Limits **Pitfall:** Missing resource limits on Crossplane controllers. ```yaml # ❌ Incorrect - no resource limits apiVersion: apps/v1 kind: Deployment metadata: name: crossplane spec: template: spec: containers: - name: crossplane image: crossplane/crossplane:latest # No resource limits # ✅ Correct - with resource limits apiVersion: apps/v1 kind: Deployment metadata: name: crossplane spec: template: spec: containers: - name: crossplane image: crossplane/crossplane:latest resources: requests: cpu: "100m" memory: "128Mi" limits: cpu: "500m" memory: "512Mi" ``` ### 6. ProviderConfig References **Pitfall:** ProviderConfig not properly referenced. ```yaml # ❌ Incorrect - missing provider config reference apiVersion: database.aws.crossplane.io/v1beta1 kind: RDSInstance spec: forProvider: region: us-east-1 # Missing providerConfigRef # ✅ Correct - with provider config reference apiVersion: database.aws.crossplane.io/v1beta1 kind: RDSInstance spec: forProvider: region: us-east-1 providerConfigRef: name: aws-provider-config ``` --- related-skills: cncf-argo, cncf-artifact-hub, cncf-aws-eks, cncf-azure-aks ## Coding Practices ### Custom API Definitions ```go // Custom API definition for Crossplane package v1alpha1 import ( metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" "k8s.io/apimachinery/pkg/runtime" ) // DatabaseType represents the type of database type DatabaseType string const ( DatabaseTypePostgreSQL DatabaseType = "PostgreSQL" DatabaseTypeMySQL DatabaseType = "MySQL" DatabaseTypeSQLServer DatabaseType = "SQLServer" ) // DatabaseParameters defines the desired state type DatabaseParameters struct { Storage int `json:"storage"` Region string `json:"region"` Version string `json:"version,omitempty"` Type DatabaseType `json:"type,omitempty"` } // DatabaseStatus defines the observed state type DatabaseStatus struct { Bound bool `json:"bound,omitempty"` Endpoint string `json:"endpoint,omitempty"` Port int `json:"port,omitempty"` Engine string `json:"engine,omitempty"` EngineVersion string `json:"engineVersion,omitempty"` } // +kubebuilder:object:root=true // +kubebuilder:subresource:status // +kubebuilder:resource:scope=Cluster // Database is the Schema for the databases API type Database struct { metav1.TypeMeta `json:",inline"` metav1.ObjectMeta `json:"metadata,omitempty"` Spec DatabaseSpec `json:"spec,omitempty"` Status DatabaseStatus `json:"status,omitempty"` } // DatabaseSpec defines the desired state type DatabaseSpec struct { Parameters DatabaseParameters `json:"parameters"` } // DatabaseList contains a list of Database type DatabaseList struct { metav1.TypeMeta `json:",inline"` metav1.ListMeta `json:"metadata,omitempty"` Items []Database `json:"items"` } func init() { SchemeBuilder.Register(&Database{}, &DatabaseList{}) } ``` ### Composition Generator ```go // Composition generator for common patterns package generator import ( apiextensionsv1 "apiextensions.crossplane.io/v1" databasev1alpha1 "example.com/api/v1alpha1" ) // CompositionGenerator generates compositions type CompositionGenerator struct { name string version string resources []apiextensionsv1.CompositionResource } // NewCompositionGenerator creates a new generator func NewCompositionGenerator(name, version string) *CompositionGenerator { return &CompositionGenerator{ name: name, version: version, resources: []apiextensionsv1.CompositionResource{}, } } // WithResource adds a resource to the composition func (g *CompositionGenerator) WithResource(base apiextensionsv1.CompositionResource) *CompositionGenerator { g.resources = append(g.resources, base) return g } // WithAWSRDS adds an RDS instance resource func (g *CompositionGenerator) WithAWSRDS() *CompositionGenerator { base := apiextensionsv1.CompositionResource{ Name: "rds-instance", Base: apiextensionsv1.CompositionResourceSpec{ APIVersion: "database.aws.crossplane.io/v1beta1", Kind: "RDSInstance", Spec: apiextensionsv1.CompositionSpec{ ForProvider: map[string]interface{}{ "region": "us-east-1", "masterUsername": "admin", "engine": "postgres", "engineVersion": "14", }, }, }, PatchSets: []apiextensionsv1.PatchSet{ { Name: "metadata", Patches: []apiextensionsv1.Patch{ { FromFieldPath: "metadata.labels", }, }, }, }, } return g.WithResource(base) } // WithAWSS3 adds an S3 bucket resource func (g *CompositionGenerator) WithAWSS3() *CompositionGenerator { base := apiextensionsv1.CompositionResource{ Name: "s3-bucket", Base: apiextensionsv1.CompositionResourceSpec{ APIVersion: "s3.aws.crossplane.io/v1beta1", Kind: "Bucket", Spec: apiextensionsv1.CompositionSpec{ ForProvider: map[string]interface{}{ "region": "us-east-1", }, }, }, } return g.WithResource(base) } // Build creates the Composition func (g *CompositionGenerator) Build() *apiextensionsv1.Composition { return &apiextensionsv1.Composition{ TypeMeta: metav1.TypeMeta{ APIVersion: "apiextensions.crossplane.io/v1", Kind: "Composition", }, ObjectMeta: metav1.ObjectMeta{ Name: g.name, }, Spec: apiextensionsv1.CompositionSpec{ CompositeTypeRef: apiextensionsv1.TypeReference{ APIVersion: g.version, Kind: "X" + g.name, }, Resources: g.resources, }, } } ``` ### Testing ```go // Crossplane integration testing package test import ( "context" "testing" "time" "github.com/stretchr/testify/assert" "k8s.io/apimachinery/pkg/types" ) func TestDatabaseProvisioning(t *testing.T) { ctx := context.Background() client := newTestClient() // Create database claim claim := &databasev1alpha1.Database{ ObjectMeta: metav1.ObjectMeta{ Name: "test-db", }, Spec: databasev1alpha1.DatabaseSpec{ Parameters: databasev1alpha1.DatabaseParameters{ Storage: 100, Region: "us-east-1", }, }, } err := client.Create(ctx, claim) assert.NoError(t, err) // Wait for provisioning timeout := time.After(5 * time.Minute) for { select { case <-timeout: t.Fatal("Timeout waiting for database provisioning") default: var db databasev1alpha1.Database err := client.Get(ctx, types.NamespacedName{Name: "test-db"}, &db) assert.NoError(t, err) if db.Status.Bound { assert.NotEmpty(t, db.Status.Endpoint) assert.NotEmpty(t, db.Status.Port) return } time.Sleep(10 * time.Second) } } } ``` --- ## Fundamentals ### Crossplane Core Components #### 1. Package Manager - Manages providers and configurations - Supports Helm charts and OCI images - Handles versioning and upgrades #### 2. Resource Controllers - Reconciles cross-resource dependencies - Manages resource lifecycles - Handles errors and retries #### 3. Composition Engine - Processes compositions - Maps claims to composites - Generates resource trees ### API Types #### 1. Composite Resource Definitions (XRDs) Defines the schema for custom APIs #### 2. Compositions Maps XRDs to actual cloud resources #### 3. Claims User-facing resource requests #### 4. Providers Maps to external cloud provider APIs --- ## Scaling and Deployment Patterns ### Multi-Tenant Setup ```bash # Multi-tenant Crossplane # Each team has isolated resources # Shared control plane # Team A namespace apiVersion: v1 kind: Namespace metadata: name: team-a --- related-skills: cncf-argo, cncf-artifact-hub, cncf-aws-eks, cncf-azure-aks # Team A claim apiVersion: database.example.org/v1alpha1 kind: PostgreSQLInstance metadata: name: team-a-db namespace: team-a spec: compositeRef: name: team-a-db ``` ### High Availability ```bash # HA deployment # Multiple Crossplane replicas # Leader election # Redundant storage ``` ### Rate Limiting ```yaml # Provider config with rate limiting apiVersion: aws.crossplane.io/v1beta1 kind: ProviderConfig metadata: name: aws-provider-config spec: credentials: source: Secret secretRef: namespace: crossplane-system name: aws-creds key: creds rateLimit: ReadObjects: 100 WriteObjects: 50 ReadResources: 100 WriteResources: 50 ``` ### Backup Strategy ```bash # Backup Crossplane state # ETCD backup # Provider credentials backup # Custom API definitions backup ``` --- related-skills: cncf-argo, cncf-artifact-hub, cncf-aws-eks, cncf-azure-aks ## Additional Resources ### Official Documentation - [Crossplane](https://crossplane.io/) - Project website - [Crossplane Documentation](https://crossplane.io/docs/) - Complete documentation - [Crossplane GitHub](https://github.com/crossplane/crossplane) - Source code - [Crossplane Examples](https://github.com/crossplane/cluster-packages) - Examples ### Implementations - [Kubernetes Crossplane](https://kubernetes.io/docs/tasks/extend-kubernetes/) - Kubernetes integration - [Crossplane Operator](https://github.com/crossplane/cluster-packages) - Operator pattern - [Crossplane CLI](https://github.com/crossplane/crossplane/tree/master/cmd/crossplane) - CLI tools ### Community Resources - [CNCF Crossplane](https://www.cncf.io/projects/crossplane/) - CNCF project page - [Crossplane Slack](https://kubernetes.slack.com/archives/C01E380J7TQ) - Community discussion - [Crossplane Mailing List](https://lists.cncf.io/g/cncf-crossplane) - Announcements ### Learning Resources - [Crossplane Getting Started](https://crossplane.io/docs/latest/getting-started/) - Tutorial - [Crossplane Examples](https://github.com/crossplane/cluster-packages/tree/master/examples) - Examples - [Crossplane Webinars](https://www.cncf.io/crossplane-webinars/) - Video content --- *This SKILL.md file was verified and last updated on 2026-04-22. Content based on CNCF Crossplane project and production usage patterns.* ## Troubleshooting ### Common Issues 1. **Deployment Failures** - Check pod logs for errors - Verify configuration values - Ensure network connectivity 2. **Performance Issues** - Monitor resource usage - Adjust resource limits - Check for bottlenecks 3. **Configuration Errors** - Validate YAML syntax - Check required fields - Verify environment-specific settings 4. **Integration Problems** - Verify API compatibility - Check dependency versions - Review integration documentation ### Getting Help - Check official documentation - Search GitHub issues - Join community channels - Review logs and metrics ## Examples ### Basic Configuration ```yaml # Basic configuration example apiVersion: v1 kind: ConfigMap metadata: name: {{project_name}}-config namespace: default data: # Configuration goes here config.yaml: | # Base configuration # Add your settings here ``` ### Kubernetes Deployment ```yaml # Kubernetes deployment for {{project_name}} apiVersion: apps/v1 kind: Deployment metadata: name: {{project_name}} namespace: default spec: replicas: 1 selector: matchLabels: app: {{project_name}} template: metadata: labels: app: {{project_name}} spec: containers: - name: {{project_name}} image: {{project_name}}:latest ports: - containerPort: 8080 resources: limits: memory: "128Mi" cpu: "500m" ``` ### Kubernetes Service ```yaml # Kubernetes service for {{project_name}} apiVersion: v1 kind: Service metadata: name: {{project_name}} namespace: default spec: selector: app: {{project_name}} ports: - protocol: TCP port: 80 targetPort: 8080 type: ClusterIP ``` --- ## When to Use Use this skill when: - **Integrating a CNCF project into Kubernetes infrastructure** — You need to configure, deploy, or troubleshoot a cloud-native tool within a cluster - **Designing cloud-native architecture** — You are selecting and integrating CNCF tools to solve specific infrastructure challenges - **Resolving operational issues** — A CNCF component is misbehaving, underperforming, or needs configuration changes --- ## Core Workflow 1. **Assess Requirements** — Understand the use case, scale, integration needs, and existing infrastructure. **Checkpoint:** Document requirements, constraints, and success criteria. 2. **Design Architecture** — Plan component interactions, data flow, and deployment strategy using cloud-native best practices. **Checkpoint:** Verify the architecture addresses all requirements and follows CNCF conventions. 3. **Implement & Configure** — Create manifests, configurations, and deployment scripts. Include resource limits, health checks, and observability hooks. **Checkpoint:** Validate all YAML against schema and test in a staging environment. 4. **Deploy & Monitor** — Apply manifests to the cluster, verify component health, and confirm observability is working. **Checkpoint:** Confirm all pods/services are running, probes passing, and metrics/alerts configured. --- ## Constraints ### MUST DO - Include at least one complete working YAML manifest example - Note when content is auto-generated vs. manually verified - Reference relevant CNCF project documentation ### MUST NOT DO - Deploy manifests without testing in a staging environment first - Use deprecated API versions (e.g., apps/v1beta1) - Omit resource limits and requests in Kubernetes manifests