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/

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

# 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)

# 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)

# 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)

# 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

# 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

# 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

# Install AWS provider
apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
  name: provider-aws
spec:
  package: crossplane/provider-aws:v0.36.0

# Create AWS credentials secret
kubectl create secret generic aws-creds -n crossplane-system \
  --from-file=creds=<credentials-file>

# Install provider
kubectl apply -f provider-aws.yaml

Custom API Examples

1. Database Composition

# 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

# 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

# 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

# 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.

# ❌ 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.

# ❌ 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.

# ❌ 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.

# ❌ 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.

# ❌ 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.

# ❌ 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

// 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

// 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

// 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

# 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

# HA deployment
# Multiple Crossplane replicas
# Leader election
# Redundant storage

Rate Limiting

# 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

# 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 - Project website
• Crossplane Documentation - Complete documentation
• Crossplane GitHub - Source code
• Crossplane Examples - Examples

Implementations

• Kubernetes Crossplane - Kubernetes integration
• Crossplane Operator - Operator pattern
• Crossplane CLI - CLI tools

Community Resources

• CNCF Crossplane - CNCF project page
• Crossplane Slack - Community discussion
• Crossplane Mailing List - Announcements

Learning Resources

• Crossplane Getting Started - Tutorial
• Crossplane Examples - Examples
• 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

# 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

# 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

# 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