تیم platform می‌خواهد developer فقط یک YAML بنویسد:

apiVersion: platform.example.com/v1
kind: App
metadata:
  name: checkout
spec:
  size: medium
  database: postgres

و پشت صحنه: VPC، RDS، IAM، Deployment، Service، Ingress، monitoring — همه provision و reconcile شوند.

بدون اینکه هر تیم infra expert شود. بدون اینکه برای هر abstraction یک controller Go بنویسید.

Crossplane همان framework است:

The Cloud-Native Framework for Platform Engineering — Build control planes for applications, not just infrastructure.

یعنی Kubernetes را به control plane برای هر چیزی گسترش دهید — cloud resources، SaaS، و از v2 به بعد حتی application stack کامل.

CNCF project — ساخته‌شده توسط Upbound، vendor-neutral، Apache 2.0. مستندات فعلی: docs.crossplane.io (v2.4).

مشکل: Terraform کافی نیست، Kubebuilder سنگین است

Terraform / Pulumi:
  apply یک‌بار → drift detection محدود
  state file جدا از cluster
  API سفارشی برای developer ندارد

Kubebuilder / custom controller:
  قدرت کامل
  هزینه نگهداری بالا برای هر API جدید

Crossplane:
  custom API (XRD) + Composition pipeline
  reconcile پیوسته مثل Kubernetes
  بدون نوشتن controller

Crossplane الگوی cloud vendorها را بازتولید می‌کند: control plane که desired state را می‌گیرد و تا lifecycle کامل نگه می‌دارد.

Crossplane چیست؟

Crossplane یک control plane framework است که:

• روی Kubernetes ساخته شده — همان API server، RBAC، etcd
• به شما اجازه می‌دهد API و abstraction خودتان را طراحی کنید
• با Providers تقریباً هر سیستم خارجی را manage می‌کند (AWS، Azure، GCP، Helm، Terraform، GitHub، …)
• با Composition منطق business را به‌جای Go controller، در pipeline توابع (YAML، KCL، Python، Go) بیان می‌کند
• با Package Manager Providers، Functions و Configurations را نصب می‌کند

Repo: github.com/crossplane/crossplane

Docs: docs.crossplane.io

چهار جزء اصلی

طبق مستندات رسمی:

می‌توانید همه را با هم استفاده کنید یا فقط بخشی را.

معماری مفهومی

Developer / CI / AI agent
        │
        ▼
   Custom API (XR)          ← XRD تعریف schema
   e.g. App, Database
        │
        ▼
   Composition Engine       ← Function pipeline
        │
        ├──► Deployment / Service / Ingress   (any K8s resource — v2)
        └──► Managed Resources (MRs)
                 │
                 ▼
           Provider controllers
                 │
         ┌───────┼───────┐
         ▼       ▼       ▼
        AWS    Azure    GCP / SaaS

کلید ارزش Crossplane: مزایای Kubernetes CRD را می‌گیرید بدون نوشتن و نگهداری controller پیچیده (Kubebuilder سطح پایین).

Composition: XRD، XR، Composition

Composite Resource Definition (XRD)

Schema API سفارشی شما — مثل CRD، اما Crossplane آن را مدیریت می‌کند:

apiVersion: apiextensions.crossplane.io/v1
kind: CompositeResourceDefinition
metadata:
  name: xapps.platform.example.com
spec:
  group: platform.example.com
  names:
    kind: XApp
    plural: xapps
  versions:
  - name: v1alpha1
    served: true
    referenceable: true
    schema:
      openAPIV3Schema:
        type: object
        properties:
          spec:
            type: object
            properties:
              size:
                type: string
                enum: [small, medium, large]
              database:
                type: string
            required: [size]

Composition

می‌گوید وقتی XR ساخته شد، چه منابعی ساخته شوند. در حالت مدرن: pipeline of Composition Functions.

apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata:
  name: app-aws
spec:
  compositeTypeRef:
    apiVersion: platform.example.com/v1alpha1
    kind: XApp
  mode: Pipeline
  pipeline:
  - step: patch-and-transform
    functionRef:
      name: function-patch-and-transform
    input:
      apiVersion: pt.fn.crossplane.io/v1beta1
      kind: Resources
      resources:
      - name: bucket
        base:
          apiVersion: s3.aws.upbound.io/v1beta1
          kind: Bucket
          spec:
            forProvider:
              region: us-east-1
        patches:
        - type: FromCompositeFieldPath
          fromFieldPath: metadata.name
          toFieldPath: metadata.name

Composite Resource (XR)

Instance از API شما:

apiVersion: platform.example.com/v1alpha1
kind: XApp
metadata:
  name: checkout
  namespace: team-a   # v2: namespaced by default
spec:
  size: medium
  compositionRef:
    name: app-aws

Composition Functions مثل pluginهای زبان config هستند: YAML (Patch & Transform)، KCL، Python، Go.

Managed Resources و Providers

Managed Resource (MR) یک CRD آماده است که یک سیستم خارجی را کنترل می‌کند:

kubectl apply -f rds-instance.yaml
  → Provider AWS controller
  → AWS RDS Instance واقعی
  → status.conditions، connection secrets

Provider پکیجی است که صدها MR را برای یک cloud/SaaS اضافه می‌کند:

نصب Provider:

cat <<EOF | kubectl apply -f -
apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
  name: provider-aws-s3
spec:
  package: xpkg.upbound.io/upbound/provider-aws-s3:v1.16.0
EOF

kubectl get providers
kubectl wait --for=condition=Healthy provider/provider-aws-s3 --timeout=120s

ProviderConfig و credentials

apiVersion: aws.upbound.io/v1beta1
kind: ProviderConfig
metadata:
  name: default
spec:
  credentials:
    source: Secret
    secretRef:
      namespace: crossplane-system
      name: aws-creds
      key: creds

Connection details معمولاً به Kubernetes Secret نوشته می‌شوند — برای مصرف توسط اپ یا cert-manager و tooling دیگر.

Crossplane v2: تغییر بزرگ

طبق اعلام Crossplane 2.0:

۱. Composition برای هر Kubernetes resource

دیگر فقط MRهای Crossplane نیست — می‌توانید در یک Composition:

• database + networking (MR)
• Deployment + Service + Ingress (native K8s)
• monitoring CRDها

را در یک abstraction جمع کنید. Platform team یک YAML به developer می‌دهد — full-stack.

۲. Namespaced by default

Cluster-scoped به‌عنوان legacy حفظ شده؛ پروژه‌های جدید باید الگوی v2 را بگیرند.

۳. Managed Resource filtering

با ManagedResourceDefinitions (MRDs) و activation policies فقط MRهایی که لازم دارید نصب می‌شوند — نه کل catalog عظیم Provider.

۴. Operations (alpha)

برای کارهایی که «create and keep forever» نیستند:

مثال: مانیتور SSL روی Ingress، rolling upgrade، maintenance — در کنار Composition و MRها.

۵. Backward compatibility

اکثر configهای v1.x کار می‌کنند؛ migration تدریجی ممکن است.

Package Manager

سه نوع package اصلی:

# Configuration = platform as a package
apiVersion: pkg.crossplane.io/v1
kind: Configuration
metadata:
  name: platform-ref-aws
spec:
  package: xpkg.upbound.io/upbound/platform-ref-aws:v0.9.0

با Configuration می‌توانید چند control plane یکسان داشته باشید — per region، per environment.

CLI:

crossplane xpkg build
crossplane xpkg push
crossplane beta render   # local Composition render

نصب Crossplane

پیش‌نیاز

• Kubernetes cluster (۱.۲۹+ توصیه برای v2)
• Helm 3
• دسترسی admin برای CRDها

Helm install

helm repo add crossplane-stable https://charts.crossplane.io/stable
helm repo update

helm install crossplane \
  crossplane-stable/crossplane \
  --namespace crossplane-system \
  --create-namespace

kubectl get pods -n crossplane-system
# crossplane-...
# crossplane-rbac-manager-...

نصب CLI

curl -sL https://raw.githubusercontent.com/crossplane/crossplane/master/install.sh | sh
sudo mv crossplane /usr/local/bin/
crossplane version

اولین MR (S3 مثال)

# 1. Provider
kubectl apply -f provider-aws-s3.yaml

# 2. Credentials secret + ProviderConfig

# 3. Managed Resource
cat <<EOF | kubectl apply -f -
apiVersion: s3.aws.upbound.io/v1beta1
kind: Bucket
metadata:
  name: demo-bucket
  namespace: default
spec:
  forProvider:
    region: us-east-1
  providerConfigRef:
    name: default
EOF

kubectl describe bucket demo-bucket
kubectl get bucket demo-bucket -o yaml | grep -A5 conditions

وضعیت معمول: Synced=True، Ready=True وقتی cloud resource ساخته شد.

Crossplane و GitOps

الگوی رایج production:

Git (desired)
  → [Argo CD](/blog/argo-project-kubernetes-gitops-cicd/)
  → Cluster (XRDs, Compositions, XRs, Providers)
  → Crossplane reconcile
  → Cloud APIs

مزایا نسبت به Terraform-only در GitOps:

• state در etcd / cluster — نه state file جدا
• drift به‌طور مداوم اصلاح می‌شود
• همان RBAC و audit Kubernetes
• developer با kubectl / Git همان API را مصرف می‌کند

ترکیب محبوب: Argo CD برای sync + Crossplane برای provision + Helm/Kustomize برای apps (یا همه داخل یک XR در v2).

امنیت و multi-tenancy

• RBAC Kubernetes روی XRها — تیم A فقط namespace خودش
• Provider credentials در Secret — محدود به ServiceAccount Crossplane
• Composition به‌عنوان guardrail — developer نمی‌تواند IAM wildcard بسازد؛ فقط size: medium می‌دهد
• NetworkPolicy / Cilium برای محدود کردن egress Provider pods به cloud APIs
• Separation of duties: platform team → XRD/Composition؛ app team → XR

Crossplane RBAC Manager به‌صورت پیش‌فرض دسترسی به MR/XRها را مدیریت می‌کند — اگر disable کنید، باید دستی grant بدهید.

Observability

kubectl get providers,functions,configurations
kubectl get composite
kubectl get managed   # or specific kinds: buckets, instances

# events و conditions
kubectl describe xapp checkout

# metrics
# Crossplane controllers expose Prometheus metrics
# provider-specific metrics too

Metrics مهم: reconcile latency، provider errors، package health.

برای DNS داخلی و service discovery بعد از provision، CoreDNS همچنان cluster DNS است — Crossplane جایگزین DNS نیست.

مقایسه: چه زمانی Crossplane؟

✅ استفاده کنید

• Internal Developer Platform با self-service API
• Multi-cloud / multi-account با abstraction واحد
• نیاز به continuous reconcile و drift correction
• تیم‌هایی که از قبل Kubernetes و GitOps دارند
• Guardrails: developer فقط پارامترهای امن ببیند

⚠️ شاید نه / جای دیگر بهتر

Crossplane جایگزین کامل Terraform برای همه تیم‌ها نیست — برای platform API روی Kubernetes طراحی شده. خیلی تیم‌ها Terraform را داخل Provider یا Composition نگه می‌دارند.

مثال end-to-end ذهنی

1. Platform team:
   - XRD: DatabaseClaim (engine, size, version)
   - Composition: RDS + SubnetGroup + SecurityGroup + Secret
   - Configuration package → publish

2. App team (Git):
   kind: DatabaseClaim
   spec: { engine: postgres, size: small }

3. Argo CD sync → XR created

4. Crossplane:
   - Functions render MRs
   - Provider AWS creates RDS
   - Connection secret → namespace app

5. App Deployment mounts secret → connects

Developer هرگز AWS console یا Terraform state نمی‌بیند — فقط API پلتفرم.

ارتباط با stack شما

GitOps ([Argo](/blog/argo-project-kubernetes-gitops-cicd/))
  └── Crossplane control plane
        ├── Providers → AWS / Azure / GCP
        ├── Composition → App + Infra APIs
        └── Secrets → apps / [cert-manager](/blog/cert-manager-kubernetes-tls-certificates/)

Cluster foundation:
  ├── [etcd](/blog/etcd-distributed-key-value-store-guide/) — state Crossplane CRDs
  ├── [Cilium](/blog/cilium-ebpf-kubernetes-networking/) — network + policy
  ├── [CoreDNS](/blog/coredns-kubernetes-dns-guide/) — discovery
  └── CRI ([containerd](/blog/containerd-container-runtime-guide/) / [CRI-O](/blog/cri-o-kubernetes-container-runtime-guide/))

Crossplane روی Kubernetes می‌نشیند — کیفیت control plane پایه (etcd، API server، networking) مستقیماً روی پایداری Provider reconcile اثر دارد.

Best practices

1. v2 namespaced XR برای پروژه‌های جدید
2. Composition Functions به‌جای Patch & Transform پیچیده
3. Configuration packages برای نسخه و reuse پلتفرم
4. کمترین Provider surface — فقط MRهای لازم (MRD filtering)
5. Credentials کوتاه‌عمر — IRSA / Workload Identity به‌جای static keys
6. GitOps برای XRD/Composition — نه apply دستی روی production
7. Composition به‌عنوان policy — نه فقط template
8. Test با crossplane beta render قبل از apply
9. Monitor Provider health و cloud API quotas
10. مستندسازی API پلتفرم برای developer (OpenAPI از XRD)

Troubleshooting

kubectl logs -n crossplane-system deploy/crossplane
kubectl logs -n crossplane-system -l pkg.crossplane.io/provider=provider-aws-s3
kubectl get events --field-selector reason=CannotConnectToProvider

جمع‌بندی

Crossplane به سازمان‌ها اجازه می‌دهد مثل cloud vendor پلتفرم بسازند: API اعلانی، self-service امن، و reconcile مداوم — روی همان foundation که Kubernetes اثبات کرده است.

قدم بعدی

1. Cluster آزمایشی + helm install crossplane
2. یک Provider کوچک (مثلاً S3 یا Helm) + یک MR
3. XRD ساده + Composition Function pipeline
4. XR را از Git با Argo CD sync کنید
5. به v2 patterns مهاجرت دهید (namespaced، full-stack Composition)

منابع

• Crossplane — crossplane.io
• Documentation (v2.4)
• What’s Crossplane?
• Announcing Crossplane 2.0
• Compositions
• GitHub — crossplane/crossplane
• CNCF Crossplane

منتشر شده در P30Light — بخش زیرساخت و سرور.