Troubleshooting Playbook

الهدف من الدرس

ستتعلم playbook ثابت للتشخيص: من kubectl get إلى describe و logs و events و exec، مع أشجار قرار لأكثر المشاكل شيوعا.

الفكرة ببساطة

لا تبدأ التخمين من YAML. ابدأ من الحالة الحالية: ما status؟ ما events؟ ما logs؟ ما endpoints؟ ثم ارجع إلى manifest.

Playbook عام

flowchart TD
  A[المشكلة] --> B[kubectl get]
  B --> C[kubectl describe]
  C --> D[kubectl logs]
  D --> E[kubectl events]
  E --> F[kubectl exec أو port-forward]
  F --> G[تعديل manifest]

أوامر لا غنى عنها

kubectl get pods -A -o wide
kubectl describe pod <pod-name>
kubectl logs <pod-name> --previous
kubectl events --sort-by=.metadata.creationTimestamp
kubectl get deploy,rs,pods,svc,endpoints,ingress
kubectl auth can-i get pods
kubectl top pods
kubectl explain deployment.spec.template.spec.containers

شجرة قرار: Pod لا يعمل

flowchart TD
  A[Pod ليس Running] --> B{STATUS}
  B -->|Pending| C[افحص scheduling و resources و PVC]
  B -->|ImagePullBackOff| D[افحص image و registry و credentials]
  B -->|CrashLoopBackOff| E[logs --previous + command + config]
  B -->|Running not Ready| F[readinessProbe + app health]
  B -->|ContainerCreating| G[volume mount + runtime events]

شجرة قرار: Service لا يعمل

flowchart TD
  A[لا يوجد response] --> B{هل Service موجود؟}
  B -->|لا| C[أنشئ Service]
  B -->|نعم| D{هل Endpoints موجودة؟}
  D -->|لا| E[labels/selector/readiness]
  D -->|نعم| F{هل port صحيح؟}
  F -->|لا| G[port/targetPort]
  F -->|نعم| H[NetworkPolicy أو التطبيق]

أمثلة مشاكل وحلول

العرض	أول أمر	ما تبحث عنه
`CrashLoopBackOff`	`kubectl logs pod --previous`	stack trace أو config ناقص
`ImagePullBackOff`	`kubectl describe pod`	اسم image، tag، secret، rate limit
`Pending`	`kubectl describe pod`	insufficient cpu/memory، taints، PVC Pending
Service لا يرد	`kubectl get endpoints svc`	هل هناك endpoints؟
Ingress 503	`kubectl get endpoints`	Service بدون Pods جاهزة
Forbidden	`kubectl auth can-i`	RBAC ناقص

سيناريو عملي: Service selector خطأ

broken.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: broken-web
spec:
  replicas: 1
  selector:
    matchLabels:
      app: broken-web
  template:
    metadata:
      labels:
        app: broken-web
    spec:
      containers:
        - name: nginx
          image: nginx:1.27
          ports:
            - name: http
              containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
  name: broken-web
spec:
  selector:
    app: wrong-label
  ports:
    - name: http
      port: 80
      targetPort: http

التشخيص:

kubectl apply -f broken.yaml
kubectl get endpoints broken-web
kubectl get pods --show-labels
kubectl describe svc broken-web

Expected output:

NAME         ENDPOINTS   AGE
broken-web   <none>      20s

الحل: اجعل selector في Service يساوي app: broken-web.

قواعد مهمة أثناء الحوادث

وثق الوقت والأوامر والنتيجة.
لا تعدل أكثر من سبب واحد في نفس اللحظة.
اقرأ events قبل حذف الموارد.
استخدم kubectl diff قبل تطبيق أي إصلاح.
لو المشكلة production، فضل rollback واضح على debugging طويل أمام المستخدمين.

Lab: إصلاح Service لا يملك Endpoints

المستوى: مبتدئ الوقت: 35 دقيقة الأدوات: kubectl

الهدف: تشخيص Service مكسور بسبب selector خاطئ وإصلاحه بخطوات واضحة.

Prerequisites

Cluster محلي.

Steps

احفظ الملف السابق باسم broken.yaml.
طبقه:

kubectl apply -f broken.yaml

افحص Service:

kubectl get svc broken-web
kubectl get endpoints broken-web

افحص labels:

kubectl get pods --show-labels

عدل selector.app في Service إلى broken-web، ثم طبق الملف:

kubectl apply -f broken.yaml
kubectl get endpoints broken-web

Expected output

NAME         ENDPOINTS        AGE
broken-web   10.244.0.8:80    2m

Cleanup

kubectl delete -f broken.yaml

الربط بالمشروع النهائي

Capstone يتطلب runbook. هذا الدرس هو قالب runbook: أعراض، أوامر فحص، expected output، قرار rollback، وتنظيف.