{"id":"l-dk-5-4","courseId":"docker-kubernetes","lang":"ar","kind":"lesson","summary":"وجّه حركة HTTPS العامة إلى notes-api باستخدام Gateway API، وحصّن الـ Pods الخاصة به بـ securityContext، وشخّص الـ Pods المعطوبة بسرعة بالأوامر get وdescribe وlogs وevents وkubectl debug.","html":"

شيئان يقفان بين notes-api والمستخدمين الحقيقيين. لا يمكن الوصول إليه من الإنترنت بعد، وحين ينكسر شيء في الثالثة فجرًا، تحتاج إلى معرفة ما هو خلال دقائق. هذا الدرس يغطّي الأمرين، وينتهي بإعدادات الأمان التي تكمل صورة الإنتاج.

\n

إدخال حركة HTTP

\n

‏Service من نوع LoadBalancer لكل تطبيق يصلح لخدمة واحدة. أما مع عشر خدمات، فأنت تدفع ثمن عشرة موازنات أحمال، وتدير عشر شهادات، والتوجيه حسب اسم المضيف أو المسار مستحيل. ما تريده نقطة دخول واحدة مشتركة توجّه طلبات HTTP إلى الـ Service الصحيح.

\n

لسنوات كانت الإجابة Ingress. ما زال يعمل، لكن واجهة Ingress البرمجية مجمَّدة ولا تحصل على ميزات جديدة، والـ controller المجتمعي الواسع الانتشار ingress-nginx تقاعد في مارس 2026: لا إصدارات جديدة ولا إصلاحات أمنية. مشروع Kubernetes يوجّه العمل الجديد نحو Gateway API، المتاح رسميًا (GA) بالإصدار gateway.networking.k8s.io/v1. يُثبَّت كإضافة (الـ CRDs الخاصة به مع أداة تنفيذ (implementation)، مثل controller موازن الأحمال في منصّتك السحابية، أو Envoy Gateway، أو Cilium، أو Istio)، وكثير من الـ clusters المُدارة توفّره جاهزًا.

\n

يقسّم Gateway API المهمّة حسب الأدوار:

\n\n
\n مشغّل الـ cluster يختار الـ GatewayClass. الـ Gateway المسمّى public في الـ namespace ‏infra ينهي TLS على المنفذ 443. الـ HTTPRoute ‏notes-api في الـ namespace ‏notes يرتبط به ويرسل طلبات notes.skylane.example إلى الـ Service ‏notes-api، الذي يحوّلها إلى الـ Pods.\n \n GatewayClass\n مشغّل الـ cluster\n \n Gateway :443\n فريق المنصّة\n \n HTTPRoute\n فريق notes\n \n Service\n \n Pods\n \n \n \n \n notes.skylane.example → notes-api:80\n
كل فريق يملك طبقته، والـ routes ترتبط بـ Gateway مشترك
\n

الـ Gateway الخاص بفريق المنصّة، مرة واحدة لكل cluster:

\n
infra/gateway.yaml
apiVersion: gateway.networking.k8s.io/v1\nkind: Gateway\nmetadata:\n  name: public\n  namespace: infra\nspec:\n  gatewayClassName: skylane-lb        # provided by your implementation\n  listeners:\n    - name: https\n      protocol: HTTPS\n      port: 443\n      hostname: \"*.skylane.example\"\n      tls:\n        mode: Terminate\n        certificateRefs:\n          - name: skylane-wildcard-tls\n      allowedRoutes:\n        namespaces:\n          from: All
\n

والـ route الخاص بك، في الـ namespace ‏notes:

\n
k8s/httproute.yaml
apiVersion: gateway.networking.k8s.io/v1\nkind: HTTPRoute\nmetadata:\n  name: notes-api\n  namespace: notes\nspec:\n  parentRefs:\n    - name: public\n      namespace: infra\n  hostnames:\n    - notes.skylane.example\n  rules:\n    - matches:\n        - path:\n            type: PathPrefix\n            value: /\n      backendRefs:\n        - name: notes-api\n          port: 80
\n

الأمر kubectl describe httproute notes-api يُظهر تحت Status هل قبل الـ Gateway هذا الـ route. وإذا كنت تنقل كائنات Ingress موجودة، فالأداة ingress2gateway تحوّلها، بما في ذلك كثير من annotations الخاصة بـ ingress-nginx.

\n

دليل التشخيص

\n

حين يسيء notes-api التصرّف، قاوم التخمين. اتّبع الترتيب نفسه في كل مرة، ودع كل خطوة تختار التالية:

\n
Terminal
kubectl get pods -l app.kubernetes.io/name=notes-api\nkubectl describe pod <pod>\nkubectl logs <pod> --previous\nkubectl events --for pod/<pod> --types=Warning
\n

العمود STATUS يخبرك أين تنظر:

\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
الحالةماذا تعنيأين تنظر
Pendingلا يوجد node يستطيع استقبال الـ Pod‏describe: أحداث مثل Insufficient cpu أو node selectors غير مطابقة
ImagePullBackOffلا يستطيع الـ kubelet سحب الـ image‏describe: ‏tag خاطئ، أو بيانات اعتماد سحب مفقودة، أو معمارية خاطئة
CreateContainerConfigErrorمفتاح ConfigMap أو Secret مُشار إليه مفقود‏describe يسمّي المفتاح
CrashLoopBackOffالتطبيق يبدأ ويخرج، مرارًا‏logs --previous، مع رمز الخروج في describe ‏(137 = نفاد ذاكرة أو قتل)
Running مع 0/1 جاهزالـ readiness probe يفشل‏describe يُظهر إخفاقات الـ probe؛ تحقّق مما يعتمد عليه /readyz

إذا كانت الـ Pods سليمة لكن الطلبات تفشل، فاعمل من الداخل إلى الخارج: ‏kubectl get endpointslices -l kubernetes.io/service-name=notes-api (الفراغ يعني مشكلة في الـ selector أو الجاهزية)، ثم حالة الـ route، ثم الـ Gateway.

\n

الـ images من نوع distroless لا تحتوي على shell، فلا يفيد kubectl exec. ألحِق ephemeral debug container (container تشخيص مؤقتًا) بدلًا من ذلك. ينضمّ إلى الـ network namespace الخاصة بالـ Pod، ومع --target يستطيع رؤية عمليات التطبيق أيضًا:

\n
Terminal
kubectl debug -it <pod> --image=busybox:1.37 --target=api\n# inside: nslookup notes-db, wget -qO- localhost:3000/readyz, ps
\n\n

القطعة الأخيرة: الـ securityContext

\n

في الدرس 2.2 شغّلت الـ image كمستخدم غير root ووعدت بفرض ذلك في الـ cluster. ها هو ذا، على container ‏notes-api:

\n
k8s/deployment.yaml
          securityContext:\n            runAsNonRoot: true\n            allowPrivilegeEscalation: false\n            readOnlyRootFilesystem: true\n            capabilities:\n              drop: [\"ALL\"]
\n

الحقل runAsNonRoot يجعل الـ kubelet يرفض بدء الـ container إذا كانت الـ image ستعمل بـ UID 0. إنه يفحص UID رقميًا، لذا فإن image يكون فيها USER اسمًا مثل node تفشل بـ CreateContainerConfigError؛ اكتب USER 1000 في الـ Dockerfile أو أضف runAsUser: 1000 هنا. وأعطِ التطبيق volume من نوع emptyDir في /tmp إن احتاج إلى مساحة مؤقتة تحت نظام ملفات جذري للقراءة فقط.

\n

بهذا يكتمل مسار notes-api: بناء multi-stage يستفيد من الـ cache، وimage صغيرة بمستخدم غير root مثبّتة بالـ digest ومفحوصة، وبيئة Compose للتطوير، وDeployment مع probes وموارد وتوسّع تلقائي وrollouts آمنة وroute عبر Gateway وsecurity context محصّن. كل واحد من هذه الإعدادات موجود في الملف لأن حادثًا ما علّم أحدهم أنه ضروري. حافظ على هذه العادة: حين ينكسر شيء، اسأل أي إعداد كان سيجعله مستحيلًا، وأضِفه.

\n","toc":[{"id":"sec-1","text":"إدخال حركة HTTP","level":2},{"id":"sec-2","text":"دليل التشخيص","level":2},{"id":"sec-3","text":"القطعة الأخيرة: الـ securityContext","level":2}],"takeaways":["يقسّم Gateway API الحركة الخارجية إلى GatewayClass (أداة التنفيذ)، وGateway (نقطة الدخول وTLS)، وHTTPRoute (قواعد التوجيه لتطبيق ما)، فيملك كلٌّ من فريق المنصّة وفريق التطبيق جزأه.","الـ Ingress ما زال يعمل لكنه مجمَّد، والـ controller المجتمعي ingress-nginx تقاعد في مارس 2026؛ والإعدادات الجديدة يجب أن تستخدم Gateway API.","اقرأ حالة الـ Pod أولًا، ثم kubectl describe للأحداث، ثم kubectl logs --previous للانهيارات؛ فالحالة تخبرك بالأداة التي تلجأ إليها.","الأمر kubectl debug --target يُلحق container مؤقتًا فيه أدوات بـ Pod يعمل، وهكذا تفحص الـ images من نوع distroless.","‏Pod الإنتاج يعمل كمستخدم غير root، دون تصعيد للصلاحيات، مع نظام ملفات جذري للقراءة فقط، وبعد إسقاط كل الـ capabilities."],"further":[{"title":"Gateway API","url":"https://kubernetes.io/docs/concepts/services-networking/gateway/"},{"title":"Debug Running Pods","url":"https://kubernetes.io/docs/tasks/debug/debug-application/debug-running-pod/"},{"title":"Configure a Security Context for a Pod or Container","url":"https://kubernetes.io/docs/tasks/configure-pod-container/security-context/"},{"title":"Ingress NGINX Retirement","url":"https://kubernetes.io/blog/2025/11/11/ingress-nginx-retirement/"}],"quiz":[{"q":"

يشغّل فريق المنصّة لديكم Gateway مشتركًا في الـ namespace ‏infra. ماذا تنشئ أنت، بصفتك فريق notes-api، لعرض notes.skylane.example؟

","options":[{"text":"‏GatewayClass جديدًا لـ notes-api.","why":"الـ GatewayClasses تصف أداة تنفيذ (implementation)، ويضبطها فريق المنصّة عادةً مرة واحدة لكل cluster."},{"text":"‏HTTPRoute في الـ namespace ‏notes يشير إلى الـ Gateway المشترك في parentRefs وإلى الـ Service ‏notes-api في backendRefs.","why":"صحيح. الـ Routes تخصّ فرق التطبيقات؛ والـ Gateway يقرّر (عبر allowedRoutes) أي namespaces يمكنها الارتباط به."},{"text":"‏Gateway ثانيًا يستمع على المنفذ 443.","why":"هذا يكرّر نقطة الدخول الخاصة بالمنصّة وإعداد TLS فيها. اربط route بالـ Gateway الموجود."},{"text":"‏Service من نوع LoadBalancer لـ notes-api.","why":"هذا يتجاوز نقطة الدخول المشتركة ويعطيك عنوانًا عامًا منفصلًا عليك إدارته."}],"answer":1},{"q":"

‏Pod يُظهر الحالة ImagePullBackOff. ما الخطوة التالية الأكثر فائدة؟

","options":[{"text":"kubectl logs <pod>","why":"الـ container لم يبدأ أصلًا، فلا توجد سجلات لقراءتها."},{"text":"kubectl rollout restart deployment/notes-api","why":"الـ Pods الجديدة ستفشل في سحب الـ image نفسها بالطريقة نفسها."},{"text":"kubectl debug -it <pod> --image=busybox:1.37","why":"لا يوجد container يعمل لتلتحق به، والمشكلة في السحب، لا في تشغيل الـ Pod."},{"text":"الأمر kubectl describe pod <pod> ثم قراءة خطأ السحب في الأحداث، كـ tag خاطئ، أو بيانات اعتماد registry مفقودة، أو عدم وجود image لهذه المعمارية.","why":"صحيح. الأحداث تذكر بالضبط لماذا لم يستطع الـ kubelet السحب."}],"answer":3},{"q":"

‏notes-api في حالة CrashLoopBackOff. والأمر kubectl logs <pod> لا يعرض إلا سطرًا أو اثنين من مخرجات البدء. ماذا تشغّل؟

","options":[{"text":"‏kubectl logs <pod> --previous، لقراءة مخرجات نسخة الـ container التي انهارت.","why":"صحيح. النسخة الحالية ربما بدأت للتوّ. أما --previous فيعرض مخرجات النسخة السابقة، بما فيها الخطأ الذي قتلها."},{"text":"‏kubectl delete pod <pod>، حتى يبدأ من جديد.","why":"البديل يشغّل الـ image نفسها بالإعدادات نفسها وينهار بالطريقة نفسها، وتكون قد أضعت الأدلّة."},{"text":"kubectl scale deployment/notes-api --replicas=0","why":"هذا يوقف حلقة الانهيار بإيقاف الخدمة، دون أن يخبرك بأي شيء."},{"text":"kubectl get nodes","why":"صحة الـ nodes نادرًا ما تسبّب حلقة انهيار في تطبيق واحد؛ مخرجات التطبيق نفسه هي نقطة البداية."}],"answer":0},{"q":"

الـ image الخاصة بـ notes-api من نوع distroless، فيفشل kubectl exec -it <pod> -- sh. كيف تتحقّق من تحليل DNS من داخل الـ Pod؟

","options":[{"text":"أعِد بناء الـ image مع shell، وانشرها، ثم حاول مجددًا.","why":"هذا يغيّر الشيء الذي تشخّصه ويستغرق دورة إصدار كاملة."},{"text":"استخدم kubectl port-forward وشغّل nslookup على حاسوبك.","why":"هذا يحلّ الأسماء بـ DNS حاسوبك، لا بـ DNS الـ Pod."},{"text":"‏kubectl debug -it <pod> --image=busybox:1.37 --target=api، ثم شغّل nslookup notes-db داخل container التشخيص.","why":"صحيح. الـ ephemeral container يتشارك الـ network namespace الخاصة بالـ Pod (ومع --target يرى عملياته أيضًا)، ويجلب الأدوات التي تفتقر إليها الـ image."},{"text":"اقرأ /etc/resolv.conf بـ kubectl logs.","why":"السجلات تعرض ما طبعته العملية، لا الملفات داخل الـ container."}],"answer":2}],"exercise":{"kind":"choice","multiple":true,"options":["crash-logs","pending-describe","pull-logs","notready-probe","crash-delete"],"correct":["crash-logs","pending-describe","notready-probe"],"title":"الخطوة الأولى لكل عَرَض","prompt":"

أنت في المناوبة على notes-api. لكل عَرَض أدناه، يقترح زميلك خطوة أولى. اختر كل ربط تكون فيه الخطوة الأولى صحيحة.

\n","hints":["اسأل عن كل واحد: هل عمل container فعلًا حتى الآن؟ إن لم يعمل، فلا سجلات له.","أي الخطوات تجمع الأدلّة، وأيها يدمّرها؟","ثلاثة من الروابط صحيحة."],"explanation":"

حلقة الانهيار تترك خطأها في مخرجات الـ container السابق، لذا يأتي logs --previous أولًا. والـ Pod العالق في Pending لم يُجدوَل أصلًا؛ وdescribe يُظهر سبب الـ scheduler. والـ Pod الذي يعمل لكنه غير جاهز يفشل في الـ readiness probe؛ وdescribe يُظهر الإخفاقات، و/readyz يخبرك بالاعتمادية المتعطّلة. أما فشل سحب الـ image فلا سجلات له لأن أي container لم يعمل؛ اقرأ خطأ السحب في describe. وحذف Pod ينهار يُضيّع سجلاته وأحداثه، والبديل ينهار بالطريقة نفسها.

\n","checkLabels":{},"optionText":{"crash-logs":{"text":"CrashLoopBackOff ← kubectl logs <pod> --previous","why":"صحيح. مخرجات النسخة المنهارة تحتوي عادةً على الخطأ الذي قتلها."},"pending-describe":{"text":"Pending لخمس دقائق ← kubectl describe pod <pod> وقراءة أحداث الجدولة","why":"صحيح. أحداث مثل Insufficient memory أو node selector غير مطابق تشرح لماذا لم يقبله أي node."},"pull-logs":{"text":"ImagePullBackOff ← kubectl logs <pod>","why":"الـ container لم يبدأ أبدًا، فلا توجد سجلات. ‏describe يُظهر خطأ السحب."},"notready-probe":{"text":"Running لكن 0/1 جاهز ← kubectl describe pod <pod> لرؤية إخفاقات الـ probe، ثم التحقّق مما يعتمد عليه /readyz","why":"صحيح. إخفاقات الـ readiness تُسجَّل كأحداث، واعتماديات ذلك الـ endpoint هي السبب عادةً."},"crash-delete":{"text":"CrashLoopBackOff ← kubectl delete pod <pod> حتى يُعاد تشغيله نظيفًا","why":"البديل يشغّل الـ image والإعدادات نفسها وينهار بالطريقة نفسها، وتذهب أدلّة الـ Pod القديم."}}},"words":651,"readMinutes":4}