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

وهذا الجدول يكمل الرسم بالأجزاء الأصغر التي ستحتاجها:
| في 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 مشروع رسمي من مشاريع Kubernetes يحول ملف Compose إلى ملفات YAML، والإصدار Version الذي جربناه 1.38.0. ونسخنا مجلد Directory التطبيق من مقال Compose كما هو، ثم شغلناها عليه:
kompose version
kompose convert -f compose.yaml -o kompose-out/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. أما kompose فيقرأ غياب ports كأن الخدمة لا يصل إليها أحد، فلا ينشئ لها Service، أي أن الاسم db لن يوجد في العنقود. وطبقنا الملفات كما هي في Namespace منفصل لنرى النتيجة:
kubectl create namespace kompose
kubectl apply -n kompose -f kompose-out/
kubectl get pods,svc,pvc -n komposeNAME 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:
kubectl logs -n kompose deploy/web --tail=2
kubectl describe pod -n kompose migrate | grep -E 'Failed' | head -12026/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 والترحيل فقط، ثم طبقناهما من جديد:
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 -4NAME 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 وجدنا هذا الجزء:
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 أربع مشاكل أخرى لا تظهر كخطأ، ولكنها أخطر لأنها تعمل:
- فحص الصحة أصبح 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 كله، وكتبنا الملفات بأنفسنا، وهذا ما تبقى من المقال.
kubectl delete namespace komposeال Image: من build إلى سجل Registry تصل إليه العقد
في Compose يكفي build: ./api لأن Docker الذي يبني هو نفسه الذي يشغل، أما في Kubernetes فكل عقدة تسحب ال Image بنفسها، فيجب أن تكون في سجل Registry تصل إليه كل العقد، مثل سجل خاص تشغله بنفسك أو سجل مزود السحابة. وفي kind يقوم الأمر kind load docker-image بهذا الدور، فينسخ ال Image من Docker على جهازك إلى containerd داخل العقد التي تحددها:
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-worker2Image: "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 صحيح، وتصغير ال Image موضوع تقليل حجم Docker Images وتأمينها، ولن نغير فيهما شيئاً هنا.
ال Namespace والإعدادات Configuration في ConfigMap والسر Secret
كل كائنات التطبيق في Namespace واحد اسمه shop، فيظهر كله بأمر واحد ويحذف بأمر واحد:
# 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، فإذا تغير ملف أعدنا التوليد:
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.yamlapiVersion: 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:
kubectl create secret generic db-password -n shop --from-file=db_password=secrets/db_password.txt
kubectl get secret db-password -n shopsecret/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. وفي Kubernetes تطلب القرص بكائن اسمه PersistentVolumeClaim، أي «أحتاج قرصاً بهذا الحجم»، فينشئ موفر التخزين Storage Provisioner قرصاً PersistentVolume ويربطه به، وفي kind الموفر هو local-path الذي ينشئ مجلداً على العقدة. وهذا ملف قاعدة البيانات كاملاً:
# 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، وStatefulSets لها مقال مستقل في هذه المرحلة.
أين البيانات Data فعلاً؟
طلبنا في ال PersistentVolumeClaim قرصاً بحجم 1Gi، فماذا أعطانا موفر التخزين؟ لننظر إلى ال PersistentVolume الذي أنشأه، وإلى ما تراه PostgreSQL من داخل ال Container:
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 -1NAME 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 ولا الترحيل:
kubectl get pod -n shop -l app=api -o jsonpath='{.items[0].status.initContainerStatuses[0].lastState.terminated.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/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. وبعد إضافة السطر أصبح المجلد كما في Compose:
kubectl exec -n shop deploy/api -c api -- ls -la /run/secrets/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:
| الفحص | السؤال | إذا فشل | يقابله في 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:
kubectl describe pod -n shop -l app=db | sed -n '/Last State/,/Restart Count/p;/Events:/,$p' 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وسجل المحاولة الثانية يشرح لماذا أصبح الأمر أسوأ بعد القتل الأول:
kubectl logs -n shop deploy/db --previous | head -12PostgreSQL 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 المتكررة، فهي رد الخادم على كل فحص. والقصة كما يلي:
- في التشغيل الأول أنهت PostgreSQL إنشاء ملفاتها وسكربت التهيئة، وأصبحت جاهزة في 19:12:22، وهذا السطر
last known up، ولكن مهلة الستين ثانية كانت قد انتهت قبلها بلحظات، فقرر ال kubelet قتلها، وانتهى القتل بالإشارة Signal المسماة SIGKILL والرمز 137. - في التشغيل الثاني وجدت PostgreSQL أنها توقفت فجأة
database system was interrupted، فبدأت إصلاح ما بعد التوقف المفاجئ Crash Recovery، وأوله أن تكتب كل ملفات المجلد إلى القرصsyncing data directory (fsync)، فأخذ هذا وحده أكثر من 35 ثانية، فانتهت المهلة Timeout مرة أخرى وقتلت مرة أخرى في 22:14:26. - في التشغيل الثالث وجدت الملفات أكثر استقراراً فبدأت أسرع، وأصبحت جاهزة قبل نهاية المهلة.

وهذه حلقة تزداد سوءاً مع كل دورة، ولو كان القرص أبطأ قليلاً لما خرجت منها أبداً. والدرس أن مهلة فحص البدء ليست رقماً تنقله من 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. فجعلنا الترحيل Init Container في Pod ال API نفسه، بنفس ال Image وبالأمر node migrate.js:
# 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 بالوقت:
kubectl apply -f k8s/
kubectl get pods -n shop -w22: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وسجل محاولة فاشلة للترحيل، وهذا من تشغيل سابق بنفس الملفات، ثم سجل المحاولة الناجحة في التشغيل الأخير:
kubectl logs -n shop api-6db8479cd8-9gmn2 -c migrate
kubectl logs -n shop deploy/api -c migrateError: 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 عمره أربع دقائق وإعاداته صفر.

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

kubectl get pods,svc,pvc -n shopNAME 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:
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<!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. وتحققنا أيضاً أن سكربت التهيئة عمل مرة واحدة في أول تشغيل:
kubectl exec -n shop deploy/db -- psql -U shop -d shop -c 'select count(*) from visits' -c 'select * from seed_info' count
-------
4
(1 row)
loaded_at
-------------------------------
2026-11-18 19:42:21.560571+00
(1 row)وهذه القراءة بعد أن أوقفنا قاعدة البيانات وأعدناها في القسم التالي، والعدد 4 يعني أن البيانات بقيت على القرص رغم أن Pod القاعدة أصبح Pod جديداً باسم جديد.
مفاجأة صغيرة في متغيرات البيئة Environment Variables
عندما فحصنا المتغيرات داخل ال API لنتأكد أن ال ConfigMap وصل، وجدنا متغيرات لم نكتبها:
kubectl exec -n shop deploy/api -c api -- sh -c 'env | grep -E "^(DB_|REDIS_|APP_)" | sort'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:
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}'holding 50 MB
holding 100 MB
api restarts=1 last=Error/13722: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 ثانية. وسجل النواة على العقدة يؤكد ذلك:
docker exec k1-worker sh -c 'dmesg | grep -E "Memory cgroup out of memory" | tail -1'[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 كما في صفحة سياسات الشبكة:
# 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 دون أي خطأ، ثم اختبرناها:
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'NAME POD-SELECTOR AGE
db-redis-from-api-only app in (db,redis) 25m
web-to-db: open
api-to-db: opennginx ما زال يصل إلى قاعدة البيانات، أي أن السياسة موجودة ولا تعمل. والسبب أن سياسات الشبكة لا ينفذها Kubernetes نفسه، وإنما إضافة الشبكة CNI، فإذا كانت الإضافة لا تدعمها أو لم تستطع تطبيقها قبلها ال API Server وحفظها ولم يحدث شيء. وفي التجربة كتبت إضافة kindnet هذا في سجلها:
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:
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 -5deployment.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 لا يرد. ثم أعدنا قاعدة البيانات:
kubectl scale deploy/db -n shop --replicas=1
# poll every 5 s: ready replicas of db and api22: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 نفسها تحتاج إعادة محاولة في السكربتات.

والخلاصة أن Kubernetes لا يصلح تطبيقاً لا يعرف كيف يتعامل مع فقد قاعدة البيانات، وإنما يعيد تشغيله، وهذا ينقذك من العطل ولكن ببطء. والحل الصحيح في الكود: التقط أخطاء الاتصال، وأعد الاتصال بفاصل متزايد Backoff، ودع فحص الجاهزية يخرج ال Pod من ال Service أثناء الانقطاع، فيعود التطبيق خلال ثوان من عودة القاعدة بدل دقيقة ونصف. وهذا ما ذكرناه في قائمة تحقق المطور قبل نشر تطبيقه، وهو أهم من أي سطر YAML في هذا المقال.
النسخ الاحتياطي Backup: الأمر نفسه عبر kubectl exec
في Compose كنت تأخذ نسخة من قاعدة البيانات بالأمر docker compose exec db pg_dump، وفي Kubernetes الأمر نفسه تقريباً، والفرق أن kubectl يختار Pod ال Deployment بنفسه:
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.dumpCREATE 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 ويرسل الملف خارج العنقود، والمبادئ نفسها التي شرحناها في نسخ قواعد البيانات بشكل متسق وقاعدة 3-2-1. ولا تعتبر القرص الدائم نسخة احتياطية، فقد رأيت في القسم السابق أنه مجلد على عقدة واحدة، ويحذف مع ال 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 فعلاً؟ قبل أن تنقله، فالنقل نفسه لا يجعله أفضل.
وفكر أيضاً في العمل اليومي بعد النقل، فهو يتغير أكثر من الملفات. ففي 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 التي بنيناها:
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 وحدود الموارد والتوسع التلقائي.
دليلأفضل الممارسات Best Practices في ملفات Docker Composeكيف تكتب ملف Compose يبدأ خدماته بالترتيب الصحيح ويحمي كلمات المرور ويضبط الذاكرة ويفصل التطوير عن الإنتاج، مع تجربة أظهرت أين يخدعك كل إعداد افتراضي.
دليلkubectl للمبتدئين: الأوامر التي تستخدمها كل يومالأوامر التي تكتبها كل يوم على عنقود Kubernetes بالترتيب الذي تحتاجها فيه، مع إعادة إنتاج CrashLoopBackOff وImagePullBackOff وإصلاحهما على عنقود حقيقي.
دليلKubernetes من الداخل: Control Plane وetcd والعقد Nodesعنقود حقيقي من ثلاث عقد نفتحه من الداخل، فنقرأ etcd ونشاهد حلقة التحكم والمجدول، ثم نوقف عقدة ونقيس كم احتاج العنقود ليلاحظ وماذا تعطل في الطريق.
دليلهل تحتاج Kubernetes فعلاً؟ متى يكفي Docker Composeما الذي يحله Kubernetes وما الذي يكلفك، ومتى يكفيك Docker Compose على سيرفر واحد أو بضعة سيرفرات.
دليلPostgreSQL على Kubernetes مع CloudNativePGكيف يدير CloudNativePG عنقود PostgreSQL على Kubernetes بنسخ متماثلة وانتقال تلقائي ونسخ احتياطي، وما الذي يحدث عندما يتوقف الرئيسي.
دليلقبل أن تنشر تطبيقك على خادمك: قائمة تحقق للمطورالأخطاء التي لا تظهر إلا بعد نشر تطبيقك في Docker خلف Reverse Proxy، وكيف تعالج كل واحد منها قبل أن يصل إلى المستخدمين.سجل التحديثات 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.