writing-skills
writing-skills
Use when creating new skills, editing existing skills, or verifying skills work before deployment
crossplane"Crossplane in Platform Engineering - Kubernetes-native control plane" for multi-cloud infrastructure
Independent GitHub snapshot · Automated classification · Original documentation governs
name: crossplane compatibility: opencode completeness: 95 content-types:
related-skills: cncf-argo, cncf-artifact-hub, cncf-aws-eks, cncf-azure-aks
Category: platform
Status: Incubating
Stars: 6,200
Last Updated: 2026-04-22
Primary Language: Go
Documentation: https://crossplane.io/
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.
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.
Use Crossplane when you need:
┌─────────────────────────────────────────┐
│ Kubernetes API Server │
│ (Kubernetes API) │
└──────────────┬──────────────────────────┘
│
▼
┌─────────────────────────────────────────┐
│ Crossplane Core │
│ ┌──────────────┐ ┌─────────────────┐ │
│ │ Packages │ │ Configuration │ │
│ │ (Providers) │ │ (Compositions) │ │
│ └──────────────┘ └─────────────────┘ │
└──────────────┬──────────────────────────┘
│
▼
┌─────────────────────────────────────────┐
│ Cloud Provider APIs │
│ AWS Azure GCP Kubernetes │
└─────────────────────────────────────────┘
# 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 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
# 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
# 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
# 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
# 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
# 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
# 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
# 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 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 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
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
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
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
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
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"
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
// 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 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,
},
}
}
// 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)
}
}
}
Defines the schema for custom APIs
Maps XRDs to actual cloud resources
User-facing resource requests
Maps to external cloud provider APIs
# 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
# HA deployment
# Multiple Crossplane replicas
# Leader election
# Redundant storage
# 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 Crossplane state
# ETCD backup
# Provider credentials backup
# Custom API definitions backup
related-skills: cncf-argo, cncf-artifact-hub, cncf-aws-eks, cncf-azure-aks
This SKILL.md file was verified and last updated on 2026-04-22. Content based on CNCF Crossplane project and production usage patterns.
Deployment Failures
Performance Issues
Configuration Errors
Integration Problems
# 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 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 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
Use this skill when:
Assess Requirements — Understand the use case, scale, integration needs, and existing infrastructure. Checkpoint: Document requirements, constraints, and success criteria.
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.
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.
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.