كتابة كتيبات التشغيل والتحليلات البعدية وتوثيق IaC

التوثيق الجيد ينقذ الأرواح — أو على الأقل ينقذ فريقك من الذعر في الساعة 3 صباحاً. يغطي هذا الدرس كيفية كتابة توثيق DevOps واضح وقابل للتنفيذ بالإنجليزية: كتيبات التشغيل والتحليلات البعدية وتوثيق Terraform ووثائق Kubernetes وطلبات التغيير.

كتابة كتيبات التشغيل

كتيب التشغيل (Runbook) هو دليل خطوة بخطوة للتعامل مع مهمة تشغيلية أو حادث محدد. يجب أن يكون واضحاً بما يكفي ليتبعه أي شخص في فريقك — حتى تحت الضغط.

قالب كتيب التشغيل

# Runbook: [العنوان — مثلاً "High CPU on API Servers"]

## Trigger (المُشغِّل)
ما التنبيه أو الحالة التي تُفعّل هذا الكتيب؟
- Alert: "CPU utilization > 90% for 5 minutes on api-server-*"
- PagerDuty service: API Platform

## Impact (التأثير)
ما الذي يتأثر إذا لم تُحل هذه المشكلة؟
- أوقات استجابة API تزداد
- العملاء قد يواجهون انتهاء مهلة
- الشدة: SEV2 إذا استمر لأكثر من 10 دقائق

## Prerequisites (المتطلبات المسبقة)
- الوصول إلى مجموعة Kubernetes الإنتاجية
- kubectl مُعد لسياق الإنتاج
- لوحة Grafana: "API Server Metrics"

## Steps (الخطوات)

### Step 1: Verify the alert (تحقق من التنبيه)
شغّل الأمر التالي للتحقق من استخدام CPU الحالي:

kubectl top pods -n api-production

**المتوقع:** واحد أو أكثر من الـ Pods يظهر CPU > 900m.
**إذا لم تظهر أي Pods بـ CPU عالي:** التنبيه قد يكون قديماً.
تحقق من Grafana لآخر 30 دقيقة.

### Step 2: Check for recent deployments (تحقق من عمليات النشر الأخيرة)

kubectl rollout history deployment/api-server -n api-production

**إذا كان هناك نشر حديث:** فكر في التراجع (انظر الخطوة 4).

### Step 3: Scale up the deployment (وسّع النشر)

kubectl scale deployment/api-server --replicas=5 -n api-production

**التحقق:** انتظر دقيقتين، ثم تحقق من CPU مرة أخرى:

kubectl top pods -n api-production

**المتوقع:** CPU ينخفض تحت 70% لكل Pod.

### Step 4: Rollback (التراجع — إذا كان السبب نشراً)

kubectl rollout undo deployment/api-server -n api-production

**التحقق:** تأكد أن الـ Pods تعمل بالإصدار السابق:

kubectl get pods -n api-production -o jsonpath='{.items[*].spec.containers[0].image}'

## Verification (التحقق)
كيف تؤكد أن المشكلة حُلّت؟
- استخدام CPU تحت 80% لمدة 10 دقائق
- وقت استجابة API p99 تحت 500ms
- لا تنبيهات خطأ جديدة

## Rollback (التراجع)
إذا جعلت الخطوات أعلاه الأمور أسوأ:
1. ارجع عن تغيير التوسيع
2. صعّد لفريق هندسة المنصة
3. استدعِ قائد SRE المناوب

## Contacts (جهات الاتصال)
- Slack فريق المنصة: #platform-engineering
- SRE المناوب: تحقق من جدول PagerDuty
- التصعيد: @sre-lead في Slack

نصائح لكتابة كتيب التشغيل

النصيحة	لماذا مهمة
استخدم أوامر دقيقة — جاهزة للنسخ واللصق	في الساعة 3 صباحاً، لا أحد يريد اكتشاف بناء الجملة
ضمّن المخرجات المتوقعة لكل خطوة	حتى يعرف القارئ إذا نجحت الخطوة
أضف خطوات تحقق	حتى يتأكد القارئ من الإصلاح
ضمّن خطة تراجع	في حال جعل الإصلاح الأمور أسوأ
حدّثه باستمرار	كتيب تشغيل قديم أسوأ من عدم وجود كتيب
استخدم لغة أمرية	"Run this command" وليس "You might want to try..."

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

التحليل البعدي (postmortem، يُسمى أيضاً incident review) يوثق ما حدث ولماذا وكيف نمنعه من الحدوث مرة أخرى. المبدأ الأساسي هو بدون لوم: ركز على الأنظمة، ليس الأشخاص.

قالب التحليل البعدي

# Postmortem: [عنوان الحادث]

**Date:** [تاريخ الحادث]
**Duration:** [إجمالي وقت التأثير]
**Severity:** [SEV1/SEV2/SEV3]
**Authors:** [الأسماء]
**Status:** [Draft / In Review / Final]

## Summary (الملخص)
ملخص من 2-3 جمل للحادث.

> في [التاريخ]، واجه [الخدمة] [التأثير] لمدة [المدة].
> السبب الجذري كان [سبب مختصر]. تأثر [العدد] مستخدم،
> مما أدى إلى [التأثير التجاري].

## Timeline (الجدول الزمني — جميع الأوقات بـ UTC)

| الوقت | الحدث |
|-------|-------|
| 14:00 | نشر الإصدار v2.3.1 للإنتاج |
| 14:15 | التنبيه يُفعّل: "High error rate on payment service" |
| 14:17 | مهندس المناوبة يُقر بالتنبيه |
| 14:20 | إعلان الحادث كـ SEV2 |
| 14:25 | فتح غرفة الحرب في #incident-20260214 |
| 14:35 | تحديد السبب الجذري: استنفاد مجمع الاتصالات |
| 14:40 | نشر الإصلاح: زيادة حجم مجمع الاتصالات |
| 14:50 | معدل الأخطاء يعود للطبيعي |
| 15:00 | حل الحادث |

## Impact (التأثير)
- **المستخدمون المتأثرون:** ~5,000 (12% من المستخدمين النشطين)
- **التأثير على الإيرادات:** تقديرياً $15,000 في معاملات فاشلة
- **مدة التأثير:** 35 دقيقة
- **الخدمات المتأثرة:** خدمة الدفع، مسار الدفع

## Root Cause (السبب الجذري)
نشر الإصدار v2.3.1 قدّم استعلام قاعدة بيانات جديد يفتح
اتصالات إضافية. لم يُزد حد مجمع الاتصالات (50) لاستيعاب
نمط الاستعلام الجديد. عندما زادت الحركة بعد 14:00، استُنفد
المجمع، مسبباً فشل الطلبات الجديدة بأخطاء انتهاء المهلة.

## Action Items (بنود الإجراءات)

| الإجراء | المالك | الأولوية | الموعد |
|---------|--------|---------|-------|
| إضافة مراقبة مجمع الاتصالات للوحة قاعدة البيانات | سارة | عالية | 1 مارس |
| إضافة تنبيه لمجمع الاتصالات > 80% | أحمد | عالية | 1 مارس |
| جعل حجم مجمع الاتصالات قابلاً للتكوين | مايك | متوسطة | 15 مارس |
| تحديث كتيب قاعدة البيانات مع استكشاف مجمع الاتصالات | سارة | متوسطة | 8 مارس |

## Lessons Learned (الدروس المستفادة)
- استنفاد مجمع الاتصالات هو وضع فشل شائع لم نكن نراقبه
- الحدود المُرمّزة مصدر متكرر للحوادث — يجب جعل كل الحدود قابلة للتكوين
- بيئة اختبار الحمل تحتاج لتعكس أنماط حركة الإنتاج بشكل أفضل

إرشادات لغة التحليل البعدي

القسم	أسلوب اللغة	مثال
Summary (الملخص)	مختصر، واقعي، بدون مصطلحات	"The payment service was unavailable for 35 minutes."
Timeline (الجدول الزمني)	زمني، أوقات دقيقة	"14:17 — On-call engineer acknowledges the alert."
Root Cause (السبب الجذري)	تقني لكن واضح	"The connection pool was exhausted because..."
Action Items (بنود الإجراءات)	محددة، مع مالك وموعد	"Add monitoring — Owner: Sarah — Due: March 1"
Lessons Learned (الدروس المستفادة)	تطلعية، نظامية	"We need to monitor all resource limits, not just CPU and memory."

كتابة توثيق وحدات Terraform

كل وحدة Terraform يجب أن يكون لها README يساعد المهندسين الآخرين في استخدامها بشكل صحيح.

قالب README لوحدة Terraform

# terraform-aws-api-gateway

ينشئ API Gateway مع تكامل Lambda ونطاق مخصص وتسجيل CloudWatch.

## Usage (الاستخدام)

```hcl
module "api" {
  source = "git::https://github.com/org/terraform-aws-api-gateway.git?ref=v1.2.0"

  name        = "my-api"
  environment = "production"
  domain_name = "api.example.com"

  routes = {
    "GET /users"    = module.users_lambda.function_arn
    "POST /orders"  = module.orders_lambda.function_arn
  }
}

Inputs (المدخلات)

الاسم	الوصف	النوع	الافتراضي	مطلوب
name	اسم API Gateway	string	—	نعم
environment	اسم البيئة (dev, staging, production)	string	—	نعم
domain_name	النطاق المخصص لـ API	string	null	لا
routes	خريطة مسارات إلى Lambda ARNs	map(string)	{}	لا

Outputs (المخرجات)

الاسم	الوصف
api_id	معرف API Gateway
api_endpoint	عنوان URL لـ API Gateway
api_arn	ARN الخاص بـ API Gateway

### نصائح لتوثيق Terraform

- **ضمّن دائماً مثال استخدام** — المهندسون يريدون النسخ واللصق والتعديل
- **وثّق كل متغير** — حتى لو كان الاسم يبدو واضحاً
- **أظهر القيم الافتراضية** — حتى يعرف المهندسون ما يجب تجاوزه
- **حدد قيود الإصدار** — للوحدة نفسها والمزودين
- **أبقِ الأمثلة محدثة** — الأمثلة المعطلة تسبب الإحباط

## كتابة وثائق نشر Kubernetes

وثّق عمليات نشر Kubernetes حتى يتمكن أي شخص من فهمها وتشغيلها:

```markdown
# Order Service — Kubernetes Deployment

## Overview (نظرة عامة)
خدمة الطلبات تعالج طلبات العملاء وتتواصل مع خدمات الدفع والمخزون.

## Deployment (النشر)
```bash
# النشر باستخدام Helm
helm upgrade --install order-service ./charts/order-service \
  --namespace order-production \
  --values values-production.yaml

Health Checks (فحوصات الصحة)

• Liveness: GET /healthz (يتحقق أن التطبيق يعمل)
• Readiness: GET /readyz (يتحقق أن التبعيات متاحة)

Monitoring (المراقبة)

• لوحة المعلومات: Grafana > Order Service
• التنبيهات: PagerDuty > Order Platform
• السجلات: kubectl logs -l app=order-service -n order-production

## كتابة دفاتر المناوبة

دفتر المناوبة (On-Call Playbook) يعطي مهندسي المناوبة الجدد كل ما يحتاجونه للنجاة من مناوبتهم:

```markdown
# On-Call Playbook — فريق المنصة

## Getting Started (البداية)
1. تحقق من وصولك إلى PagerDuty
2. ثبّت تطبيق PagerDuty على الهاتف
3. تحقق من وصولك إلى مجموعة Kubernetes الإنتاجية
4. احفظ لوحة Grafana: [الرابط]

## Alert Response Guide (دليل الاستجابة للتنبيهات)

| التنبيه | الشدة | الخطوة الأولى |
|---------|-------|-------------|
| CPU عالي على خوادم API | SEV2 | [رابط كتيب التشغيل] |
| تأخر نسخ قاعدة البيانات | SEV2 | [رابط كتيب التشغيل] |
| شهادة تنتهي قريباً | SEV3 | [رابط كتيب التشغيل] |
| مساحة القرص > 90% | SEV3 | [رابط كتيب التشغيل] |

## Escalation Path (مسار التصعيد)
1. حاول الحل باستخدام كتيب التشغيل (15 دقيقة)
2. إذا لم يُحل، استدعِ المناوب الثانوي
3. إذا كان SEV1، استدعِ مدير الهندسة
4. إذا كان يؤثر على العملاء، أبلغ #customer-support

كتابة توثيق طلبات التغيير

التغييرات الكبيرة في البنية التحتية يجب توثيقها في طلب تغيير:

# Change Request: ترحيل Redis إلى ElastiCache

## Summary (الملخص)
ترحيل Redis المُدار ذاتياً على EC2 إلى AWS ElastiCache
لتحسين الموثوقية وتقليل العبء التشغيلي.

## Risk Assessment (تقييم المخاطر)
- **مستوى المخاطر:** متوسط
- **خطة التراجع:** تبديل DNS للعودة إلى Redis على EC2 (< 5 دقائق)
- **ترحيل البيانات:** باستخدام نسخ Redis، بدون توقف

## Approval (الموافقة)
- [ ] مدير الهندسة
- [ ] مراجعة أمنية
- [ ] قائد SRE

التوثيق الجيد ليس مجرد كتابة — إنه عمل تعاطفي مع نفسك المستقبلية وزملائك. اكتب التوثيق الذي تتمنى لو كان لديك عندما استُدعيت في الساعة 3 صباحاً.

تهانينا على إكمال هذه الدورة! أكمل الاختبار لكسب رصيدك.

:::