> ## Content Index
> Fetch the complete content index at: https://arabroot.io/llms.txt
> Use this file to discover other available public pages before exploring further.

# نقل تطبيق Docker Compose إلى Kubernetes خطوة بخطوة
- URL: https://arabroot.io/articles/نقل-تطبيق-docker-compose-الى-kubernetes/
- Published: 2026-11-18T19:44:28.000Z
- Updated: 2026-11-18T20:42:43.000Z
- Description: ننقل تطبيقاً من أربع خدمات من Docker Compose إلى Kubernetes، ونرى ما أخطأ فيه kompose وما تعلمناه من كل عطل حتى عمل التطبيق.
- Author: فريق عرب رووت
- Tags: الأدلة التقنية, الحاويات Containers وتنسيقها مع Kubernetes, DevOps وCI/CD, Docker والحاويات, الاستضافة الذاتية

لنفرض أن لديك تطبيقاً من أربع خدمات Services يعمل منذ شهور بملف Docker Compose واحد: واجهة أمامية Frontend خلف nginx، وواجهة برمجية API صغيرة، وقاعدة بيانات Database من نوع PostgreSQL، وذاكرة مؤقتة Cache من نوع Redis. ثم قرر الفريق أن ينتقل إلى Kubernetes، لأن السيرفر Server الواحد لم يعد يكفي أو لأن باقي تطبيقات الشركة هناك. والطريق الذي يبدو أقصر هو أداة تحويل Conversion Tool تأخذ الملف وتخرج ملفات YAML، فتطبقها ب `kubectl apply` وتنتهي. ولكن ملف Compose الجيد فيه قرارات كثيرة لا تظهر في سطر واحد: من ينتظر من، ومتى تعتبر الخدمة جاهزة، وأين كلمة المرور Password، ومن يستطيع الوصول إلى قاعدة البيانات، وأغلب هذه القرارات تضيع في التحويل، أو تتحول إلى شيء يشبهها ويتصرف بشكل مختلف.

وفي [أفضل الممارسات في ملفات Docker Compose](https://arabroot.io/articles/%D8%A7%D9%81%D8%B6%D9%84-%D8%A7%D9%84%D9%85%D9%85%D8%A7%D8%B1%D8%B3%D8%A7%D8%AA-%D9%81%D9%8A-%D9%85%D9%84%D9%81%D8%A7%D8%AA-docker-compose/) بنينا هذا التطبيق نفسه بملف يحل كل مشكلة واجهناها: ترتيب البدء Startup Order بفحوص الصحة Health Checks، ومهمة الترحيل Migration التي تعمل مرة واحدة، والأسرار Secrets في ملفات، والشبكة الداخلية Internal Network، وحدود الذاكرة Memory Limits. وفي هذا المقال نأخذ الملف نفسه وملفات التطبيق نفسها دون أن نغير فيها حرفاً، وننقلها إلى عنقود Cluster على Kubernetes من ثلاث عقد Nodes بنيناه بأداة kind في مقال Kubernetes من الداخل، ونستخدم الأوامر التي شرحناها في مقال kubectl للمبتدئين. نبدأ بتجربة أداة kompose ونرى ماذا تنتج وأين فشلت، ثم نكتب الملفات بأيدينا خدمة خدمة، ونتعلم من الأعطال التي ظهرت في الطريق، وكلها حقيقية من التجربة.

وسوف نناقش في هذا المقال ما يلي:

- ما يقابل كل جزء من ملف Compose في Kubernetes، وما لا يقابله شيء.
- تجربة الأداة kompose على الملف، والأخطاء السبعة التي ظهرت عندما طبقنا ما أنتجته.
- الإعدادات Configuration في ConfigMap، والسر Secret كملف، ولماذا منع ال Secret على المسار `/run/secrets` كل Pods التطبيق من البدء.
- قاعدة البيانات مع قرص دائم PersistentVolumeClaim، وتحويل فحص الصحة إلى ثلاثة فحوص Probes، وكيف قتل فحص البدء قاعدة البيانات مرتين.
- الترحيل في حاوية تمهيدية Init Container بدل `depends_on`، وحدود الذاكرة، وعزل الشبكة بسياسة NetworkPolicy.
- التطبيق النهائي يعمل، ثم نوقف قاعدة البيانات ونرى ماذا يحدث للتطبيق.

## ما الذي يقابل كل جزء من Compose في Kubernetes؟

قبل أي أداة لنضع الخريطة، فهي التي سنرجع إليها في كل قسم. والفكرة الأهم فيها أن الخدمة الواحدة في Compose تصبح أكثر من كائن Object في Kubernetes، لأن Compose يجمع في كلمة `services` أشياء يفصلها Kubernetes: الجزء الذي يشغل ال Containers وهو ال Deployment، والاسم الذي يصل به الآخرون إليها وهو ال Service، وكلاهما شرحناه في [مصطلحات Kubernetes بالرسم](https://arabroot.io/articles/%D9%85%D8%B5%D8%B7%D9%84%D8%AD%D8%A7%D8%AA-kubernetes-%D8%A8%D8%A7%D9%84%D8%B1%D8%B3%D9%85/):

![عمودان: في Compose السطر services.api يقابله Deployment مع Service بالاسم api، وports يقابله Service ثم port-forward أو Ingress، وenv_file يقابله ConfigMap مع envFrom، وsecrets يقابله Secret مركب كملف للقراءة فقط، وvolumes يقابله PersistentVolumeClaim، وhealthcheck مع start_period يقابله startupProbe وreadinessProbe وlivenessProbe، وdepends_on بالشرط service_completed_successfully يقابله initContainer يعاد حتى ينجح، وnetworks الداخلية تقابلها NetworkPolicy تحتاج CNI يطبقها](https://arabroot.io/content/images/2026/11/compose-to-k8s-01-mapping.webp)

كل جزء من ملف Compose له مكان، والصفان الأخيران لا يقابلهما شيء مباشر

وهذا الجدول يكمل الرسم بالأجزاء الأصغر التي ستحتاجها:

| في Compose                                       | في Kubernetes                     | الفرق المهم                                                                |
| ------------------------------------------------ | --------------------------------- | -------------------------------------------------------------------------- |
| image وbuild                                     | image فقط                         | العنقود لا يبني، وال Image يجب أن تكون في سجل Registry تصل إليه العقد      |
| restart: unless-stopped                          | restartPolicy: Always             | ال Deployment لا يقبل غيرها، ومهام المرة الواحدة تذهب إلى Job              |
| stop\_grace\_period: 10s                         | terminationGracePeriodSeconds: 10 | نفس المعنى: SIGTERM ثم الانتظار ثم SIGKILL                                 |
| deploy.resources.limits.memory مع memswap\_limit | resources.limits.memory           | ال kubelet لا يعطي Swap افتراضياً، فالحد حد فعلي                           |
| ${APP\_VERSION} من ملف .env                      | لا يوجد                           | لا توجد متغيرات Variables في YAML، والحل Kustomize أو Helm أو كتابة القيمة |
| logging بالمشغل Driver local                     | تدوير ال kubelet للسجلات          | الافتراضي 10 ميجابايت وخمسة ملفات لكل Container                            |
| profiles: \[tools\]                              | لا يوجد                           | الأداة psql تشغلها عند الحاجة ب kubectl exec أو kubectl run                |

## التجربة الأولى Lab: أداة kompose

الأداة [kompose](https://kompose.io/?ref=arabroot.io) مشروع رسمي من مشاريع Kubernetes يحول ملف Compose إلى ملفات YAML، والإصدار Version الذي جربناه 1.38.0\. ونسخنا مجلد Directory التطبيق من مقال Compose كما هو، ثم شغلناها عليه:

```bash
kompose version
kompose convert -f compose.yaml -o kompose-out/
```

```text
1.38.0 (a8f5d1cbd)
WARN Restart policy 'unless-stopped' in service redis is not supported, convert it to 'always'
WARN Restart policy 'unless-stopped' in service web is not supported, convert it to 'always'
WARN Restart policy 'unless-stopped' in service api is not supported, convert it to 'always'
WARN Restart policy 'unless-stopped' in service db is not supported, convert it to 'always'
WARN Service "api" won't be created because 'ports' is not specified
WARN Service "db" won't be created because 'ports' is not specified
WARN File don't exist or failed to check if the directory is empty: CreateFile :/var/lib/postgresql: The filename, directory name, or volume label syntax is incorrect.
WARN Service "migrate" won't be created because 'ports' is not specified
WARN Service "redis" won't be created because 'ports' is not specified
WARN File don't exist or failed to check if the directory is empty: CreateFile :/data: The filename, directory name, or volume label syntax is incorrect.
INFO Kubernetes file "..\\kompose-out\\web-service.yaml" created
INFO Kubernetes file "..\\kompose-out\\db-password-secret.yaml" created
INFO Kubernetes file "..\\kompose-out\\api-deployment.yaml" created
INFO Kubernetes file "..\\kompose-out\\api-env-configmap.yaml" created
INFO Kubernetes file "..\\kompose-out\\db-deployment.yaml" created
INFO Kubernetes file "..\\kompose-out\\pgdata-persistentvolumeclaim.yaml" created
INFO Kubernetes file "..\\kompose-out\\db-cm1-configmap.yaml" created
INFO Kubernetes file "..\\kompose-out\\migrate-pod.yaml" created
INFO Kubernetes file "..\\kompose-out\\redis-deployment.yaml" created
INFO Kubernetes file "..\\kompose-out\\redisdata-persistentvolumeclaim.yaml" created
INFO Kubernetes file "..\\kompose-out\\web-deployment.yaml" created
INFO Kubernetes file "..\\kompose-out\\web-cm0-configmap.yaml" created
INFO Kubernetes file "..\\kompose-out\\web-cm1-configmap.yaml" created 
```

ثلاثة عشر ملفاً في ثانية، والتحذيرات تقول أهم شيء قبل أن نطبق أي ملف: `Service "db" won't be created because 'ports' is not specified`. فملف Compose الجيد لا ينشر منفذ Port قاعدة البيانات ولا منفذ Redis ولا منفذ ال API، لأنها تصل إلى بعضها عبر الشبكة الداخلية بالاسم، كما شرحنا في [شبكات Docker](https://arabroot.io/articles/%D8%B4%D8%A8%D9%83%D8%A7%D8%AA-docker-%D9%88%D8%A3%D9%81%D8%B6%D9%84-%D8%A7%D9%84%D9%85%D9%85%D8%A7%D8%B1%D8%B3%D8%A7%D8%AA/#compose-networks). أما kompose فيقرأ غياب `ports` كأن الخدمة لا يصل إليها أحد، فلا ينشئ لها Service، أي أن الاسم `db` لن يوجد في العنقود. وطبقنا الملفات كما هي في Namespace منفصل لنرى النتيجة:

```bash
kubectl create namespace kompose
kubectl apply -n kompose -f kompose-out/
kubectl get pods,svc,pvc -n kompose
```

```text
NAME                         READY   STATUS              RESTARTS      AGE
pod/api-7b64bd5656-8b7lb     0/1     ImagePullBackOff    0             96s
pod/db-7dcd6ddc65-kkn42      0/1     ContainerCreating   0             95s
pod/migrate                  0/1     ImagePullBackOff    0             94s
pod/redis-7b4b5cd948-254bz   1/1     Running             0             93s
pod/web-647f69999f-nrd9z     0/1     CrashLoopBackOff    3 (19s ago)   92s

NAME          TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)    AGE
service/web   ClusterIP   10.96.165.173   <none>        8080/TCP   91s

NAME                              STATUS   VOLUME                                     CAPACITY   ACCESS MODES   STORAGECLASS   VOLUMEATTRIBUTESCLASS   AGE
persistentvolumeclaim/pgdata      Bound    pvc-82e02daa-4a3f-4b80-9f6c-4a2dcb02c40e   100Mi      RWO            standard       <unset>                 94s
persistentvolumeclaim/redisdata   Bound    pvc-e33f02b5-27bf-456e-99ab-7f2a85d519b7   100Mi      RWO            standard       <unset>                 93s
```

خدمة واحدة من خمس تعمل، وهي Redis التي لا تعتمد على أحد. ولنقرأ كل خطأ بالترتيب الذي شرحناه في مقال kubectl:

```bash
kubectl logs -n kompose deploy/web --tail=2
kubectl describe pod -n kompose migrate | grep -E 'Failed' | head -1
```

```text
2026/11/18 18:55:21 [emerg] 1#1: host not found in upstream "api" in /etc/nginx/conf.d/default.conf:4
nginx: [emerg] host not found in upstream "api" in /etc/nginx/conf.d/default.conf:4

  Warning  Failed     94s (x2 over 112s)  kubelet            spec.containers{migrate}: Failed to pull image "ct2-c-shop-api:1.0.0": failed to pull and unpack image "docker.io/library/ct2-c-shop-api:1.0.0": failed to resolve reference "docker.io/library/ct2-c-shop-api:1.0.0": pull access denied, repository does not exist or may require authorization: server message: insufficient_scope: authorization failed
```

الخطأ الأول نتيجة مباشرة لغياب ال Service: nginx يبحث عن الاسم `api` عند البدء فلا يجده فيتوقف، والخطأ الثاني أن ال Image التي بناها Compose على جهازنا بالأمر `build` لا توجد إلا في Docker على جهازنا، والعقد تحاول سحبها من Docker Hub. ولكي نرى ما بعد هذين الخطأين حملنا ال Image إلى العقد بالأمر `kind load docker-image`، وهو ما يقوم مقام السجل Registry في التجربة، وصححنا اسمها في ملفي ال API والترحيل فقط، ثم طبقناهما من جديد:

```bash
docker build -t k1-shop-api:1.0.0 ./api
kind load docker-image k1-shop-api:1.0.0 --name k1 --nodes k1-worker,k1-worker2
sed -i 's#image: ct2-c-shop-api:1.0.0#image: k1-shop-api:1.0.0#' kompose-out/api-deployment.yaml kompose-out/migrate-pod.yaml
kubectl apply -n kompose -f kompose-out/api-deployment.yaml -f kompose-out/migrate-pod.yaml
kubectl get pods -n kompose
kubectl describe pod -n kompose migrate | grep -A3 -E 'State:' | head -4
```

```text
NAME                     READY   STATUS              RESTARTS        AGE
api-57bb898db9-srkkg     0/1     RunContainerError   2 (6s ago)      48s
db-7dcd6ddc65-kkn42      0/1     CrashLoopBackOff    5 (2m40s ago)   10m
migrate                  0/1     StartError          0               48s
redis-7b4b5cd948-254bz   1/1     Running             0               10m
web-647f69999f-nrd9z     0/1     CrashLoopBackOff    6 (2m31s ago)   10m

    State:          Terminated
      Reason:       StartError
      Message:      failed to create containerd task: failed to create shim task: OCI runtime create failed: runc create failed: unable to start container process: error during container init: error mounting "/var/lib/kubelet/pods/ae9d6ad8-…/volumes/kubernetes.io~projected/kube-api-access-k5j8g" to rootfs at "/var/run/secrets/kubernetes.io/serviceaccount": create mountpoint for /var/run/secrets/kubernetes.io/serviceaccount mount: lookup mountpoint target: securejoin.OpenInRoot /var/run/secrets/kubernetes.io/serviceaccount: openat2 /var/run/secrets/kubernetes.io/serviceaccount: not a directory
```

والآن ال API وقاعدة البيانات والترحيل لا تبدأ أصلاً، والرسالة الطويلة تقول السبب في آخرها: `not a directory`. وعندما فتحنا ملف ال Deployment الذي أنتجه kompose وجدنا هذا الجزء:

```yaml
          volumeMounts:
            - mountPath: /run/secrets
              name: db-password
              subPath: db-password
```

فالسر في Compose كان ملفاً داخل المجلد `/run/secrets`، أما kompose فركب الملف نفسه بالخيار `subPath` على المسار `/run/secrets`، فأصبح `/run/secrets` ملفاً وليس مجلداً. وال kubelet يركب لكل Pod افتراضياً رمز الدخول Token إلى ال API Server في المجلد `/var/run/secrets/kubernetes.io/serviceaccount`، و`/var/run` في Alpine وأغلب التوزيعات Distributions اختصار Symlink إلى `/run`، فلم يجد runc مجلداً يضع فيه الرمز، فرفض تشغيل ال Container. وحتى لو بدأ فمتغير البيئة Environment Variable الذي كتبه kompose يقول `DB_PASSWORD_FILE=/run/secrets/db-password`، والملف غير موجود بهذا الاسم.

![عمودان، ما أنتجه kompose وما يلزم: لا يوجد Service ل api ولا db ولا redis ويلزم Service لكل خدمة يتصل بها غيرها، وnginx في web لا يجد الاسم api فيتوقف، وImage محلية ct2-c-shop-api تعطي ImagePullBackOff ويلزم سجل أو kind load، والسر مركب بال subPath على /run/secrets كملف ويلزم مجلد للقراءة فقط فيه الملف db_password، وhealthcheck أصبح livenessProbe فقط ويلزم startup وreadiness وliveness، وmigrate أصبح Pod عادياً لا ينتظر أحداً ويلزم initContainer أو Job، وكلمة المرور داخل YAML بترميز Base64 ويلزم Secret ينشأ من ملف خارج Git](https://arabroot.io/content/images/2026/11/compose-to-k8s-05-kompose.webp)

سبعة أخطاء ظهرت عندما طبقنا مخرج kompose كما هو، ولم تعمل إلا Redis

وفي الملفات التي أنتجها kompose أربع مشاكل أخرى لا تظهر كخطأ، ولكنها أخطر لأنها تعمل:

- **فحص الصحة أصبح livenessProbe فقط:** لا يوجد فحص جاهزية Readiness، فال Service يرسل الطلبات Requests إلى Pod لم يجهز بعد، والفحص الوحيد يعيد تشغيل قاعدة البيانات إذا تأخرت، ومهلة Timeout الإعداد `start_period` أصبحت `initialDelaySeconds: 60`، أي أنه لا يفحص أبداً في الدقيقة الأولى حتى لو جهزت القاعدة بعد ثانيتين.
- **الترحيل أصبح Pod عادياً:** الملف `migrate-pod.yaml` فيه `restartPolicy: Never`، ولا شيء ينتظره ولا شيء ينتظر قاعدة البيانات قبله، فإذا بدأ قبل القاعدة فشل مرة واحدة وانتهى، وال API لن يعرف.
- **كلمة المرور داخل الملف:** الملف `db-password-secret.yaml` فيه القيمة بترميز Base64، فإذا وضعت المخرج Output في Git كما يفعل أغلب الناس وضعت كلمة المرور معه.
- **الشبكة الداخلية اختفت:** لا توجد أي سياسة شبكة، فكل Pod في العنقود يصل إلى قاعدة البيانات.

فهل kompose بلا فائدة؟ لا، فهو نقطة بداية جيدة لتعرف أسماء الحقول، ولكنه لا يستطيع أن يعرف ما يعنيه ملفك، ونحن نعرف. لذلك حذفنا ال Namespace المسمى `kompose` كله، وكتبنا الملفات بأنفسنا، وهذا ما تبقى من المقال.

```bash
kubectl delete namespace kompose
```

## ال Image: من build إلى سجل Registry تصل إليه العقد

في Compose يكفي `build: ./api` لأن Docker الذي يبني هو نفسه الذي يشغل، أما في Kubernetes فكل عقدة تسحب ال Image بنفسها، فيجب أن تكون في سجل Registry تصل إليه كل العقد، مثل سجل خاص تشغله بنفسك أو سجل مزود السحابة. وفي kind يقوم الأمر `kind load docker-image` بهذا الدور، فينسخ ال Image من Docker على جهازك إلى containerd داخل العقد التي تحددها:

```bash
docker build -t k1-shop-api:1.0.0 ./api
kind load docker-image k1-shop-api:1.0.0 --name k1 --nodes k1-worker,k1-worker2
```

```text
Image: "k1-shop-api:1.0.0" with ID "sha256:7916e571964e64dedbbae421a5d8a7792281b63afb7950859c2131f62fab0226" not yet present on node "k1-worker", loading...
Image: "k1-shop-api:1.0.0" with ID "sha256:7916e571964e64dedbbae421a5d8a7792281b63afb7950859c2131f62fab0226" not yet present on node "k1-worker2", loading...
```

وحملناها على العقدتين العاملتين فقط، لأن عقدة التحكم لا تشغل تطبيقاتنا. ولاحظ الوسم Tag `1.0.0`: لا تستخدم `latest` في Kubernetes أبداً، والسبب أن الوسم `latest` يجعل سياسة السحب الافتراضية `Always`، فيحاول ال kubelet سحبها من السجل كل مرة، وهي غير موجودة في أي سجل هنا، ولأن عقدتين قد تشغلان نسختين مختلفتين بنفس الاسم إذا تغيرت ال Image بين سحب وآخر. وكتابة Dockerfile صحيح موضوع [كتابة Dockerfile صحيح](https://arabroot.io/articles/%D9%83%D8%AA%D8%A7%D8%A8%D8%A9-dockerfile-%D8%B5%D8%AD%D9%8A%D8%AD-multi-stage-%D9%88-layer-caching/)، وتصغير ال Image موضوع [تقليل حجم Docker Images وتأمينها](https://arabroot.io/articles/%D8%AA%D9%82%D9%84%D9%8A%D9%84-%D8%AD%D8%AC%D9%85-docker-images-%D9%88%D8%AA%D8%A7%D9%85%D9%8A%D9%86%D9%87%D8%A7/)، ولن نغير فيهما شيئاً هنا.

## ال Namespace والإعدادات Configuration في ConfigMap والسر Secret

كل كائنات التطبيق في Namespace واحد اسمه `shop`، فيظهر كله بأمر واحد ويحذف بأمر واحد:

```yaml
# Everything of the shop app lives in its own namespace: one command lists it, one command removes it.
apiVersion: v1
kind: Namespace
metadata:
  name: shop
```

والملفات التي كانت في Compose تركب من مجلد المشروع، أي ملف المتغيرات `api.env` وإعداد nginx وصفحته وسكربت Script تهيئة قاعدة البيانات، تصبح ConfigMaps. ولم نكتبها بأيدينا وإنما ولدناها من الملفات نفسها بالخيار `--dry-run=client -o yaml`، فإذا تغير ملف أعدنا التوليد:

```bash
kubectl create configmap api-env -n shop --from-env-file=api.env --dry-run=client -o yaml > 10-config.yaml
echo '---' >> 10-config.yaml
kubectl create configmap db-init -n shop --from-file=db-init/01-seed.sql --dry-run=client -o yaml >> 10-config.yaml
echo '---' >> 10-config.yaml
kubectl create configmap web-site -n shop --from-file=web/index.html --from-file=web/default.conf --dry-run=client -o yaml >> 10-config.yaml
```

```yaml
apiVersion: v1
data:
  DB_HOST: db
  DB_NAME: shop
  DB_USER: shop
  REDIS_URL: redis://redis:6379
kind: ConfigMap
metadata:
  name: api-env
  namespace: shop
---
apiVersion: v1
data:
  01-seed.sql: |
    -- Stands for loading a dump on first start: it takes a few seconds, and runs while the
    -- entrypoint's temporary server listens on the Unix socket only.
    SELECT pg_sleep(6);
    CREATE TABLE IF NOT EXISTS seed_info (loaded_at timestamptz DEFAULT now());
    INSERT INTO seed_info DEFAULT VALUES;
kind: ConfigMap
metadata:
  name: db-init
  namespace: shop
---
apiVersion: v1
data:
  default.conf: |
    server {
        listen 80;
        location / { root /usr/share/nginx/html; }
        location /api/ { proxy_pass http://api:3000; }
    }
  index.html: |
    <!doctype html><meta charset="utf-8"><title>shop</title>
    <h1>shop</h1><p>visits: <span id="n">…</span></p>
    <script>fetch('/api/hits').then(r=>r.json()).then(j=>{document.getElementById('n').textContent=j.db})</script>
kind: ConfigMap
metadata:
  name: web-site
  namespace: shop
```

لاحظ أن إعداد nginx لم يتغير فيه حرف، فما زال يقول `proxy_pass http://api:3000`، ومتغيرات ال API ما زالت `DB_HOST=db` و`redis://redis:6379`. وهذا يعمل لأننا سوف نسمي ال Services بنفس أسماء الخدمات في Compose، فيصبح `db` اسماً في DNS العنقود داخل نفس ال Namespace، كما يصبح في الشبكة الداخلية لCompose. وهذه قاعدة مفيدة عند النقل: أبق الأسماء كما هي، فلا تحتاج تغيير إعدادات التطبيق.

أما كلمة المرور فلا تدخل أي ملف YAML، وإنما ننشئ ال Secret مباشرة من ملف السر الذي كان يستخدمه Compose، وهو خارج Git:

```bash
kubectl create secret generic db-password -n shop --from-file=db_password=secrets/db_password.txt
kubectl get secret db-password -n shop
```

```text
secret/db-password created
NAME          TYPE     DATA   AGE
db-password   Opaque   1      4s
```

والاسم `db_password` قبل علامة المساواة هو اسم الملف الذي سيظهر داخل ال Container، فإذا ركبنا ال Secret كمجلد على `/run/secrets` ظهر الملف على `/run/secrets/db_password`، وهو المسار نفسه في Compose، فيقرأ التطبيق كلمة المرور من ملف كما كان دون أي تغيير في الكود Code. وتذكر ما رأيناه في مقال Kubernetes من الداخل: ال Secret محفوظ في etcd دون تشفير Encryption ما لم تفعله، وتفاصيل ال ConfigMaps وال Secrets وطرق إدارتها في Git لها مقال مستقل في هذه المرحلة.

## قاعدة البيانات Database: Deployment مع قرص PersistentVolumeClaim

ال Volume المسمى `pgdata` في Compose كان مجلداً على قرص السيرفر نفسه، كما شرحنا في [بيانات ال Containers](https://arabroot.io/articles/%D8%A8%D9%8A%D8%A7%D9%86%D8%A7%D8%AA-%D8%A7%D9%84-containers-volumes-%D9%88-bind-mounts-%D9%88%D8%A7%D9%84%D9%86%D8%B3%D8%AE-%D8%A7%D9%84%D8%A7%D8%AD%D8%AA%D9%8A%D8%A7%D8%B7%D9%8A/). وفي Kubernetes تطلب القرص بكائن اسمه PersistentVolumeClaim، أي «أحتاج قرصاً بهذا الحجم»، فينشئ موفر التخزين Storage Provisioner قرصاً PersistentVolume ويربطه به، وفي kind الموفر هو local-path الذي ينشئ مجلداً على العقدة. وهذا ملف قاعدة البيانات كاملاً:

```yaml
# PostgreSQL: one replica, its data on a PersistentVolumeClaim.
# Recreate: the old pod stops before the new one starts, so two servers never open the same data directory.
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: pgdata
  namespace: shop
spec:
  accessModes: ["ReadWriteOnce"]
  resources:
    requests:
      storage: 1Gi
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: db
  namespace: shop
spec:
  replicas: 1
  strategy:
    type: Recreate
  selector:
    matchLabels:
      app: db
  template:
    metadata:
      labels:
        app: db
        tier: backend
    spec:
      # The app never calls the Kubernetes API, and the token mount at /var/run/secrets/kubernetes.io
      # cannot be created inside our read-only secret volume at /run/secrets.
      automountServiceAccountToken: false
      containers:
        - name: postgres
          image: postgres:18.6-alpine
          env:
            - name: POSTGRES_USER
              value: shop
            - name: POSTGRES_DB
              value: shop
            - name: POSTGRES_PASSWORD_FILE
              value: /run/secrets/db_password
          ports:
            - containerPort: 5432
          # The Compose healthcheck with start_period becomes three probes here:
          startupProbe:            # up to 5 minutes for initdb, init scripts and crash recovery
            exec:
              command: ["pg_isready", "-h", "127.0.0.1", "-U", "shop", "-d", "shop"]
            periodSeconds: 5
            failureThreshold: 60
          readinessProbe:          # in the Service only while it accepts TCP connections
            exec:
              command: ["pg_isready", "-h", "127.0.0.1", "-U", "shop", "-d", "shop"]
            periodSeconds: 10
            timeoutSeconds: 3
          livenessProbe:           # restart only when the server stops answering for 30 s
            tcpSocket:
              port: 5432
            periodSeconds: 10
            failureThreshold: 3
          resources:
            requests:
              cpu: 100m
              memory: 256Mi
            limits:
              memory: 512Mi
          volumeMounts:
            - name: data
              mountPath: /var/lib/postgresql
            - name: init
              mountPath: /docker-entrypoint-initdb.d
              readOnly: true
            - name: secrets
              mountPath: /run/secrets
              readOnly: true
      volumes:
        - name: data
          persistentVolumeClaim:
            claimName: pgdata
        - name: init
          configMap:
            name: db-init
        - name: secrets
          secret:
            secretName: db-password
---
apiVersion: v1
kind: Service
metadata:
  name: db
  namespace: shop
spec:
  selector:
    app: db
  ports:
    - port: 5432
      targetPort: 5432
```

في الإعداد أعلاه لاحظ التالي:

- `strategy: Recreate` مهم جداً لقاعدة البيانات، والسبب أن الاستراتيجية الافتراضية RollingUpdate تبدأ ال Pod الجديد قبل أن توقف القديم، فيحاول خادمان Servers فتح نفس مجلد البيانات. ومع `ReadWriteOnce` على عقدة واحدة قد ينجح ذلك فعلاً ويفسد البيانات.
- الفحص `pg_isready -h 127.0.0.1` هو نفسه الذي وصلنا إليه في مقال Compose، لأن الفحص عبر ال Socket ينجح أثناء سكربتات التهيئة والخادم لا يستمع على الشبكة بعد.
- `automountServiceAccountToken: false` لم يكن في المسودة الأولى، وسببه قصة القسم التالي.
- ال Volume المسمى `init` يركب ConfigMap السكربت حيث تبحث عنه صورة PostgreSQL الرسمية، كما كان ال Bind Mount في Compose.

وقد يتساءل البعض: لماذا Deployment وليس StatefulSet، وهو الكائن المخصص لقواعد البيانات؟ والإجابة أن StatefulSet يعطي كل نسخة اسماً ثابتاً وقرصاً خاصاً بها، وهذا ما تحتاجه عندما تكون عندك عدة نسخ لها هويات مختلفة، مثل عنقود قواعد بيانات فيه رئيسي ونسخ متماثلة. أما نسخة واحدة فال Deployment مع Recreate وقرص واحد يكفيها، وهو أقرب إلى ما كان في Compose. وعندما تحتاج أكثر من نسخة فلا تكتب ذلك بنفسك، وإنما استخدم مشغلاً Operator مثل الذي شرحناه في [PostgreSQL على Kubernetes مع CloudNativePG](https://arabroot.io/articles/postgresql-%D8%B9%D9%84%D9%89-kubernetes-%D9%85%D8%B9-cloudnativepg/)، وStatefulSets لها مقال مستقل في هذه المرحلة.

### أين البيانات Data فعلاً؟

طلبنا في ال PersistentVolumeClaim قرصاً بحجم 1Gi، فماذا أعطانا موفر التخزين؟ لننظر إلى ال PersistentVolume الذي أنشأه، وإلى ما تراه PostgreSQL من داخل ال Container:

```bash
kubectl get pv -o custom-columns=NAME:.metadata.name,CLAIM:.spec.claimRef.name,PATH:.spec.hostPath.path,NODE:.spec.nodeAffinity.required.nodeSelectorTerms[0].matchExpressions[0].values[0]
kubectl exec -n shop deploy/db -- df -h /var/lib/postgresql | tail -1
```

```text
NAME                                       CLAIM       PATH                                                                                  NODE
pvc-5fad43d2-bdc0-4e66-a0a5-a126fa2ba587   pgdata      /var/local-path-provisioner/pvc-5fad43d2-bdc0-4e66-a0a5-a126fa2ba587_shop_pgdata      k1-worker2
pvc-b9c74bf2-39d5-40cb-93fd-365c739b3cfb   redisdata   /var/local-path-provisioner/pvc-b9c74bf2-39d5-40cb-93fd-365c739b3cfb_shop_redisdata   k1-worker

/dev/sdc               1006.9G    228.6G    727.1G  24% /docker-entrypoint-initdb.d
```

في المخرج أعلاه لاحظ التالي:

- القرص ليس قرصاً، وإنما مجلد على العقدة k1-worker2 تحت `/var/local-path-provisioner`، تماماً مثل ال Named Volume في Docker، والفرق أن اسمه يحمل ال Namespace واسم ال PVC.
- عمود `NODE` يقول إن ال PV مربوط بالعقدة k1-worker2 بقاعدة تقارب Node Affinity، أي أن Pod قاعدة البيانات لن يجدول بعد اليوم إلا على هذه العقدة. فإذا توقفت العقدة فلن ينتقل إلى عقدة أخرى كما ينتقل ال API، وإنما يبقى `Pending` حتى تعود، لأن بياناته هناك.
- الحجم 1Gi لم يطبق أبداً، فالأمر `df` يرى قرص الجهاز كله، 1006.9 جيجابايت، فموفر local-path لا يحد الحجم، والرقم في ال PVC للمطابقة فقط. فإذا امتلأت قاعدة البيانات امتلأ قرص العقدة كله معها.

وهذا مقبول في التجربة وعلى عنقود من سيرفر واحد، ولكنه يعني أن قاعدة البيانات في عنقودنا من ثلاث عقد ليست أكثر توافراً Availability مما كانت عليه في Compose. والتخزين الذي يتبع ال Pod إلى أي عقدة ويحد الحجم فعلاً يحتاج تخزيناً شبكياً أو نظاماً مثل Longhorn، وله مقال مستقل في هذه المرحلة.

### لماذا لم يبدأ أي Pod يركب السر Secret على `/run/secrets`؟

في المحاولة الأولى لم يكن في الملف السطر `automountServiceAccountToken: false`، وكنا قد أصلحنا خطأ kompose، فال Secret مركب كمجلد وليس كملف. ومع ذلك لم يبدأ ال API ولا الترحيل:

```bash
kubectl get pod -n shop -l app=api -o jsonpath='{.items[0].status.initContainerStatuses[0].lastState.terminated.message}'
```

```text
failed to create containerd task: failed to create shim task: OCI runtime create failed: runc create failed: unable to start container process: error during container init: error mounting "/var/lib/kubelet/pods/8c1cefd5-…/volumes/kubernetes.io~projected/kube-api-access-k5f2m" to rootfs at "/var/run/secrets/kubernetes.io/serviceaccount": create mountpoint for /var/run/secrets/kubernetes.io/serviceaccount mount: make mountpoint "/var/run/secrets/kubernetes.io/serviceaccount": mkdirat /run/containerd/io.containerd.runtime.v2.task/k8s.io/3f595e4dda73…/rootfs/run/secrets/kubernetes.io: read-only file system
```

والخطأ هذه المرة مختلف: `read-only file system`. فال Secret الآن مجلد على `/run/secrets`، ومركب للقراءة فقط، ثم جاء ال kubelet يركب رمز الدخول في `/run/secrets/kubernetes.io/serviceaccount`، أي داخل مجلدنا، فاحتاج أن ينشئ المجلد `kubernetes.io` فيه، فلم يستطع. فالمسار `/run/secrets` الذي اختاره Compose تقليداً من Docker Swarm هو نفسه المسار الذي يستخدمه Kubernetes لرموز الدخول، وهذا تعارض لن تجده في أي ملف Compose.

وأمامك حلان: أن تركب السر في مسار آخر مثل `/etc/shop-secrets` وتغير المتغير `DB_PASSWORD_FILE` ليشير إليه، أو أن تلغي تركيب رمز الدخول. واخترنا الثاني لسبب آخر مهم: تطبيقنا لا يتحدث مع ال API Server أبداً، ورمز الدخول في كل Pod يعطي من يخترق التطبيق هوية داخل العنقود يستطيع أن يسأل بها ال API Server، فإلغاؤه في كل Pod لا يحتاجه ممارسة أمان جيدة أصلاً، كما تشرح [صفحة حسابات الخدمة Service Accounts](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/?ref=arabroot.io). وبعد إضافة السطر أصبح المجلد كما في Compose:

```bash
kubectl exec -n shop deploy/api -c api -- ls -la /run/secrets/
```

```text
total 4
drwxrwxrwt    3 root     root           100 Nov 18 19:41 .
drwxr-xr-x    1 root     root          4096 Nov 18 19:55 ..
drwxr-xr-x    2 root     root            60 Nov 18 19:41 ..2026_11_18_19_41_14.846111922
lrwxrwxrwx    1 root     root            31 Nov 18 19:41 ..data -> ..2026_11_18_19_41_14.846111922
lrwxrwxrwx    1 root     root            18 Nov 18 19:41 db_password -> ..data/db_password
```

والملف `db_password` اختصار إلى مجلد بتاريخ، وهذه طريقة ال kubelet ليحدث ال Secret دون أن يرى التطبيق ملفاً نصف مكتوب: يكتب المجلد الجديد كاملاً ثم يغير الاختصار `..data` مرة واحدة. ولهذا السبب لا تركب ال Secret بالخيار `subPath` كما فعل kompose، فال `subPath` يركب الملف مرة واحدة ولا يحدثه أبداً إذا غيرت كلمة المرور.

## فحص الصحة Health Check أصبح ثلاثة فحوص Probes

في Compose فحص واحد اسمه `healthcheck` يقول هل الخدمة سليمة، ومعه `start_period` يعطيها مهلة عند البدء. وفي Kubernetes ثلاثة فحوص لكل منها نتيجة مختلفة، كما في [صفحة فحوص ال Liveness وال Readiness وال Startup](https://kubernetes.io/docs/concepts/configuration/liveness-readiness-startup-probes/?ref=arabroot.io):

| الفحص          | السؤال                  | إذا فشل                                                           | يقابله في Compose                              |
| -------------- | ----------------------- | ----------------------------------------------------------------- | ---------------------------------------------- |
| startupProbe   | هل انتهى البدء؟         | بعد العدد المحدد يقتل ال Container ويعيده، ولا يعمل غيره حتى ينجح | start\_period                                  |
| readinessProbe | هل يستقبل الطلبات الآن؟ | يخرج من ال Service ولا يقتل                                       | الشرط service\_healthy عند البدء فقط           |
| livenessProbe  | هل العملية حية؟         | يقتل ال Container ويعيده                                          | لا يوجد، فCompose لا يعيد تشغيل خدمة Unhealthy |

والخطأ الذي يقع فيه الناس، وكاد أن يقع فيه kompose، هو أن يجعلوا الفحص نفسه للاثنين، فيعيد Kubernetes تشغيل الخدمة كلما كانت مشغولة أو كان شيء تعتمد عليه متوقفاً. لذلك جعلنا فحص الحياة في كل خدمات التطبيق فحص اتصال Connection بسيطاً على المنفذ `tcpSocket`، أي «هل العملية تستمع؟»، وجعلنا فحص الجاهزية هو الفحص الحقيقي. وفي ال API بالذات المسار `/healthz` ينفذ `SELECT 1` على قاعدة البيانات، فلو جعلناه فحص حياة لأعاد Kubernetes تشغيل كل نسخ ال API كلما توقفت قاعدة البيانات، وهذا لا يصلح شيئاً، وإنما يضيف عطلاً فوق عطل.

### عندما قتل فحص البدء Startup Probe قاعدة البيانات مرتين

في المحاولة الأولى نقلنا `start_period: 60s` من Compose كما هو، فكتبنا فحص البدء بثلاثين محاولة كل ثانيتين، أي 60 ثانية. وعلى سيرفر سريع يكفي هذا بكثير، ولكن في التجربة كان القرص مشغولاً، وهذا ما ظهر في أحداث Events ال Pod:

```bash
kubectl describe pod -n shop -l app=db | sed -n '/Last State/,/Restart Count/p;/Events:/,$p'
```

```text
    Last State:     Terminated
      Reason:       Error
      Exit Code:    137
      Started:      Wed, 18 Nov 2026 22:12:54 +0300
      Finished:     Wed, 18 Nov 2026 22:14:26 +0300
    Ready:          True
    Restart Count:  2
Events:
  Type     Reason     Age                 From               Message
  ----     ------     ----                ----               -------
  Normal   Scheduled  16m                 default-scheduler  Successfully assigned shop/db-65669f946-qxzth to k1-worker2
  Warning  Unhealthy  15m (x25 over 15m)  kubelet            spec.containers{postgres}: Startup probe failed: 127.0.0.1:5432 - no response
  Normal   Killing    13m (x2 over 14m)   kubelet            spec.containers{postgres}: Container postgres failed startup probe, will be restarted
```

وسجل المحاولة الثانية يشرح لماذا أصبح الأمر أسوأ بعد القتل الأول:

```bash
kubectl logs -n shop deploy/db --previous | head -12
```

```text
PostgreSQL Database directory appears to contain a database; Skipping initialization

2026-11-18 19:12:55.828 UTC [1] LOG:  starting PostgreSQL 18.6 on x86_64-pc-linux-musl, compiled by gcc (Alpine 15.2.0) 15.2.0, 64-bit
2026-11-18 19:12:55.828 UTC [1] LOG:  listening on IPv4 address "0.0.0.0", port 5432
2026-11-18 19:12:56.381 UTC [41] LOG:  database system was interrupted; last known up at 2026-11-18 19:12:22 UTC
2026-11-18 19:12:56.391 UTC [42] FATAL:  the database system is starting up
2026-11-18 19:13:06.497 UTC [41] LOG:  syncing data directory (fsync), elapsed time: 10.09 s, current path: ./base/16384/2995
2026-11-18 19:13:16.464 UTC [41] LOG:  syncing data directory (fsync), elapsed time: 20.06 s, current path: ./base/16384/2696
2026-11-18 19:13:31.448 UTC [41] LOG:  syncing data directory (fsync), elapsed time: 35.04 s, current path: ./base/4/3997
```

واختصرنا من السجل أسطر `FATAL: the database system is starting up` المتكررة، فهي رد الخادم على كل فحص. والقصة كما يلي:

1. في التشغيل الأول أنهت PostgreSQL إنشاء ملفاتها وسكربت التهيئة، وأصبحت جاهزة في 19:12:22، وهذا السطر `last known up`، ولكن مهلة الستين ثانية كانت قد انتهت قبلها بلحظات، فقرر ال kubelet قتلها، وانتهى القتل بالإشارة Signal المسماة SIGKILL والرمز 137.
2. في التشغيل الثاني وجدت PostgreSQL أنها توقفت فجأة `database system was interrupted`، فبدأت إصلاح ما بعد التوقف المفاجئ Crash Recovery، وأوله أن تكتب كل ملفات المجلد إلى القرص `syncing data directory (fsync)`، فأخذ هذا وحده أكثر من 35 ثانية، فانتهت المهلة Timeout مرة أخرى وقتلت مرة أخرى في 22:14:26.
3. في التشغيل الثالث وجدت الملفات أكثر استقراراً فبدأت أسرع، وأصبحت جاهزة قبل نهاية المهلة.

![خط زمني من التشغيل الأول: من 11:20 initdb وسكربت التهيئة ثم جاهزة في 12:22، ومهلة 60 ثانية انتهت فوصل Killing: failed startup probe، ثم التشغيل الثاني من 12:54 في إصلاح ما بعد التوقف أكثر من 35 ثانية وانتهت المهلة مرة ثانية وExit Code 137 في 14:26، ثم التشغيل الثالث جاهز في 15:11، والإصلاح periodSeconds 5 مع failureThreshold 60](https://arabroot.io/content/images/2026/11/compose-to-k8s-03-probe-kill.webp)

كل قتل جعل التشغيل التالي أبطأ، لأن PostgreSQL تبدأ بإصلاح ما بعد التوقف المفاجئ

وهذه حلقة تزداد سوءاً مع كل دورة، ولو كان القرص أبطأ قليلاً لما خرجت منها أبداً. والدرس أن مهلة فحص البدء ليست رقماً تنقله من Compose، لأن Compose لا يقتل الخدمة عندما تنتهي `start_period`، وإنما يبدأ فقط في احتساب الفشل، أما Kubernetes فيقتلها. فاجعل المهلة أطول بكثير من أسوأ بدء تتوقعه، ففحص البدء لا يكلف شيئاً إذا نجح مبكراً، ولذلك جعلناها خمس دقائق، وفي التشغيل النظيف الأخير جهزت القاعدة في 65 ثانية دون أي إعادة تشغيل.

## ترتيب البدء Startup Order دون depends\_on: ال Init Container

في Compose كان ال API ينتظر قاعدة البيانات بالشرط `service_healthy`، وينتظر مهمة الترحيل بالشرط `service_completed_successfully`. وKubernetes لا يملك أي مفهوم لترتيب البدء بين Deployments مختلفة، وهذا مقصود، لأن قاعدة البيانات قد تعيد التشغيل بعد ساعة، والترتيب عند البدء لا يحمي من ذلك، كما ذكرنا في مقال Compose. وما يقدمه بدلاً من ذلك هو الحاوية التمهيدية Init Container: Container يعمل داخل ال Pod قبل ال Container الأساسي، ويجب أن ينتهي بنجاح قبل أن يبدأ التطبيق، وإذا فشل أعاده ال kubelet بنفس الانتظار المتزايد الذي رأيناه في CrashLoopBackOff، كما في [صفحة ال Init Containers](https://kubernetes.io/docs/concepts/workloads/pods/init-containers/?ref=arabroot.io). فجعلنا الترحيل Init Container في Pod ال API نفسه، بنفس ال Image وبالأمر `node migrate.js`:

```yaml
# The API: two replicas. The migration runs as an init container before the API container starts,
# and the kubelet retries it until the database accepts connections (Compose: service_completed_successfully).
apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
  namespace: shop
spec:
  replicas: 2
  selector:
    matchLabels:
      app: api
  template:
    metadata:
      labels:
        app: api
        tier: backend
    spec:
      terminationGracePeriodSeconds: 10      # stop_grace_period: 10s
      # The app never calls the Kubernetes API, and the token mount at /var/run/secrets/kubernetes.io
      # cannot be created inside our read-only secret volume at /run/secrets.
      automountServiceAccountToken: false
      initContainers:
        - name: migrate
          image: k1-shop-api:1.0.0
          command: ["node", "migrate.js"]
          envFrom:
            - configMapRef:
                name: api-env
          env:
            - name: DB_PASSWORD_FILE
              value: /run/secrets/db_password
          volumeMounts:
            - name: secrets
              mountPath: /run/secrets
              readOnly: true
      containers:
        - name: api
          image: k1-shop-api:1.0.0
          envFrom:
            - configMapRef:
                name: api-env
          env:
            - name: DB_PASSWORD_FILE
              value: /run/secrets/db_password
            - name: APP_VERSION          # Compose took it from .env; here it is written with the image tag
              value: "1.0.0"
          ports:
            - containerPort: 3000
          startupProbe:            # liveness waits until the process listens once
            tcpSocket:
              port: 3000
            periodSeconds: 2
            failureThreshold: 60
          readinessProbe:          # /healthz runs SELECT 1: not ready while the database is away
            httpGet:
              path: /healthz
              port: 3000
            periodSeconds: 5
            timeoutSeconds: 3
          livenessProbe:           # only the process: do not restart the API because the database is down
            tcpSocket:
              port: 3000
            periodSeconds: 10
            failureThreshold: 3
          resources:
            requests:
              cpu: 100m
              memory: 64Mi
            limits:
              cpu: 500m
              memory: 128Mi
          volumeMounts:
            - name: secrets
              mountPath: /run/secrets
              readOnly: true
      volumes:
        - name: secrets
          secret:
            secretName: db-password
---
apiVersion: v1
kind: Service
metadata:
  name: api
  namespace: shop
spec:
  selector:
    app: api
  ports:
    - port: 3000
      targetPort: 3000
```

وملفا Redis وweb على النمط نفسه، فRedis مع قرص صغير وفحص جاهزية `redis-cli ping`، وweb بنسختين يركب إعداد nginx والصفحة من ال ConfigMap بالخيار `subPath`، وهو مقبول هنا لأن الإعداد لا يتغير إلا مع نسخة جديدة. والملفات كلها في مجلد `lab` مع المقال. ثم طبقنا المجلد كله مرة واحدة على Namespace فارغ، كما يحدث عند أول تثبيت على عنقود جديد، وراقبنا ال Pods بالوقت:

```bash
kubectl apply -f k8s/
kubectl get pods -n shop -w
```

```text
22:41:28 api-95849cd49-jlzvw      0/1   Init:Error          0     108s
22:41:44 db-6fdbb4f9d8-gtgd5      0/1   Running             0             2m8s
22:41:46 api-95849cd49-jlzvw      0/1   Init:CrashLoopBackOff   1 (13s ago)   2m6s
22:42:42 api-95849cd49-jlzvw      0/1   Init:Error              3 (51s ago)   3m2s
22:42:49 db-6fdbb4f9d8-gtgd5      1/1   Running                 0             3m12s
22:43:11 api-95849cd49-s67ft      0/1   Init:0/1                4 (53s ago)   3m31s
22:43:13 api-95849cd49-s67ft      0/1   PodInitializing         0             3m33s
22:43:17 api-95849cd49-s67ft      0/1   Running                 0             3m37s
22:43:35 api-95849cd49-s67ft      1/1   Running                 0             3m54s
```

وسجل محاولة فاشلة للترحيل، وهذا من تشغيل سابق بنفس الملفات، ثم سجل المحاولة الناجحة في التشغيل الأخير:

```bash
kubectl logs -n shop api-6db8479cd8-9gmn2 -c migrate
kubectl logs -n shop deploy/api -c migrate
```

```text
Error: connect ECONNREFUSED 10.96.152.74:5432
    at TCPConnectWrap.afterConnect [as oncomplete] (node:net:2021:16) {
  errno: -111,
  code: 'ECONNREFUSED',
  syscall: 'connect',
  address: '10.96.152.74',
  port: 5432
}

Found 2 pods, using pod/api-95849cd49-s67ft
migrate: table visits ready, 0 rows
```

في المخرج أعلاه لاحظ التالي:

- الترحيل فشل أربع مرات بالخطأ `ECONNREFUSED` لأن القاعدة لم تكن جاهزة، ونجح في المحاولة الخامسة، وكل ذلك دون أن نكتب سطر انتظار واحداً، فالإعادة جاءت من ال kubelet.
- العنوان Address في الخطأ هو ClusterIP لل Service المسمى `db` في ذلك التشغيل، والرفض جاء فوراً وليس بعد مهلة، لأن kube-proxy يكتب قاعدة ترفض الاتصال عندما لا يكون خلف ال Service أي Pod جاهز، وهذا أفضل من أن ينتظر التطبيق حتى تنتهي مهلته.
- القاعدة جهزت في 22:42:49، والترحيل نجح في 22:43:11، أي بعد 22 ثانية، والسبب أن ال kubelet كان في فترة انتظار بين محاولتين عندما جهزت القاعدة. فهذا الأسلوب أبطأ من شرط الانتظار في Compose، ولكنه يعمل بنفس الطريقة عند أول تثبيت وعند كل إعادة تشغيل بعد ذلك.
- عمود `RESTARTS` عاد صفراً عندما بدأ ال Container الأساسي، فهو يعد إعادات تشغيل التطبيق وليس ال Init Container، فلا تتفاجأ إذا رأيت Pod عمره أربع دقائق وإعاداته صفر.

![ثلاثة مسارات زمنية من التشغيل النظيف: db في Pending ثم ContainerCreating حتى 41:44 ثم initdb حتى 42:49 ثم Ready، وmigrate فشل أربع مرات بالخطأ ECONNREFUSED قبل جاهزية القاعدة ونجح في 43:11، وapi في Init:CrashLoopBackOff حتى أصبح Ready في 22:43:35](https://arabroot.io/content/images/2026/11/compose-to-k8s-04-startup-order.webp)

ال Init Container يعاد حتى تجهز القاعدة، والانتظار بين المحاولات أخر البدء 22 ثانية

وقد يتساءل البعض: نسختان من ال API تعنيان أن الترحيل يعمل مرتين في وقت واحد، فهل هذا آمن؟ في تطبيقنا نعم، لأن الترحيل جملة واحدة `CREATE TABLE IF NOT EXISTS`، ولكن في ترحيل حقيقي يغير جداول موجودة قد يتصادم التشغيلان. وأمامك عندها خياران: أداة ترحيل تأخذ قفلاً Lock في قاعدة البيانات قبل أن تبدأ، وأغلب الأدوات المعروفة تفعل ذلك، أو أن تجعل الترحيل كائناً منفصلاً من نوع Job يعمل مرة واحدة قبل نشر النسخة الجديدة، وهو الأقرب إلى خدمة `migrate` في Compose، ويحتاج خط نشر Pipeline ينتظر انتهاءه قبل أن يطبق ال Deployment.

## التطبيق النهائي Final App يعمل

![ال Namespace المسمى shop: port-forward على 9573 إلى Service web على المنفذ 80 ثم Deployment web من نسختين nginx، وproxy_pass إلى Service api على 3000 ثم Deployment api من نسختين في كل منها init migrate ثم api، ومنه إلى Service db على 5432 أمام Deployment db بنسخة واحدة مع PVC pgdata بحجم 1Gi، وإلى Service redis على 6379 أمام Deployment redis مع PVC redisdata، وصندوق فيه ConfigMap api-env وweb-site وdb-init وSecret db-password](https://arabroot.io/content/images/2026/11/compose-to-k8s-02-architecture.webp)

أربعة Deployments وأربعة Services بنفس أسماء خدمات Compose، فلم يتغير أي إعداد في التطبيق

```bash
kubectl get pods,svc,pvc -n shop
```

```text
NAME                         READY   STATUS    RESTARTS   AGE
pod/api-95849cd49-jlzvw      1/1     Running   0          5m33s
pod/api-95849cd49-s67ft      1/1     Running   0          5m33s
pod/db-6fdbb4f9d8-gtgd5      1/1     Running   0          5m37s
pod/redis-5cfbbd679b-jbq46   1/1     Running   0          5m35s
pod/web-79678d4c5d-dzk2p     1/1     Running   0          5m31s
pod/web-79678d4c5d-gqmxm     1/1     Running   0          5m31s

NAME            TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)    AGE
service/api     ClusterIP   10.96.235.94    <none>        3000/TCP   5m35s
service/db      ClusterIP   10.96.105.83    <none>        5432/TCP   5m39s
service/redis   ClusterIP   10.96.225.118   <none>        6379/TCP   5m36s
service/web     ClusterIP   10.96.224.86    <none>        80/TCP     5m33s

NAME                              STATUS   VOLUME                                     CAPACITY   ACCESS MODES   STORAGECLASS   VOLUMEATTRIBUTESCLASS   AGE
persistentvolumeclaim/pgdata      Bound    pvc-5fad43d2-bdc0-4e66-a0a5-a126fa2ba587   1Gi        RWO            standard       <unset>                 5m40s
persistentvolumeclaim/redisdata   Bound    pvc-b9c74bf2-39d5-40cb-93fd-365c739b3cfb   256Mi      RWO            standard       <unset>                 5m37s
```

ولا يوجد منفذ منشور على أي عقدة، فكل ال Services من النوع ClusterIP، والوصول من جهازنا عبر port-forward إلى web كما شرحنا في مقال kubectl، أما في الإنتاج Production فهذا عمل Ingress أو Gateway، وله مقال مستقل في هذه المرحلة مع شهادات Certificates لل HTTPS:

```bash
kubectl port-forward -n shop svc/web 9573:80 &
curl -s http://127.0.0.1:9573/ | head -3
curl -s http://127.0.0.1:9573/api/hits
curl -s http://127.0.0.1:9573/api/hits
curl -s http://127.0.0.1:9573/api/hits
```

```text
<!doctype html><meta charset="utf-8"><title>shop</title>
<h1>shop</h1><p>visits: <span id="n">…</span></p>
<script>fetch('/api/hits').then(r=>r.json()).then(j=>{document.getElementById('n').textContent=j.db})</script>
{"db":1,"redis":1,"version":"1.0.0"}
{"db":2,"redis":2,"version":"1.0.0"}
{"db":3,"redis":3,"version":"1.0.0"}
```

الطلب مر من جهازنا إلى nginx، ثم إلى ال API بالاسم `api`، ثم إلى PostgreSQL وRedis بالاسمين `db` و`redis`، والعدادان يزيدان معاً، والإصدار `1.0.0` وصل من متغير البيئة. وكل ذلك بنفس الكود ونفس إعداد nginx ونفس ملف المتغيرات الذي كان في Compose. وتحققنا أيضاً أن سكربت التهيئة عمل مرة واحدة في أول تشغيل:

```bash
kubectl exec -n shop deploy/db -- psql -U shop -d shop -c 'select count(*) from visits' -c 'select * from seed_info'
```

```text
 count
-------
     4
(1 row)

           loaded_at
-------------------------------
 2026-11-18 19:42:21.560571+00
(1 row)
```

وهذه القراءة بعد أن أوقفنا قاعدة البيانات وأعدناها في القسم التالي، والعدد 4 يعني أن البيانات بقيت على القرص رغم أن Pod القاعدة أصبح Pod جديداً باسم جديد.

### مفاجأة صغيرة في متغيرات البيئة Environment Variables

عندما فحصنا المتغيرات داخل ال API لنتأكد أن ال ConfigMap وصل، وجدنا متغيرات لم نكتبها:

```bash
kubectl exec -n shop deploy/api -c api -- sh -c 'env | grep -E "^(DB_|REDIS_|APP_)" | sort'
```

```text
APP_VERSION=1.0.0
DB_HOST=db
DB_NAME=shop
DB_PASSWORD_FILE=/run/secrets/db_password
DB_PORT=tcp://10.96.105.83:5432
DB_PORT_5432_TCP=tcp://10.96.105.83:5432
DB_PORT_5432_TCP_ADDR=10.96.105.83
DB_PORT_5432_TCP_PORT=5432
DB_PORT_5432_TCP_PROTO=tcp
DB_SERVICE_HOST=10.96.105.83
DB_SERVICE_PORT=5432
DB_USER=shop
REDIS_PORT=tcp://10.96.225.118:6379
REDIS_PORT_6379_TCP=tcp://10.96.225.118:6379
REDIS_PORT_6379_TCP_ADDR=10.96.225.118
REDIS_PORT_6379_TCP_PORT=6379
REDIS_PORT_6379_TCP_PROTO=tcp
REDIS_SERVICE_HOST=10.96.225.118
REDIS_SERVICE_PORT=6379
REDIS_URL=redis://redis:6379
```

فال kubelet يضيف لكل Service في ال Namespace مجموعة متغيرات باسمه، وال Service اسمه `db`، فظهر المتغير `DB_PORT=tcp://10.96.105.83:5432`. وتطبيقنا لا يقرأ `DB_PORT`، ولكن تطبيقات كثيرة تقرؤه وتتوقع رقماً مثل 5432، فتجد نصاً يبدأ ب `tcp://` فتتوقف برسالة غريبة لن تفهمها في Compose، لأن Compose لا يضيف هذه المتغيرات. فإذا كان تطبيقك يستخدم متغيرات بأسماء مثل `DB_PORT` أو `REDIS_PORT` فأضف إلى ال Pod السطر `enableServiceLinks: false`، فهو يوقف هذه المتغيرات، والتطبيق يجد الخدمات بأسمائها عبر DNS على أي حال.

## حد الذاكرة Memory Limit: من memswap\_limit إلى OOMKilled

في مقال Compose رأينا أن حد الذاكرة وحده يسمح للتطبيق بمثله من ال Swap، واحتجنا `memswap_limit` ليصبح الحد حداً فعلاً. أما ال kubelet فلا يعطي ال Containers أي Swap افتراضياً، فالحد `limits.memory: 128Mi` وحده يكفي. ولنتأكد استدعينا المسار `/api/hog` الذي يحجز 50 ميجابايت في كل طلب، مباشرة على أحد ال Pods:

```bash
kubectl port-forward -n shop pod/api-95849cd49-jlzvw 9573:3000 &
curl -s -m 15 http://127.0.0.1:9573/api/hog
curl -s -m 15 http://127.0.0.1:9573/api/hog
curl -s -m 15 http://127.0.0.1:9573/api/hog
kubectl get pod -n shop api-95849cd49-jlzvw -o jsonpath='{range .status.containerStatuses[*]}{.name} restarts={.restartCount} last={.lastState.terminated.reason}/{.lastState.terminated.exitCode}{"\n"}{end}'
```

```text
holding 50 MB
holding 100 MB

api restarts=1 last=Error/137
```

```text
22:46:07 api-95849cd49-jlzvw   1/1   Running   0     6m26s
22:46:15 api-95849cd49-jlzvw   0/1   Error     0     6m35s
22:46:17 api-95849cd49-jlzvw   0/1   Running   1 (4s ago)   6m37s
22:46:32 api-95849cd49-jlzvw   1/1   Running   1 (18s ago)   6m51s
```

الطلب الثالث لم يرد أصلاً، لأن التطبيق تجاوز 128 ميجابايت فقتلته النواة Kernel، وأعاده ال kubelet خلال ثانيتين، وأصبح جاهزاً بعد 15 ثانية. وسجل النواة على العقدة يؤكد ذلك:

```bash
docker exec k1-worker sh -c 'dmesg | grep -E "Memory cgroup out of memory" | tail -1'
```

```text
[41001.656600] Memory cgroup out of memory: Killed process 218608 (MainThread) total-vm:1292364kB, anon-rss:128184kB, file-rss:35572kB, shmem-rss:0kB, UID:1000 pgtables:1340kB oom_score_adj:999
```

ولاحظ شيئين في هذه التجربة. الأول أن السبب في حالة Status ال Container كان `Error` مع الرمز 137، وليس `OOMKilled` الذي تتوقع رؤيته، وهذا يحدث على بعض الأجهزة التي تستخدم cgroup v1 مثل جهاز التجربة، فلا تعتمد على كلمة السبب وحدها، فالرمز 137 يعني SIGKILL دائماً، وأول من تشك فيه هو حد الذاكرة. والثاني أن port-forward توقف مع ال Pod برسالة `lost connection to pod`، وهذا ما ذكرناه في مقال kubectl: هو أداة للتشخيص وليس للنشر. وكيف تضبط الطلب والحد بالقياس بدل التخمين موضوع مقال مستقل في هذه المرحلة عن التوسع التلقائي وحدود الموارد.

## الشبكة الداخلية Internal Network: سياسة NetworkPolicy

في Compose كانت قاعدة البيانات وRedis على شبكة `backend` الداخلية، وكان nginx على شبكة `frontend` فقط، فلم يكن يستطيع الوصول إلى قاعدة البيانات حتى لو اخترق أحدهم nginx. أما في Kubernetes فكل Pod يصل إلى كل Pod آخر في العنقود افتراضياً، وفي كل ال Namespaces، وما يقابل الشبكة الداخلية هو سياسة الشبكة NetworkPolicy كما في [صفحة سياسات الشبكة](https://kubernetes.io/docs/concepts/services-networking/network-policies/?ref=arabroot.io):

```yaml
# Compose had a backend network marked internal. Here: only the API may open connections to db and redis.
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: db-redis-from-api-only
  namespace: shop
spec:
  podSelector:
    matchExpressions:
      - key: app
        operator: In
        values: ["db", "redis"]
  policyTypes: ["Ingress"]
  ingress:
    - from:
        - podSelector:
            matchLabels:
              app: api
```

والسياسة تقول: ال Pods التي تحمل `app=db` أو `app=redis` لا تقبل اتصالاً إلا من ال Pods التي تحمل `app=api`. وقبلها ال API Server دون أي خطأ، ثم اختبرناها:

```bash
kubectl get networkpolicy -n shop
kubectl exec -n shop deploy/web -- sh -c 'nc -z -w 3 db 5432 && echo web-to-db: open || echo web-to-db: blocked'
kubectl exec -n shop deploy/api -c api -- sh -c 'nc -z -w 3 db 5432 && echo api-to-db: open || echo api-to-db: blocked'
```

```text
NAME                     POD-SELECTOR        AGE
db-redis-from-api-only   app in (db,redis)   25m
web-to-db: open
api-to-db: open
```

nginx ما زال يصل إلى قاعدة البيانات، أي أن السياسة موجودة ولا تعمل. والسبب أن سياسات الشبكة لا ينفذها Kubernetes نفسه، وإنما إضافة الشبكة CNI، فإذا كانت الإضافة لا تدعمها أو لم تستطع تطبيقها قبلها ال API Server وحفظها ولم يحدث شيء. وفي التجربة كتبت إضافة kindnet هذا في سجلها:

```text
E1118 18:11:47.418937       1 controller.go:217] "initial nftables sync failed" err=<
	conn.Receive: netlink receive: operation not supported
	netlink receive: no such file or directory
	netlink receive: no such file or directory
```

فمحرك السياسات في kindnet يكتب قواعده بنظام nftables، ونواة WSL2 على جهاز التجربة لا تدعم ما يحتاجه منه، ففشل بصمت تقريباً، ورسالة واحدة في سجل لا يقرؤه أحد. وهذا أهم درس في القسم كله: لا تعتبر أي سياسة شبكة تعمل حتى تختبرها بنفسك من Pod يجب أن يمنع، كما فعلنا ب `nc`، واجعل هذا الاختبار جزءاً من خط النشر. وعلى عنقود حقيقي بإضافة تدعم السياسات مثل Cilium أو Calico، أو kind على سيرفر Linux بنواة حديثة، يرد الأمر الأول بالكلمة `blocked`.

## ماذا يحدث إذا توقفت قاعدة البيانات Database؟

في مقال Compose ذكرنا أن شروط الانتظار تعمل عند البدء فقط، وأن التطبيق يحتاج أن يعيد الاتصال بنفسه إذا فقد قاعدة البيانات لاحقاً. وتطبيقنا لا يفعل ذلك، فهو يتصل مرة واحدة عند البدء. فماذا يفعل Kubernetes معه؟ أوقفنا قاعدة البيانات بتغيير عدد نسخها إلى صفر، وراقبنا ال API:

```bash
kubectl scale deploy/db -n shop --replicas=0
kubectl get pods -n shop -l app=api
curl -s -w ' HTTP %{http_code}\n' http://127.0.0.1:9573/api/hits
kubectl logs -n shop api-95849cd49-jlzvw -c api --previous | head -5
```

```text
deployment.apps/db scaled
NAME                  READY   STATUS             RESTARTS      AGE
api-95849cd49-jlzvw   0/1     CrashLoopBackOff   2 (23s ago)   8m44s
api-95849cd49-s67ft   0/1     CrashLoopBackOff   2 (10s ago)   8m44s

<html>
<head><title>502 Bad Gateway</title></head>
<body>
<center><h1>502 Bad Gateway</h1></center>
<hr><center>nginx/1.29.8</center>
</body>
</html>
 HTTP 502

node:internal/modules/run_main:107
    triggerUncaughtException(
    ^

Error: connect ECONNREFUSED 10.96.105.83:5432
```

كنا نتوقع أن يصبح ال API غير جاهز ويخرج من ال Service ويبقى يعمل، فهذا ما صممنا له الفحوص. ولكن الذي حدث أسرع وأبسط: عندما أغلقت PostgreSQL الاتصال توقف التطبيق نفسه، لأن مكتبة `pg` ترسل خطأ على الاتصال المغلق ولا أحد في الكود يلتقطه، فأعاده ال kubelet، فحاول الاتصال عند البدء فوجد الرفض فتوقف، وهكذا في CrashLoopBackOff. ونتيجة المستخدم هي نفسها في الحالتين: nginx يرد ب 502 لأن ال API لا يرد. ثم أعدنا قاعدة البيانات:

```bash
kubectl scale deploy/db -n shop --replicas=1
# poll every 5 s: ready replicas of db and api
```

```text
22:54:35 scaled
22:54:56 db=1 api=
22:56:08 db=1 api=1
22:56:14 db=1 api=2
```

جهزت القاعدة بعد 21 ثانية، لأن ملفاتها كانت على القرص، ولكن ال API احتاج 78 ثانية أخرى ليعود، لأن ال kubelet كان قد وصل في عد الانتظار إلى أكثر من دقيقة بين المحاولات، فبقي التطبيق متوقفاً بعد أن زال السبب. ولاحظ أيضاً أن أمر الإعادة scale فشل في محاولتنا الأولى برسالة `TLS handshake timeout`، لأن ال API Server كان يعيد التشغيل على جهاز التجربة المشغول في تلك اللحظة، فأعدناه، وهذا تذكير بأن أوامر kubectl نفسها تحتاج إعادة محاولة في السكربتات.

![خط زمني من التجربة: db بعدد نسخ صفر من 47:39 حتى 54:56 ثم Ready، وال api في Error ثم CrashLoopBackOff طوال المدة ويرد nginx بالرمز 502، ثم انتظار 78 ثانية بعد عودة القاعدة حتى عاد ال api في 56:14، والخطأ Error: connect ECONNREFUSED 10.96.105.83:5432](https://arabroot.io/content/images/2026/11/compose-to-k8s-06-db-down.webp)

التطبيق الذي لا يعيد الاتصال يتوقف مع قاعدة البيانات، ويتأخر في العودة بسبب الانتظار المتزايد

والخلاصة أن Kubernetes لا يصلح تطبيقاً لا يعرف كيف يتعامل مع فقد قاعدة البيانات، وإنما يعيد تشغيله، وهذا ينقذك من العطل ولكن ببطء. والحل الصحيح في الكود: التقط أخطاء الاتصال، وأعد الاتصال بفاصل متزايد Backoff، ودع فحص الجاهزية يخرج ال Pod من ال Service أثناء الانقطاع، فيعود التطبيق خلال ثوان من عودة القاعدة بدل دقيقة ونصف. وهذا ما ذكرناه في [قائمة تحقق المطور قبل نشر تطبيقه](https://arabroot.io/articles/%D9%82%D8%A7%D8%A6%D9%85%D8%A9-%D8%AA%D8%AD%D9%82%D9%82-%D8%A7%D9%84%D9%85%D8%B7%D9%88%D8%B1-%D9%82%D8%A8%D9%84-%D9%86%D8%B4%D8%B1-%D8%AA%D8%B7%D8%A8%D9%8A%D9%82%D9%87/)، وهو أهم من أي سطر YAML في هذا المقال.

## النسخ الاحتياطي Backup: الأمر نفسه عبر kubectl exec

في Compose كنت تأخذ نسخة من قاعدة البيانات بالأمر `docker compose exec db pg_dump`، وفي Kubernetes الأمر نفسه تقريباً، والفرق أن kubectl يختار Pod ال Deployment بنفسه:

```bash
kubectl exec -n shop deploy/db -- pg_dump -U shop -d shop --schema-only | grep -E '^CREATE TABLE'
kubectl exec -n shop deploy/db -- pg_dump -U shop -d shop -Fc > shop.dump
ls -la shop.dump
```

```text
CREATE TABLE public.seed_info (
CREATE TABLE public.visits (

-rw-r--r-- 1 wajdy 197609 3195 Nov 18 23:21 shop.dump
```

والنسخة بالصيغة المضغوطة `-Fc` خرجت من ال Pod عبر kubectl إلى ملف على جهازنا، وحجمها 3195 بايت لأن البيانات صغيرة. ولم نحتج كلمة مرور لأن الأمر يعمل داخل Container قاعدة البيانات نفسه عبر ال Socket. ولكن لاحظ أن هذا أمر تكتبه بيدك، وفي Compose كما في Kubernetes تحتاج أن تجعله يعمل وحده كل يوم، وفي Kubernetes مكانه كائن CronJob يشغل `pg_dump` ويرسل الملف خارج العنقود، والمبادئ نفسها التي شرحناها في [نسخ قواعد البيانات بشكل متسق](https://arabroot.io/articles/%D9%86%D8%B3%D8%AE-%D9%82%D9%88%D8%A7%D8%B9%D8%AF-%D8%A7%D9%84%D8%A8%D9%8A%D8%A7%D9%86%D8%A7%D8%AA-%D8%A8%D8%B4%D9%83%D9%84-%D9%85%D8%AA%D8%B3%D9%82-pg%5Fdump-%D8%A7%D9%88-mysqldump/) و[قاعدة 3-2-1](https://arabroot.io/articles/%D8%A7%D9%84%D9%86%D8%B3%D8%AE-%D8%A7%D9%84%D8%A7%D8%AD%D8%AA%D9%8A%D8%A7%D8%B7%D9%8A-%D8%A8%D9%82%D8%A7%D8%B9%D8%AF%D8%A9-3-2-1-%D9%88%D8%A7%D8%AE%D8%AA%D8%A8%D8%A7%D8%B1-%D8%A7%D9%84%D8%A7%D8%B3%D8%AA%D8%B9%D8%A7%D8%AF%D8%A9/). ولا تعتبر القرص الدائم نسخة احتياطية، فقد رأيت في القسم السابق أنه مجلد على عقدة واحدة، ويحذف مع ال Namespace.

## ماذا عن ملف .env والمتغير Variable المسمى APP\_VERSION؟

في Compose كان الملف `.env` يحمل `APP_VERSION=1.0.0`، وكان Compose يعوضه في الملف نفسه في وسم ال Image وفي متغير البيئة، فتغير النسخة في مكان واحد. وملفات Kubernetes لا تعرف أي تعويض للمتغيرات، فالكتابة `${APP_VERSION}` في YAML تصل إلى ال API Server كما هي، ولذلك كتبنا `1.0.0` في ثلاثة أماكن: وسم ال Image في ال API، ووسمها في ال Init Container، ومتغير البيئة. وهذا يعمل في التجربة، ولكنه في مشروع حقيقي يعني أن أحدهم سيغير مكانين وينسى الثالث.

والحلول المعروفة ثلاثة: الأداة Kustomize المدمجة في kubectl بالأمر `kubectl apply -k`، وهي تغير وسم ال Image في كل الملفات من سطر واحد دون قوالب، والأداة Helm التي تحول الملفات إلى قوالب Templates بمتغيرات، ولها مقال مستقل في هذه المرحلة، أو أن يكتب خط النشر الوسم بأداة مثل `kubectl set image` بعد كل بناء. ولا تحاول أن تقلد Compose بأداة مثل `envsubst` على الملفات، والسبب أن الملف الذي في Git لن يكون الملف الذي وصل إلى العنقود، فتخسر الفائدة الأولى من الملفات، وهي أن تقرأ ما يعمل.

## هل يستحق التطبيق Application هذا كله؟

ملف Compose الذي بدأنا منه 138 سطراً، والملفات التي انتهينا إليها 382 سطراً في سبعة ملفات، وكل ما أضفناه كان لحل مشكلة رأيناها. وما الذي حصلنا عليه مقابل ذلك؟ نسختان من ال API وweb على عقدتين، فإذا توقفت عقدة بقي التطبيق يعمل، مع التحفظ الذي رأيناه في مقال Kubernetes من الداخل عن توقيت ذلك. وتحديث تدريجي Rolling Update دون توقف، وإعادة تشغيل تلقائية لكل خدمة تتوقف. أما قاعدة البيانات فما زالت نسخة واحدة على قرص عقدة واحدة، فإذا توقفت تلك العقدة توقف التطبيق كما كان في Compose. فإذا كان تطبيقك يعمل على سيرفر واحد ويكفيه، فراجع [هل تحتاج Kubernetes فعلاً؟](https://arabroot.io/articles/%D9%87%D9%84-%D8%AA%D8%AD%D8%AA%D8%A7%D8%AC-kubernetes-%D9%81%D8%B9%D9%84%D8%A7/) قبل أن تنقله، فالنقل نفسه لا يجعله أفضل.

وفكر أيضاً في العمل اليومي بعد النقل، فهو يتغير أكثر من الملفات. ففي Compose كان كل شيء على سيرفر واحد تصل إليه ب SSH، والسجلات في `docker compose logs`، والتحديث أمر واحد. وفي Kubernetes تحتاج أن يعرف كل من في الفريق السياقات وال Namespaces وترتيب التشخيص الذي شرحناه في مقال kubectl، وتحتاج نظاماً يجمع السجلات لأن ال Pod الذي توقف يأخذ سجله معه، ونظاماً للمراقبة Monitoring لأن الأمر `kubectl top` لا يحفظ تاريخاً، وخط نشر يطبق الملفات ويتابع نتيجتها، وشخصاً مسؤولاً عن ترقية العنقود نفسه كل بضعة أشهر. وهذه تكلفة حقيقية تدفعها كل شهر، وليست مرة واحدة عند النقل.

## أخطاء شائعة Common Mistakes

- **تطبيق مخرج kompose كما هو:** في التجربة لم تعمل إلا Redis، لأن الخدمات دون `ports` لم تحصل على Service.
- **Image مبنية على جهازك فقط:** العقد تسحب من سجل، و`latest` يجعلها تحاول السحب كل مرة.
- **ال Secret بالخيار subPath:** يصبح المسار ملفاً بدل مجلد، ولا يتحدث إذا غيرت كلمة المرور.
- **السر على `/run/secrets` مع رمز الدخول الافتراضي:** لم يبدأ أي Pod، والحل `automountServiceAccountToken: false` أو مسار آخر.
- **نقل `start_period` إلى فحص البدء كما هو:** Kubernetes يقتل الخدمة عند انتهاء المهلة، فقتل قاعدة البيانات مرتين.
- **فحص حياة يعتمد على قاعدة البيانات:** يعيد تشغيل كل نسخ التطبيق كلما توقفت القاعدة.
- **قاعدة بيانات بالاستراتيجية RollingUpdate:** خادمان على نفس مجلد البيانات، والصحيح Recreate.
- **ترحيل في Init Container مع عدة نسخ دون قفل:** يعمل مرتين في وقت واحد.
- **NetworkPolicy دون اختبار:** قبلها العنقود ولم تعمل، والاختبار ب `nc` هو الذي كشف ذلك.
- **متغيرات بأسماء مثل `DB_PORT`:** يكتبها ال kubelet لكل Service، والحل `enableServiceLinks: false`.
- **حذف ال Namespace في الإنتاج:** سياسة الاسترجاع Reclaim Policy `Delete` في موفر التخزين تحذف القرص وبياناته معه.

## قائمة تحقق Checklist للنقل

| البند                                                  | كيف تتحقق                                                        |
| ------------------------------------------------------ | ---------------------------------------------------------------- |
| Service لكل خدمة يتصل بها غيرها، بنفس اسمها في Compose | kubectl get svc -n NS، وnslookup NAME من Pod                     |
| ال Images في سجل تصل إليه العقد بوسم ثابت              | لا يوجد ImagePullBackOff، ولا latest                             |
| الأسرار من ملفات خارج Git، ومركبة كمجلد                | kubectl exec … ls -la على المسار، ولا كلمة مرور في أي YAML       |
| رمز الدخول ملغى في ال Pods التي لا تحتاجه              | automountServiceAccountToken: false                              |
| ثلاثة فحوص بمهلة بدء أطول من أسوأ بدء                  | إعادات التشغيل صفر في أول تثبيت على Namespace فارغ               |
| فحص الحياة لا يعتمد على خدمة أخرى                      | أوقف القاعدة، وتأكد أن الخدمات الأخرى لا تعيد التشغيل بسبب الفحص |
| قاعدة البيانات Recreate مع قرص                         | البيانات باقية بعد scale 0 ثم scale 1                            |
| حدود الذاكرة مختبرة                                    | الرمز 137 عند التجاوز، وسجل النواة على العقدة                    |
| سياسات الشبكة مختبرة                                   | nc -z من Pod يجب أن يمنع                                         |
| التطبيق يعيد الاتصال                                   | يعود خلال ثوان من عودة القاعدة دون CrashLoopBackOff              |

## حذف المختبر Cleanup

حذف ال Namespace يحذف كل ما فيه، ومعه القرصان لأن سياسة الاسترجاع `Delete`، ثم نحذف العنقود كله وال Image التي بنيناها:

```bash
kubectl delete namespace shop
kind delete cluster --name k1
docker network rm k1-net
docker image rm k1-shop-api:1.0.0
```

## الخلاصة Summary

وصلنا لنهاية الموضوع، وأهم ما فيه:

- كل خدمة في Compose أصبحت Deployment وService بنفس الاسم، فلم يتغير أي إعداد في التطبيق، والملفات أصبحت ConfigMaps، والسر Secret من ملف خارج Git مركب كمجلد على نفس المسار.
- kompose أنتج ثلاثة عشر ملفاً في ثانية، ولكن لم تعمل إلا Redis: لا Services للخدمات الداخلية، وسر مركب كملف، وفحص حياة فقط، وترحيل لا ينتظر أحداً.
- المسار `/run/secrets` تعارض مع رمز الدخول الذي يركبه ال kubelet، وفحص البدء بمهلة Compose قتل قاعدة البيانات مرتين، والحل في الحالتين سطر واحد عرفناه من رسالة الخطأ.
- الترحيل في Init Container يعاد حتى تجهز القاعدة دون أي كود انتظار، وهو أبطأ من شرط Compose ولكنه يعمل عند كل بدء.
- سياسة الشبكة قبلها العنقود ولم تعمل، والتطبيق الذي لا يعيد الاتصال توقف مع القاعدة وعاد بعدها بدقيقة ونصف، فاختبر كل ما تكتبه، وأصلح ما يجب إصلاحه في الكود.

وفي المقالات القادمة من هذه المرحلة بإذن الله سوف نكمل ما بدأناه هنا: ال ConfigMaps وال Secrets بالتفصيل، ثم Ingress وشهادات HTTPS لنستبدل port-forward، ثم Helm وحدود الموارد والتوسع التلقائي.

[![](https://arabroot.io/content/images/2026/11/compose-best-practices-cover-cover.webp)دليلأفضل الممارسات Best Practices في ملفات Docker Composeكيف تكتب ملف Compose يبدأ خدماته بالترتيب الصحيح ويحمي كلمات المرور ويضبط الذاكرة ويفصل التطوير عن الإنتاج، مع تجربة أظهرت أين يخدعك كل إعداد افتراضي.](https://arabroot.io/articles/%D8%A7%D9%81%D8%B6%D9%84-%D8%A7%D9%84%D9%85%D9%85%D8%A7%D8%B1%D8%B3%D8%A7%D8%AA-%D9%81%D9%8A-%D9%85%D9%84%D9%81%D8%A7%D8%AA-docker-compose/)[![](https://arabroot.io/content/images/2026/11/kubectl-basics-cover-cover.webp)دليلkubectl للمبتدئين: الأوامر التي تستخدمها كل يومالأوامر التي تكتبها كل يوم على عنقود Kubernetes بالترتيب الذي تحتاجها فيه، مع إعادة إنتاج CrashLoopBackOff وImagePullBackOff وإصلاحهما على عنقود حقيقي.](https://arabroot.io/articles/%D8%A7%D9%88%D8%A7%D9%85%D8%B1-kubectl-%D8%A7%D9%84%D9%8A%D9%88%D9%85%D9%8A%D8%A9-%D9%84%D9%84%D9%85%D8%A8%D8%AA%D8%AF%D8%A6%D9%8A%D9%86/)[![](https://arabroot.io/content/images/2026/11/k8s-architecture-cover-cover.webp)دليلKubernetes من الداخل: Control Plane وetcd والعقد Nodesعنقود حقيقي من ثلاث عقد نفتحه من الداخل، فنقرأ etcd ونشاهد حلقة التحكم والمجدول، ثم نوقف عقدة ونقيس كم احتاج العنقود ليلاحظ وماذا تعطل في الطريق.](https://arabroot.io/articles/%D9%83%D9%8A%D9%81-%D9%8A%D8%B9%D9%85%D9%84-kubernetes-%D9%85%D9%86-%D8%A7%D9%84%D8%AF%D8%A7%D8%AE%D9%84-control-plane-%D9%88-etcd/)[![](https://arabroot.io/content/images/2026/10/k8s-need-cover-cover.webp)دليلهل تحتاج Kubernetes فعلاً؟ متى يكفي Docker Composeما الذي يحله Kubernetes وما الذي يكلفك، ومتى يكفيك Docker Compose على سيرفر واحد أو بضعة سيرفرات.](https://arabroot.io/articles/%D9%87%D9%84-%D8%AA%D8%AD%D8%AA%D8%A7%D8%AC-kubernetes-%D9%81%D8%B9%D9%84%D8%A7/)[![](https://arabroot.io/content/images/2026/10/cloudnativepg-cover-cover.webp)دليلPostgreSQL على Kubernetes مع CloudNativePGكيف يدير CloudNativePG عنقود PostgreSQL على Kubernetes بنسخ متماثلة وانتقال تلقائي ونسخ احتياطي، وما الذي يحدث عندما يتوقف الرئيسي.](https://arabroot.io/articles/postgresql-%D8%B9%D9%84%D9%89-kubernetes-%D9%85%D8%B9-cloudnativepg/)[![](https://arabroot.io/content/images/2026/10/dev-checklist-cover-cover.webp)دليلقبل أن تنشر تطبيقك على خادمك: قائمة تحقق للمطورالأخطاء التي لا تظهر إلا بعد نشر تطبيقك في Docker خلف Reverse Proxy، وكيف تعالج كل واحد منها قبل أن يصل إلى المستخدمين.](https://arabroot.io/articles/%D9%82%D8%A7%D8%A6%D9%85%D8%A9-%D8%AA%D8%AD%D9%82%D9%82-%D8%A7%D9%84%D9%85%D8%B7%D9%88%D8%B1-%D9%82%D8%A8%D9%84-%D9%86%D8%B4%D8%B1-%D8%AA%D8%B7%D8%A8%D9%8A%D9%82%D9%87/)

## سجل التحديثات Changelog

- 18 نوفمبر 2026: كتابة المقال، وتنفيذ التجربة على kind 0.33.0 بالإصدار Kubernetes 1.36.4 مع kubectl v1.36.1 وkompose 1.38.0، وال Images postgres:18.6-alpine وredis:8.10.3-alpine وnginx:1.29.8-alpine وال API من مقال Compose على node:24-alpine.