Crossplane

مستوى تحكم البنية التحتية كشفرة الأصلي في Kubernetes لتركيب موارد السحابة.

التثبيت

نواة Crossplane

الأمر	الوصف
helm repo add crossplane-stable https://charts.crossplane.io/stable	إضافة مستودع Helm لـ Crossplane
helm repo update	تحديث مستودعات Helm
helm install crossplane crossplane-stable/crossplane -n crossplane-system --create-namespace	تثبيت Crossplane على Kubernetes
helm install crossplane crossplane-stable/crossplane -n crossplane-system --set args='{"--debug"}'	التثبيت مع تسجيل التصحيح
helm upgrade crossplane crossplane-stable/crossplane -n crossplane-system	ترقية Crossplane
helm uninstall crossplane -n crossplane-system	إلغاء تثبيت Crossplane
kubectl get pods -n crossplane-system	التحقق من أن Crossplane يعمل
kubectl get deployments -n crossplane-system	التحقق من حالة النشر

تثبيت CLI

الأمر	الوصف
curl -sL https://raw.githubusercontent.com/crossplane/crossplane/master/install.sh | sh	تثبيت CLI الخاص بـ Crossplane
brew install crossplane/tap/crossplane	تثبيت CLI عبر Homebrew
crossplane --version	عرض إصدار CLI

أوامر CLI

إدارة الحزم

الأمر	الوصف
crossplane xpkg init my-config configuration	تهيئة حزمة تكوين جديدة
crossplane xpkg init my-provider provider	تهيئة حزمة provider جديدة
crossplane xpkg build	بناء حزمة Crossplane
crossplane xpkg build --package-root=./package --examples-root=./examples	البناء بأدلة محددة
crossplane xpkg push index.docker.io/org/config:v1	دفع الحزمة إلى السجل
crossplane xpkg install provider index.docker.io/org/provider:v1	تثبيت حزمة provider
crossplane xpkg install configuration index.docker.io/org/config:v1	تثبيت حزمة تكوين

التصحيح والتحقق

الأمر	الوصف
crossplane beta validate schema.yaml resources/	التحقق من الموارد مقابل المخطط
crossplane beta trace kind/name	تتبع تبعيات الموارد
crossplane beta trace kind/name -o wide	التتبع مع مخرجات موسعة
crossplane beta convert composition comp.yaml	تحويل Composition إلى وضع Pipeline
crossplane beta render xr.yaml composition.yaml functions.yaml	عرض الموارد المركبة محلياً

المزودون (Providers)

إعداد المزودين

الأمر	الوصف
kubectl apply -f provider-aws.yaml	تثبيت مزود AWS
kubectl apply -f provider-gcp.yaml	تثبيت مزود GCP
kubectl apply -f provider-azure.yaml	تثبيت مزود Azure
kubectl apply -f provider-kubernetes.yaml	تثبيت مزود Kubernetes
kubectl apply -f provider-helm.yaml	تثبيت مزود Helm
kubectl get providers	عرض المزودين المثبتين
kubectl get provider.pkg provider-aws -o yaml	عرض تفاصيل المزود
kubectl describe providerrevision	عرض حالة مراجعة المزود
kubectl get managed	عرض جميع موارد السحابة المُدارة
kubectl get managed -o wide	عرض الموارد المُدارة مع الحالة

تكوين مزود AWS

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

إنشاء سر بيانات الاعتماد:

kubectl create secret generic aws-creds \
  -n crossplane-system \
  --from-file=credentials=./aws-credentials.txt

تكوين مزود GCP

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

تكوين مزود Azure

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

الموارد المركبة (XRDs)

عمليات XRD

الأمر	الوصف
kubectl apply -f xrd.yaml	إنشاء CompositeResourceDefinition
kubectl get xrd	عرض جميع XRDs
kubectl describe xrd xdatabases.custom.example.com	عرض تفاصيل XRD
kubectl get composite	عرض جميع الموارد المركبة
kubectl describe composite	عرض حالة المورد المركب
kubectl delete xrd xdatabases.custom.example.com	حذف XRD
تعيين spec.claimNames في XRD	تفعيل المطالبات بنطاق مساحة الاسم
تعيين spec.versions[].schema في XRD	تعريف مخطط OpenAPI لـ XRD
تعيين spec.connectionSecretKeys في XRD	تعريف مفاتيح الاتصال المراد كشفها

مثال تعريف XRD

apiVersion: apiextensions.crossplane.io/v1
kind: CompositeResourceDefinition
metadata:
  name: xdatabases.platform.example.com
spec:
  group: platform.example.com
  names:
    kind: XDatabase
    plural: xdatabases
  claimNames:
    kind: Database
    plural: databases
  connectionSecretKeys:
    - endpoint
    - port
    - username
    - password
  versions:
    - name: v1alpha1
      served: true
      referenceable: true
      schema:
        openAPIV3Schema:
          type: object
          properties:
            spec:
              type: object
              properties:
                parameters:
                  type: object
                  properties:
                    engine:
                      type: string
                      enum: ["postgres", "mysql", "mariadb"]
                      description: "نوع محرك قاعدة البيانات"
                    engineVersion:
                      type: string
                      description: "إصدار المحرك"
                    storageGB:
                      type: integer
                      default: 20
                      description: "حجم التخزين بالجيجابايت"
                    instanceSize:
                      type: string
                      enum: ["small", "medium", "large"]
                      default: "small"
                  required:
                    - engine
              required:
                - parameters

التركيبات (Compositions)

عمليات Composition

الأمر	الوصف
kubectl apply -f composition.yaml	إنشاء Composition
kubectl get compositions	عرض جميع التركيبات
kubectl describe composition	عرض تفاصيل التركيبة
تعيين spec.compositeTypeRef في Composition	الربط بـ XRD
تعيين spec.resources[] في Composition	تعريف الموارد المركبة
استخدام patches في Composition	تعيين الحقول بين المركب والموارد
patch: { type: FromCompositeFieldPath }	تصحيح من المركب إلى المورد
patch: { type: ToCompositeFieldPath }	تصحيح من المورد إلى المركب
patch: { type: CombineFromComposite }	دمج حقول متعددة في واحد
تعيين spec.mode: Pipeline في Composition	استخدام وضع خط أنابيب الدوال

مثال Composition (وضع Resources)

apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata:
  name: xdatabase-aws
  labels:
    provider: aws
    engine: postgres
spec:
  compositeTypeRef:
    apiVersion: platform.example.com/v1alpha1
    kind: XDatabase
  resources:
    - name: rds-instance
      base:
        apiVersion: rds.aws.upbound.io/v1beta1
        kind: Instance
        spec:
          forProvider:
            engine: postgres
            instanceClass: db.t3.micro
            allocatedStorage: 20
            publiclyAccessible: false
            skipFinalSnapshot: true
            region: us-east-1
      patches:
        - type: FromCompositeFieldPath
          fromFieldPath: spec.parameters.engineVersion
          toFieldPath: spec.forProvider.engineVersion
        - type: FromCompositeFieldPath
          fromFieldPath: spec.parameters.storageGB
          toFieldPath: spec.forProvider.allocatedStorage
        - type: FromCompositeFieldPath
          fromFieldPath: spec.parameters.instanceSize
          toFieldPath: spec.forProvider.instanceClass
          transforms:
            - type: map
              map:
                small: db.t3.micro
                medium: db.t3.medium
                large: db.t3.large
      connectionDetails:
        - type: FromFieldPath
          name: endpoint
          fromFieldPath: status.atProvider.endpoint
        - type: FromFieldPath
          name: port
          fromFieldPath: status.atProvider.port
    - name: subnet-group
      base:
        apiVersion: rds.aws.upbound.io/v1beta1
        kind: SubnetGroup
        spec:
          forProvider:
            region: us-east-1
            description: "مُدار بواسطة Crossplane"
  writeConnectionSecretsToNamespace: crossplane-system

مثال Composition (وضع Pipeline)

apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata:
  name: xdatabase-pipeline
spec:
  compositeTypeRef:
    apiVersion: platform.example.com/v1alpha1
    kind: XDatabase
  mode: Pipeline
  pipeline:
    - step: patch-and-transform
      functionRef:
        name: function-patch-and-transform
      input:
        apiVersion: pt.fn.crossplane.io/v1beta1
        kind: Resources
        resources:
          - name: rds-instance
            base:
              apiVersion: rds.aws.upbound.io/v1beta1
              kind: Instance
              spec:
                forProvider:
                  engine: postgres
                  instanceClass: db.t3.micro
                  region: us-east-1
            patches:
              - type: FromCompositeFieldPath
                fromFieldPath: spec.parameters.storageGB
                toFieldPath: spec.forProvider.allocatedStorage
    - step: auto-ready
      functionRef:
        name: function-auto-detect-ready

المطالبات (Claims)

عمليات المطالبات

الأمر	الوصف
kubectl apply -f claim.yaml	إنشاء مطالبة مورد
kubectl get claim	عرض جميع المطالبات في مساحة الاسم
kubectl get database	عرض مطالبات من نوع Database
kubectl describe claim my-database	عرض حالة وأحداث المطالبة
kubectl delete claim my-database	حذف المطالبة والموارد المُدارة
تعيين spec.compositionRef.name في المطالبة	اختيار Composition محددة
تعيين spec.compositionSelector.matchLabels في المطالبة	اختيار Composition بالتسميات
kubectl get events --field-selector involvedObject.name=my-db	عرض أحداث المطالبة
kubectl get secret my-db-conn -o jsonpath='{.data.endpoint}'	قراءة تفاصيل الاتصال

مثال مطالبة

apiVersion: platform.example.com/v1alpha1
kind: Database
metadata:
  name: my-app-db
  namespace: default
spec:
  parameters:
    engine: postgres
    engineVersion: "15"
    storageGB: 50
    instanceSize: medium
  compositionSelector:
    matchLabels:
      provider: aws
      engine: postgres
  writeConnectionSecretToRef:
    name: my-app-db-conn

الدوال (Functions)

خط أنابيب الدوال

الأمر	الوصف
kubectl apply -f function.yaml	تثبيت دالة Composition
kubectl get functions	عرض الدوال المثبتة
kubectl describe function function-patch-and-transform	عرض تفاصيل الدالة
crossplane beta render xr.yaml composition.yaml functions.yaml	اختبار خط الأنابيب محلياً

الدوال الشائعة

# تثبيت function-patch-and-transform
apiVersion: pkg.crossplane.io/v1beta1
kind: Function
metadata:
  name: function-patch-and-transform
spec:
  package: xpkg.upbound.io/crossplane-contrib/function-patch-and-transform:v0.7.0
---
# تثبيت function-auto-detect-ready
apiVersion: pkg.crossplane.io/v1beta1
kind: Function
metadata:
  name: function-auto-detect-ready
spec:
  package: xpkg.upbound.io/crossplane-contrib/function-auto-detect-ready:v0.2.1
---
# تثبيت function-go-templating
apiVersion: pkg.crossplane.io/v1beta1
kind: Function
metadata:
  name: function-go-templating
spec:
  package: xpkg.upbound.io/crossplane-contrib/function-go-templating:v0.6.0

التكوين

EnvironmentConfig

apiVersion: apiextensions.crossplane.io/v1alpha1
kind: EnvironmentConfig
metadata:
  name: production
data:
  region: us-east-1
  environment: production
  vpcId: vpc-0abc123def456
  subnetIds:
    - subnet-0abc123
    - subnet-0def456
    - subnet-0ghi789
  tags:
    team: platform
    costCenter: engineering

نشر أسرار الاتصال

الأمر	الوصف
kubectl create secret generic aws-creds -n crossplane-system --from-file=creds=./aws-creds.txt	إنشاء سر بيانات اعتماد المزود
تعيين spec.credentials.source: Secret في ProviderConfig	الإشارة إلى سر بيانات الاعتماد
kubectl apply -f environmentconfig.yaml	إنشاء EnvironmentConfig
kubectl get storeconfig	عرض تكوينات التخزين
تعيين spec.publishConnectionDetailsTo في Composition	تكوين نشر أسرار الاتصال
تعيين spec.writeConnectionSecretToRef في المطالبة	كتابة تفاصيل الاتصال في سر
kubectl get secrets -l crossplane.io/claim-name=my-db	عرض الأسرار لمطالبة

تكوين التخزين لمخزن أسرار خارجي

apiVersion: secrets.crossplane.io/v1alpha1
kind: StoreConfig
metadata:
  name: vault
spec:
  type: Vault
  defaultScope: crossplane-system
  vault:
    mountPath: secret
    version: v2
    auth:
      method: Token
      token:
        source: Secret
        secretRef:
          namespace: crossplane-system
          name: vault-token
          key: token

استكشاف الأخطاء وإصلاحها

التشخيصات

الأمر	الوصف
kubectl get managed -o wide	عرض الموارد المُدارة مع الحالة
kubectl describe managed	عرض معلومات تفصيلية للموارد المُدارة
kubectl logs -n crossplane-system deploy/crossplane	عرض سجلات متحكم Crossplane
kubectl logs -n crossplane-system deploy/crossplane -f	متابعة سجلات المتحكم
kubectl get events --sort-by='.lastTimestamp'	عرض أحداث المجموعة الأخيرة
crossplane beta trace xdatabase my-db	تتبع شجرة الموارد الكاملة
crossplane beta trace xdatabase my-db -o wide	التتبع مع حالة تفصيلية
kubectl get managed -l crossplane.io/composite=my-db	العثور على موارد لمركب
kubectl annotate managed resource.api.example.com/name crossplane.io/paused=true	إيقاف مؤقت لمطابقة المورد
kubectl annotate managed resource.api.example.com/name crossplane.io/paused-	استئناف مطابقة المورد

المشاكل الشائعة

الأمر	الوصف
kubectl get providerrevision	التحقق مما إذا كان المزود سليماً
kubectl describe providerrevision	عرض أخطاء تثبيت المزود
kubectl get managed -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.conditions[*].reason}{"\n"}{end}'	حالة سريعة لجميع الموارد المُدارة
kubectl patch managed resource.api.example.com/name --type merge -p '{"metadata":{"annotations":{"crossplane.io/paused":"true"}}}'	الإيقاف المؤقت عبر التصحيح
kubectl delete managed --all	حذف جميع الموارد المُدارة (استخدم بحذر)

أفضل الممارسات

1. استخدام المطالبات بدلاً من المركبات المباشرة — المطالبات لها نطاق مساحة الاسم وتوفر حدود RBAC مناسبة بين الفرق.

2. تثبيت إصدارات المزودين — حدد دائماً إصدارات المزودين بدقة لمنع التغييرات غير المتوقعة أثناء الترقيات.

3. استخدام وضع Pipeline للتركيبات الجديدة — وضع Pipeline مع الدوال أكثر مرونة وقابلية للاختبار من وضع Resources.

4. تنفيذ EnvironmentConfigs — خزّن بيانات البيئة المشتركة مثل معرفات VPC وقوائم الشبكات الفرعية لتجنب التكرار عبر التركيبات.

5. إعداد نشر أسرار الاتصال — حدد دائماً writeConnectionSecretToRef في المطالبات حتى تتمكن التطبيقات من استهلاك تفاصيل الاتصال.

6. استخدام crossplane beta trace — هذه أسرع طريقة لتصحيح المشاكل عبر تصور شجرة الموارد الكاملة من المطالبة إلى المورد المُدار.

7. تسمية التركيبات للاختيار — استخدم تسميات مثل provider: aws وengine: postgres حتى تتمكن المطالبات من اختيار التركيبات بالتسمية بدلاً من الاسم.

8. الاختبار محلياً باستخدام crossplane beta render — اعرض تركيباتك محلياً قبل تطبيقها على مجموعة.

9. تنفيذ فحوصات الجاهزية — استخدم function-auto-detect-ready أو فحوصات جاهزية مخصصة لضمان أن الموارد المركبة تُبلّغ عن حالة دقيقة.

10. إصدار XRDs الخاصة بك — ابدأ بـ v1alpha1 وارتقِ عبر v1beta1 إلى v1 مع استقرار واجهة API الخاصة بك.