مجموعة أدوات البنية التحتية كبرمجية

# مجموعة أدوات البنية التحتية كبرمجية — دليل الاستخدام

## ما تفعله هذه الإضافة

تقوم مجموعة أدوات البنية التحتية كبرمجية بربط ثلاث مهارات لتغطية دورة حياة النشر السحابي الكاملة: توفير البنية التحتية باستخدام Terraform، وحزم تطبيقك باستخدام Helm، ونشره إلى Kubernetes. استخدمها للانتقال من الصفر إلى بيئة إنتاج عاملة دون مغادرة مساعد الذكاء الاصطناعي الخاص بك.

---

## مثال على سير عمل كامل

**السيناريو:** نشر واجهة برمجة تطبيقات Node.js إلى AWS EKS.

**الخطوة 1 — توفير البنية التحتية السحابية** (`wshobson-terraform-module-library`)
```
إنشاء وحدة Terraform لمجموعة EKS الخاصة بـ AWS:
- المنطقة: us-east-1
- مجموعة العقد: 3x t3.medium
- VPC مع الشبكات الفرعية الخاصة
- تفعيل موسع المجموعة التلقائي

التشغيل: terraform init → terraform plan → terraform apply
```
النتيجة: ملفات وحدة Terraform (`main.tf` و `variables.tf` و `outputs.tf`) مع مجموعة EKS ومجموعة العقدة والشبكة المكوّنة. تظهر الخطة ~12 موردًا لإنشائها. يقوم التطبيق بتوفير المجموعة في حوالي 15 دقيقة.

**الخطوة 2 — حزم التطبيق** (`wshobson-helm-chart-scaffolding`)
```
إنشاء مخطط Helm لـ my-node-api:
- الصورة: my-registry/node-api:v1.2.0
- النسخ المتماثلة: 2
- المنفذ: 3000
- فحص الصحة: /health
- ConfigMap لمتغيرات البيئة
- HorizontalPodAutoscaler: 2-10 نسخ متماثلة عند 70% وحدة المعالجة المركزية
```
النتيجة: مخطط Helm كامل مع `Chart.yaml` و `values.yaml` و `templates/deployment.yaml` و `templates/service.yaml` و `templates/hpa.yaml` و `templates/configmap.yaml`. يتضمن برنامج `validate-chart.sh` النصي للتحقق من الأخطاء قبل النشر.

**الخطوة 3 — النشر إلى Kubernetes** (`wshobson-k8s-manifest-generator`)
```
إنشاء بيانات K8s لنشر my-node-api إلى مجموعة EKS:
- مساحة الاسم: production
- النشر: نسختان متماثلتان، حدود الموارد 256Mi/500m
- الخدمة: ClusterIP على المنفذ 80
- ConfigMap: LOG_LEVEL=info، NODE_ENV=production
- Secret: DATABASE_URL من Secrets Manager
```
النتيجة: `deployment.yaml` و `service.yaml` و `configmap.yaml` و `secret.yaml` جاهزة لـ `kubectl apply -f`.

---

## النطاق والحدود

**تتطلب هذه مجموعة الأدوات:**
- تثبيت أدوات CLI المحلية: `terraform` (>=1.0) و `helm` (>=3.0) و `kubectl` مكوّنة لمجموعتك
- تكوين بيانات اعتماد السحابة (AWS CLI أو GCP auth وما إلى ذلك) ليتم تطبيق Terraform
- مجموعة Kubernetes موجودة أو تم توفيرها في الخطوة 1

**هذه مجموعة الأدوات NOT:**
- تنفيذ `terraform apply` أو `kubectl apply` نيابة عنك — إنها تنشئ الملفات، وتقوم بتشغيل الأوامر
- استبدال خط أنابيب CI/CD الكامل (GitHub Actions أو ArgoCD أو FluxCD) — استخدم تلك للنشر التلقائي
- إدارة ترقيات المجموعة أو تدوير الشهادات أو تدويل الأسرار
- العمل مع المنصات المملوكة (Heroku أو Railway أو Render) — تستهدف K8s/Terraform القياسي

---

## استعادة الفشل

**Terraform: الموفر غير مكوّن**
الخطأ: `No valid credential sources found`. الإصلاح: قم بتشغيل `aws configure` (أو ما يعادلها لسحابتك) قبل `terraform init`. تحقق من خلال `terraform plan` — سيظهر خطأ المصادقة قبل لمس أي موارد.

**Terraform: رفض الإذن**
الخطأ: `AccessDenied` أثناء التطبيق. دور IAM/حساب الخدمة يفتقر إلى الأذونات المطلوبة. تحقق من الخطأ للحصول على الإجراء المحدد (مثل `eks:CreateCluster`). أضف الإذن المفقيد إلى نهج IAM، ثم أعد تشغيل `terraform apply` — سيقوم Terraform فقط بإنشاء الموارد المتبقية.

**Helm: فشل التحقق من صحة المخطط**
قم بتشغيل `helm lint ./my-chart` لرؤية الأخطاء المحددة. الأسباب الشائعة: قيم مطلوبة مفقودة في `values.yaml`، مسافة بادئة غير صالحة لـ YAML في القوالب. أصلح السطر المبلغ عنه، ثم أعد التحقق قبل النشر.

**Helm: الإصدار موجود بالفعل**
الخطأ: `cannot re-use a name that is still in use`. استخدم `helm upgrade my-release ./my-chart` بدلاً من `helm install`، أو أضف أعلام `--create-namespace --replace`.

**kubectl: المجموعة غير قابلة للوصول**
الخطأ: `Unable to connect to the server`. الإصلاح: قم بتشغيل `kubectl config get-contexts` للتحقق من تحديد المجموعة الصحيحة. بالنسبة إلى EKS: `aws eks update-kubeconfig --name <cluster-name> --region <region>` لتحديث بيانات الاعتماد.

**Pod CrashLoopBackOff بعد النشر**
قم بتشغيل `kubectl logs <pod-name> -n production` لرؤية أخطاء التطبيق. تحقق من أن جميع مفاتيح ConfigMap ومراجع Secret في البيان تتطابق مع ما يتوقعه التطبيق. أصلح البيان وأعد التطبيق.