# کوبرنتیز چیست؟ معماری، تفاوت با داکر و آموزش نصب k3s روی سرور

> کوبرنتیز چیست و چه زمانی به آن نیاز دارید؟ معماری، تفاوت با داکر، نصب k3s روی اوبونتو با YAML و Ingress، نکات سرور ایران و رفع خطاهای رایج.

- صفحه: https://hakanserver.com/what-is-kubernetes/
- تاریخ انتشار: ۹ آبان ۱۴۰۵ (2026-10-31)
- دسته: سرور
- زمان مطالعه: حدود 23 دقیقه

![سه نود کوبرنتیز، یک control-plane و دو worker، متصل به سرور؛ نمای ساده از کلاستر کوبرنتیز](https://hakanserver.com/wp-content/uploads/2026/10/what-is-kubernetes.jpg)

کوبرنتیز چیست؟ کوبرنتیز (Kubernetes یا K8s) نرم‌افزاری متن‌باز برای اجرا و مدیریت کانتینرها روی یک یا چند سرور است: شما می‌نویسید چه برنامه‌ای با چند نسخه اجرا شود و کوبرنتیز جای اجرا، ری‌استارت کانتینر خراب، توزیع بار و به‌روزرسانی بدون قطعی را خودکار انجام می‌دهد.

در این راهنما معماری کوبرنتیز و زمان نیاز به آن را می‌بینید و در بخش عملی، k3s را روی Ubuntu 24.04 نصب می‌کنید و یک برنامه را منتشر، به‌روز و بازگردانی می‌کنید. نکته‌های سرورهای داخل ایران بخش جداگانه‌ای دارد و دستورها در آبان ۱۴۰۵ با مستندات رسمی تطبیق داده شده‌اند.

> **به‌طور خلاصه:** وضعیت مطلوب را (مثلاً «۳ نسخه از این ایمیج، پشت یک آدرس ثابت») در فایل YAML می‌نویسید و کوبرنتیز مدام وضعیت واقعی را به آن می‌رساند.
> 
> 
> 
> - داکر ایمیج می‌سازد و کانتینر را روی یک سرور اجرا می‌کند؛ کوبرنتیز همان ایمیج‌ها را روی چند نود مدیریت می‌کند.
> - برای یک سایت یا اپ کوچک، Docker Compose روی یک سرور کافی است.
> - برای شروع روی سرور، k3s کم‌دردسر است؛ نود سرور آن طبق مستندات دست‌کم ۲ هستهٔ CPU و ۲ گیگابایت رم می‌خواهد.
> - روی سرور ایران حتی ایمیج‌های سیستمی k3s از Docker Hub می‌آیند؛ پیش از نصب، میرور یا نصب آفلاین را آماده کنید.

## کوبرنتیز چیست و چه مشکلی را حل می‌کند؟

نام کوبرنتیز (که کوبرنتیس هم نوشته می‌شود) از واژه‌ای یونانی به معنای سکان‌دار است و K8s شکل کوتاه آن است: ۸ حرف بین K و s. گوگل آن را در ۲۰۱۴ متن‌باز کرد و امروز از پروژه‌های بالغ (Graduated) بنیاد CNCF است.

اجرای چند کانتینر روی یک سرور با داکر ساده است. مشکل از ده‌ها کانتینر روی چند سرور شروع می‌شود: هر کانتینر کجا اجرا شود، با خاموش شدن یک سرور چه شود، نسخهٔ جدید چطور بدون قطعی جایگزین شود و سرویس‌ها با IPهای متغیر چطور همدیگر را پیدا کنند. کوبرنتیز این کارها را خودکار می‌کند:

- **زمان‌بندی (Scheduling):** هر کانتینر را بر اساس CPU و رمی که لازم دارد، روی سروری (نود) با ظرفیت کافی اجرا می‌کند.
- **خودترمیمی (Self-healing):** کانتینر خراب را دوباره اجرا می‌کند و اگر نودی از دسترس خارج شود، به‌طور پیش‌فرض حدود ۵ دقیقه بعد کانتینرهایش را روی نودهای سالم می‌سازد.
- **مقیاس‌دهی (Scaling):** تعداد نسخه‌ها را دستی یا خودکار بر اساس مصرف CPU تغییر می‌دهد.
- **به‌روزرسانی تدریجی و بازگشت (Rolling Update و Rollback):** نسخهٔ جدید را کم‌کم جایگزین می‌کند و با یک دستور به نسخهٔ قبل برمی‌گردد.
- **کشف سرویس و توزیع بار:** به هر گروه کانتینر نام DNS و IP ثابت می‌دهد و درخواست‌ها را بینشان پخش می‌کند.

کوبرنتیز پلتفرم کامل و آماده (PaaS) نیست: کد را build نمی‌کند (این کار CI/CD است)، دیتابیس آماده نمی‌دهد و ابزار لاگ و مانیتورینگ را خودتان انتخاب می‌کنید.

## تفاوت داکر و کوبرنتیز

داکر (Docker) ایمیج می‌سازد و کانتینر را روی یک سرور اجرا می‌کند و Docker Compose چند کانتینر مرتبط را روی همان سرور بالا می‌آورد. کوبرنتیز همان ایمیج‌ها را روی یک کلاستر (Cluster)، یعنی گروهی از سرورها، اجرا و مدیریت می‌کند؛ پس رقیب نیستند و معمولاً ایمیج با داکر ساخته و با کوبرنتیز اجرا می‌شود. برای چند سرور، حالت Swarm خود Docker Engine هم هست که ساده‌تر است، اما امکانات کمتری دارد. نصب داکر و Compose در [آموزش نصب داکر روی اوبونتو](https://hakanserver.com/install-docker-ubuntu/) آمده است.

آموزش‌های قدیمی این نکته را ندارند: کوبرنتیز کانتینر را با یک محیط اجرای سازگار با رابط CRI (Container Runtime Interface)، معمولاً containerd یا CRI-O، اجرا می‌کند و اتصال مستقیمش به Docker Engine (به نام dockershim) از نسخهٔ 1.24 در سال ۲۰۲۲ حذف شده است. ایمیج‌های داکر استاندارد OCI هستند و بدون تغییر روی کوبرنتیز اجرا می‌شوند.

| ویژگی | Docker Compose | کوبرنتیز |
| --- | --- | --- |
| خرابی کانتینر | ری‌استارت با restart policy | ری‌استارت خودکار و جایگزینی پاد ازدست‌رفته |
| خرابی سرور | همه‌چیز متوقف می‌شود | پادها روی نودهای سالم دیگر ساخته می‌شوند |
| به‌روزرسانی | معمولاً با قطعی کوتاه | تدریجی، با بازگشت یک‌دستوری |

## معماری کوبرنتیز: لایهٔ کنترل و نودها

هر کلاستر یک لایهٔ کنترل (Control Plane) دارد که تصمیم می‌گیرد و نودهای کارگر (Worker Node) که کانتینرها را اجرا می‌کنند. در کلاستر کوچک هر دو روی یک سرورند و k3s روی نود سرور هم برنامه اجرا می‌کند.

| جزء | محل | وظیفه |
| --- | --- | --- |
| kube-apiserver | لایهٔ کنترل | درِ ورود کلاستر؛ همهٔ درخواست‌ها از API آن می‌گذرند |
| etcd | لایهٔ کنترل | پایگاه‌دادهٔ وضعیت کلاستر (در k3s تک‌سرور: SQLite) |
| kube-scheduler | لایهٔ کنترل | انتخاب نود برای پادهای تازه |
| kube-controller-manager | لایهٔ کنترل | کنترلرهایی که وضعیت را به حالت مطلوب می‌رسانند |
| kubelet | هر نود | اجرا و پایش پادهای نود |
| kube-proxy | هر نود، اختیاری | قانون‌های شبکه برای Service |
| Container Runtime | هر نود | اجرای کانتینر، مثلاً containerd |

افزونهٔ شبکه (CNI) مثل Flannel به پادها IP می‌دهد و CoreDNS نام سرویس‌ها را ترجمه می‌کند. با `kubectl apply`، شیء در etcd ذخیره می‌شود، کنترلرها پادها را تعریف می‌کنند، scheduler نود را برمی‌گزیند و kubelet کانتینر را اجرا می‌کند.

## مفاهیم اصلی کوبرنتیز

هر چیزی در کوبرنتیز یک شیء (Object) است که در YAML تعریف می‌شود:

| شیء | کاربرد | مثال |
| --- | --- | --- |
| Pod | کوچک‌ترین واحد اجرا؛ یک یا چند کانتینر با IP مشترک | یک کانتینر وب |
| Deployment و ReplicaSet | تعداد ثابتی پاد یکسان، با به‌روزرسانی تدریجی و بازگشت | اپ بدون حالت |
| StatefulSet | پادهایی با نام و دیسک ثابت | دیتابیس |
| DaemonSet | یک پاد روی هر نود | جمع‌آوری لاگ |
| Job و CronJob | کار یک‌باره یا زمان‌بندی‌شده | بکاپ شبانه |
| Service | IP و نام DNS ثابت جلوی پادها | `web.default.svc.cluster.local` |
| Ingress | مسیریابی HTTP بر اساس دامنه و مسیر | `app.example.com` |
| ConfigMap و Secret | تنظیمات و اطلاعات حساس، بیرون از ایمیج | رمز دیتابیس |
| Namespace | جداسازی منطقی منابع | `dev` و `prod` |
| PV و PVC | فضای ذخیرهٔ ماندگار و درخواست آن | ۱۰ گیگابایت دیسک |

پادها موقتی‌اند و هر پاد تازه IP تازه می‌گیرد؛ برای همین پاد را با Deployment می‌سازید و با Service به آن وصل می‌شوید. Service پادها را با برچسب (Label) پیدا می‌کند: هر پادی که برچسب‌های انتخابگرش (Selector) را داشته باشد.

### انواع Service

- **ClusterIP (پیش‌فرض):** فقط از داخل کلاستر در دسترس است؛ مثلاً برای اتصال اپ به دیتابیس.
- **NodePort:** پورتی ثابت روی همهٔ نودها، به‌طور پیش‌فرض از بازهٔ 30000 تا 32767.
- **LoadBalancer:** انتشار با لود بالانسر بیرونی که خود کوبرنتیز ندارد؛ در ابرها لود بالانسر ارائه‌دهنده و در k3s، ServiceLB با پورت‌های خود نودها این کار را می‌کند.

### Ingress، Gateway API و پایان ingress-nginx

Ingress درخواست‌های HTTP را بر اساس دامنه و مسیر به Serviceها می‌فرستد و بدون Ingress Controller کاری نمی‌کند؛ k3s کنترلر Traefik را خودش نصب می‌کند. در زمان نگارش این مطلب (آبان ۱۴۰۵) دو تغییر مهم است:

- **API مربوط به Ingress منجمد شده است:** حذف نمی‌شود، اما امکان تازه‌ای هم نمی‌گیرد. جانشین پیشنهادی Gateway API است که از ۲۰۲۳ نسخهٔ پایدار v1 دارد و با منابعی مثل Gateway و HTTPRoute کار می‌کند. Gateway API افزونه‌ای جداست؛ Traefik همراه k3s از آن پشتیبانی می‌کند، اما به‌طور پیش‌فرض خاموش است.
- **ingress-nginx بازنشسته شد:** طبق [اعلام رسمی کوبرنتیز](https://kubernetes.io/blog/2025/11/11/ingress-nginx-retirement/)، این کنترلر محبوب از مارس ۲۰۲۶ نسخهٔ جدید، رفع باگ و وصلهٔ امنیتی نمی‌گیرد و مخزنش فقط‌خواندنی است. نصب‌های موجود کار می‌کنند، اما توصیهٔ رسمی مهاجرت به Gateway API یا کنترلری دیگر است. NGINX Ingress Controller شرکت F5 پروژهٔ جدایی است و همچنان به‌روز می‌شود. بررسی استفاده:

```
kubectl get pods --all-namespaces --selector app.kubernetes.io/name=ingress-nginx
```

### Secret فقط base64 است

base64 رمزنگاری نیست و با `base64 -d` برمی‌گردد. طبق مستندات کوبرنتیز، Secretها به‌طور پیش‌فرض رمزنشده در etcd ذخیره می‌شوند و هر کس اجازهٔ ساخت پاد در یک Namespace را داشته باشد، عملاً Secretهای آن را هم می‌خواند. رمزنگاری در حالت ذخیره (Encryption at Rest) را روشن کنید (در k3s در گام ۱ بخش عملی)، دسترسی‌ها را با RBAC (کنترل دسترسی بر اساس نقش) محدود کنید و Secret را در گیت نگذارید.

## آیا به کوبرنتیز نیاز دارید؟

منصفانه بگوییم: بیشتر سایت‌ها و اپ‌های کوچک و متوسط به آن نیاز ندارند. یک سایت وردپرسی، یک API با دیتابیسش یا یک ربات، با Docker Compose روی یک سرور مجازی ساده‌تر و کم‌هزینه‌تر اجرا می‌شود. کوبرنتیز سربار دارد: لایهٔ کنترل خودش منابع می‌خواهد، یادگیری‌اش زمان می‌برد و کلاستر دست‌کم سالی یک بار ارتقا می‌خواهد.

| وضعیت شما | پیشنهاد |
| --- | --- |
| یک سایت یا اپ با دیتابیس | Docker Compose روی یک سرور |
| چند سرویس روی یک سرور | Compose، یا k3s تک‌نود برای یادگیری |
| چند سرویس و چند توسعه‌دهنده با استقرار مکرر | کوبرنتیز (k3s یا kubeadm) |
| تحمل خرابی یک سرور | دست‌کم ۳ نود سرور |
| نمی‌خواهید کلاستر نگه دارید | سرویس کانتینری مدیریت‌شده (PaaS) |

کلاستر تک‌نود دسترس‌پذیری بالا (HA) نمی‌دهد و حالت HA در k3s با etcd داخلی، تعداد فردی نود سرور می‌خواهد. برای شروع، دیتابیس اصلی را بیرون از کلاستر نگه دارید. کوبرنتیز مدیریت‌شدهٔ ابرهای خارجی هم معمولاً به دلیل تحریم برای کاربران ایرانی در دسترس نیست.

## توزیع‌های کوبرنتیز: kubeadm، k3s، MicroK8s و k0s

هر چهار توزیع زیر کوبرنتیز استاندارد اجرا می‌کنند و فرقشان در بسته‌بندی، پیش‌فرض‌ها و منابع است. حداقل منابع از مستندات رسمی هر پروژه است و مصرف برنامه‌ها جداست:

| توزیع | ویژگی | حداقل منابع | مناسب برای |
| --- | --- | --- | --- |
| kubeadm | ابزار رسمی پروژه؛ runtime و شبکه جدا نصب می‌شوند | ۲ گیگابایت رم هر نود؛ ۲ هسته برای لایهٔ کنترل | کلاستر استاندارد |
| k3s | یک فایل اجرایی زیر ۱۰۰ مگابایت با Traefik و ServiceLB | سرور ۲ هسته و ۲ گیگابایت؛ کارگر ۱ هسته و ۵۱۲ مگابایت | سرور مجازی و کلاستر کوچک |
| MicroK8s | بستهٔ snap شرکت Canonical | از ۵۴۰ مگابایت؛ پیشنهادی ۴ گیگابایت رم | اوبونتو و محیط توسعه |
| k0s | یک فایل اجرایی بدون وابستگی، از Mirantis | کنترلر ۱ گیگابایت؛ کارگر ۰٫۵ گیگابایت | کلاستر چندنودی با k0sctl |

برای تمرین روی لپ‌تاپ kind و minikube کافی‌اند و برای سرور مجازی، k3s معمولاً کم‌دردسرتر است.

## نصب k3s روی اوبونتو، گام‌به‌گام

در این بخش یک کلاستر تک‌نود k3s روی Ubuntu 24.04 می‌سازید، برنامه‌ای منتشر می‌کنید و در پایان یک نود کارگر اضافه می‌کنید. طبق جدول پشتیبانی k3s 1.36 در سایت SUSE، Ubuntu 22.04 و 26.04 هم آزموده شده‌اند.

### پیش‌نیازها و پورت‌ها

- سروری با Ubuntu 24.04 و مجازی‌سازی کامل مثل KVM؛ روی OpenVZ و LXC ممکن است اجرا نشود. نود سرور طبق مستندات دست‌کم ۲ هسته و ۲ گیگابایت رم و ترجیحاً دیسک SSD می‌خواهد؛ برای تمرین، یک [سرور لینوکس](https://hakanserver.com/buy-a-virtual-server/linux-server/) با ۴ گیگابایت رم راحت‌تر است.
- hostname یکتا برای هر نود و دسترسی SSH با کاربر دارای sudo ([آموزش اتصال به سرور لینوکسی از طریق SSH](https://hakanserver.com/connect-to-linux-server-via-ssh/)).
- اگر Nginx یا Apache خود سرور روی پورت‌های 80 و 443 کار می‌کند، Traefik همراه k3s این دو پورت را بی‌صدا از آن می‌گیرد (جدول رفع خطاها).

| پورت | جهت | کاربرد |
| --- | --- | --- |
| 6443/tcp | کارگرها و kubectl به سرور | API کوبرنتیز |
| 8472/udp | بین نودها | Flannel با VXLAN (پیش‌فرض) |
| 51820/udp | بین نودها | Flannel با WireGuard |
| 10250/tcp | بین نودها | kubelet |
| 2379-2380/tcp | بین سرورها | etcd در حالت HA |
| 80 و 443/tcp | اینترنت به نودها | Traefik |

> **هشدار:** طبق مستندات k3s، پورت 8472/udp نباید روی اینترنت باز باشد، چون شبکهٔ داخلی کلاستر را در دسترس همه می‌گذارد؛ 6443 را هم فقط برای IP نودها باز کنید. اگر سرور در ایران است، اول آزمون دسترسی بخش «کوبرنتیز روی سرورهای داخل ایران» را اجرا کنید.

### گام ۱: تنظیمات و نصب k3s

k3s تنظیمات را از `/etc/rancher/k3s/config.yaml` می‌خواند و این فایل، برخلاف پارامترهای دستور نصب، در ارتقاها حفظ می‌شود. این تنظیم رمزنگاری Secretها را از اول روشن می‌کند:

```
sudo mkdir -p /etc/rancher/k3s
sudo tee /etc/rancher/k3s/config.yaml > /dev/null  /dev/null > ~/.bashrc
source ~/.bashrc
kubectl get nodes
```

سراغ `chmod 644` روی `k3s.yaml` نروید؛ دسترسی مدیر را به همهٔ کاربران سرور می‌دهد. k3s گواهی‌های فایل اصلی را به‌روز می‌کند، اما نسخهٔ کپی به‌روز نمی‌شود؛ اگر بعدها خطای گواهی دیدید، کپی را تکرار کنید. با root این گام لازم نیست.

### گام ۳: فایروال

مستندات k3s خاموش کردن UFW را پیشنهاد می‌کند و اگر روشن بماند، باز کردن 6443/tcp و مجاز کردن شبکهٔ پادها (10.42.0.0/16) و سرویس‌ها (10.43.0.0/16) را. روشن ماندن UFW امن‌تر است، چون پورت‌های خود سرور مثل 6443، 10250 و 8472 را از اینترنت می‌بندد. در این راهنما 6443 باز نمی‌شود و kubectl از بیرون با تونل SSH وصل می‌شود:

```
sudo ufw allow OpenSSH
sudo ufw allow from 10.42.0.0/16 to any
sudo ufw allow from 10.43.0.0/16 to any
sudo ufw enable
sudo ufw status
```

پورت‌های 80 و 443 قانون UFW لازم ندارند، چون ServiceLB ترافیک آن‌ها را پیش از قانون‌های ورودی UFW با NAT به Traefik می‌رساند (بخش امنیت). اگر پورت SSH را عوض کرده‌اید، پیش از `enable` آن را باز کنید. مبانی UFW در [فعال‌سازی فایروال در لینوکس](https://hakanserver.com/enabling-firewall-in-linux/) آمده است.

### گام ۴: Deployment و Service

برنامهٔ نمونه `traefik/whoami` است که نام پاد پاسخ‌دهنده را برمی‌گرداند:

```
cat > app.yaml  ingress.yaml  **نکته:** `scale` و `set image` فقط کلاستر را عوض می‌کنند و `kubectl apply -f app.yaml` بعدی، تعداد و نسخه را به مقدار فایل برمی‌گرداند. در کار واقعی فایل را تغییر دهید، در گیت نگه دارید و `apply` کنید.

### گام ۷: افزودن نود کارگر

سرور دوم را با hostname متفاوت در همان لوکیشن آماده کنید (`sudo hostnamectl set-hostname k3s-2`). روی سرور اول توکن را بخوانید و نود جدید را در فایروال مجاز کنید:

```
sudo cat /var/lib/rancher/k3s/server/node-token
sudo ufw allow from WORKER_IP
```

روی نود جدید (برای سرور ایران، اول `registries.yaml` گام ۱ را بسازید):

```
sudo ufw allow OpenSSH
sudo ufw allow from SERVER_IP
sudo ufw allow from 10.42.0.0/16 to any
sudo ufw allow from 10.43.0.0/16 to any
sudo ufw enable
curl -sfL https://get.k3s.io | K3S_URL=https://SERVER_IP:6443 K3S_TOKEN=PASTE_NODE_TOKEN sh -
```

با `K3S_URL`، اسکریپت سرویس `k3s-agent` را نصب می‌کند. `kubectl get nodes` روی سرور اول نود جدید را با ROLES برابر `` و وضعیت Ready نشان می‌دهد.

> **هشدار:** طبق مستندات k3s، هر کس توکن سرور را داشته باشد عملاً مدیر کلاستر است؛ آن را در اسکریپت یا گیت نگذارید. ترافیک بین نودها هم بدون `wireguard-native` گام ۱ رمزنگاری نمی‌شود.

### حذف k3s

اسکریپت حذف، k3s، پادها، پایگاه‌دادهٔ کلاستر و داده‌های local-path را پاک می‌کند:

```
# on a server node
sudo /usr/local/bin/k3s-uninstall.sh
# on a worker (agent) node
sudo /usr/local/bin/k3s-agent-uninstall.sh
```

### دستورات پرکاربرد kubectl

| دستور | کاربرد |
| --- | --- |
| `kubectl get pods -A` | پادهای همهٔ Namespaceها |
| `kubectl describe pod NAME` | جزئیات و رویدادها؛ اولین قدم عیب‌یابی |
| `kubectl logs NAME --previous` | لاگ اجرای قبلی کانتینر ری‌استارت‌شده |
| `kubectl exec -it NAME -- sh` | شل داخل کانتینر (اگر ایمیج شل دارد) |
| `kubectl get events --sort-by=.metadata.creationTimestamp` | رویدادهای اخیر به ترتیب زمان |
| `kubectl port-forward svc/web 8080:80` | دسترسی موقت محلی به سرویس |
| `kubectl top nodes` | مصرف CPU و رم نودها |
| `kubectl delete -f app.yaml` | حذف منابع تعریف‌شده در فایل |

## کوبرنتیز روی سرورهای داخل ایران

Docker Hub آی‌پی‌های ایران را به استناد مقررات صادرات آمریکا مسدود می‌کند و این در کوبرنتیز دو اثر دارد: ایمیج بدون نام رجیستری از `docker.io` گرفته می‌شود و ایمیج‌های سیستمی خود k3s، از `pause` و `coredns` تا `traefik`، هم در `docker.io/rancher` هستند (فهرستشان در `k3s-images.txt` هر نسخه). پس بدون آمادگی، حتی اگر نصب تمام شود، پادهای سیستمی در ContainerCreating یا ImagePullBackOff می‌مانند.

ایمیج‌های رسمی کوبرنتیز (مثلاً برای kubeadm) روی `registry.k8s.io` هستند که ترافیک را به Google Cloud و AWS می‌فرستد و خیلی از ابزارها از `ghcr.io` و `quay.io` می‌آیند؛ دسترسی سرورهای ایران به این‌ها و به GitHub همیشه برقرار نیست. پیش از نصب بسنجید:

```
for u in https://get.k3s.io https://update.k3s.io/v1-release/channels \
  https://github.com/k3s-io/k3s/releases https://registry-1.docker.io/v2/ \
  https://docker.arvancloud.ir/v2/ https://registry.k8s.io/v2/ \
  https://ghcr.io/v2/ https://quay.io/v2/; do
  echo "$(curl -s -o /dev/null -m 10 -w '%{http_code}' "$u") $u"
done
```

کد 200 یا 401 یعنی در دسترس (401 برای رجیستری‌ها عادی است)، 403 یعنی مسدود و 000 یعنی تا ۱۰ ثانیه اتصالی برقرار نشد. اسکریپت نصب از `update.k3s.io` نسخه را می‌پرسد و فایل را از GitHub می‌گیرد.

### میرور Docker Hub با registries.yaml

اگر سه نشانی اول باز است و Docker Hub نه، فایل `registries.yaml` گام ۱ کافی است: k3s آن را هنگام راه‌اندازی می‌خواند و containerd درخواست‌های `docker.io` را اول به میرور می‌فرستد. چند شرکت ایرانی میرور عمومی Docker Hub دارند. نمونهٔ شناخته‌شده‌اش میرور آروان‌کلاد با آدرس `https://docker.arvancloud.ir` است که در زمان نگارش این مطلب (آبان ۱۴۰۵) به درخواست ایمیج‌های `rancher` و `traefik/whoami` پاسخ می‌داد؛ وضعیت امروزش را با آزمون بالا بسنجید.

- فایل را روی همهٔ نودها بسازید و اگر k3s نصب است، سرویس `k3s` یا `k3s-agent` را ری‌استارت کنید. آزمون: `sudo k3s crictl pull traefik/whoami:v1.11.0`.
- containerd در آخر خود `docker.io` را هم امتحان می‌کند، پس خطای kubectl ممکن است 403 خود Docker Hub را نشان دهد حتی وقتی مشکل از میرور است؛ علت واقعی در `/var/lib/rancher/k3s/agent/containerd/containerd.log` نودی است که پاد رویش است.
- این تنظیم فقط `docker.io` را پوشش می‌دهد. میرور واسطهٔ شخص ثالث است؛ فقط ایمیج رسمی با تگ مشخص بگیرید.

### نصب آفلاین k3s (Air-gap)

اگر `get.k3s.io` یا GitHub باز نمی‌شود، فایل‌ها را روی سیستمی با دسترسی، مثلاً سرور لینوکسی خارج از ایران، بگیرید و منتقل کنید. با بستهٔ ایمیج‌های سیستمی، k3s برای اجزای خودش به Docker Hub نیاز ندارد. دستورها برای پردازندهٔ amd64 است. مقدار `V` را با نسخهٔ کانال stable در `https://update.k3s.io/v1-release/channels` یکی کنید (به‌جای `+` بنویسید `%2B`) و فایل‌های گام ۱ را پیش از اجرای `install.sh` بسازید:

```
# On a machine with internet access
V=v1.36.5%2Bk3s1
curl -LO https://github.com/k3s-io/k3s/releases/download/$V/k3s
curl -LO https://github.com/k3s-io/k3s/releases/download/$V/k3s-airgap-images-amd64.tar.zst
curl -LO https://github.com/k3s-io/k3s/releases/download/$V/sha256sum-amd64.txt
curl -Lo install.sh https://get.k3s.io
scp k3s k3s-airgap-images-amd64.tar.zst sha256sum-amd64.txt install.sh user@SERVER_IP:~/

# On the server
cd ~
grep -E ' (k3s|k3s-airgap-images-amd64.tar.zst)$' sha256sum-amd64.txt | sha256sum -c -
sudo mkdir -p /var/lib/rancher/k3s/agent/images/
sudo cp k3s-airgap-images-amd64.tar.zst /var/lib/rancher/k3s/agent/images/
sudo install -m 755 k3s /usr/local/bin/k3s
chmod +x install.sh
INSTALL_K3S_SKIP_DOWNLOAD=true ./install.sh
```

چک‌سام باید برای هر دو فایل `OK` بدهد. برای نود کارگر همین فایل‌ها را منتقل و دستور آخر را با `K3S_URL` و `K3S_TOKEN` اجرا کنید. ارتقا در این روش دستی است: فایل‌های نسخهٔ جدید را جایگزین و اسکریپت را دوباره اجرا کنید. ایمیج برنامه‌ها را هم می‌توانید جای دیگر با `docker save` ذخیره و روی نود با `sudo k3s ctr images import` وارد کنید.

### رجیستری خصوصی یا نود خارج از ایران

برای تیم‌ها راه پایدارتر رجیستری خصوصی است که ایمیج‌های لازم را نگه می‌دارد و در `registries.yaml` به‌عنوان میرور `docker.io`، `ghcr.io` یا `registry.k8s.io` معرفی می‌شود. اگر کاربران بیشتر خارج از ایران‌اند یا کارتان مدام به GitHub وابسته است، نودها را روی [سرور مجازی خارجی](https://hakanserver.com/buy-a-virtual-server/buying-a-foreign-virtual-server/) بگذارید.

## رفع خطاهای رایج کوبرنتیز

اول `kubectl describe pod NAME` را بزنید و بخش Events انتهای خروجی را بخوانید.

| نشانه | علت محتمل | راه‌حل |
| --- | --- | --- |
| ImagePullBackOff با 403 | رجیستری IP ایران را نمی‌پذیرد | میرور یا نصب آفلاین |
| ImagePullBackOff با not found | نام یا تگ ایمیج اشتباه | بررسی تگ در رجیستری |
| ImagePullBackOff با 429 | سقف دریافت Docker Hub | ورود به حساب یا میرور |
| CrashLoopBackOff | برنامه پس از شروع خارج می‌شود | `kubectl logs NAME --previous` |
| OOMKilled | مصرف رم بیشتر از `limits` | افزایش limits یا رفع نشت حافظه |
| Pending با Insufficient cpu یا memory | منابع آزاد کمتر از requests | کم کردن requests یا افزودن منابع |
| سایت Nginx یا Apache خود سرور بعد از نصب k3s، `404 page not found` می‌دهد | ServiceLB پورت‌های 80 و 443 را با NAT به Traefik داده است | خط `disable: traefik` در `config.yaml` و ری‌استارت k3s، یا انتقال سایت به کلاستر |
| نود NotReady | `k3s-agent` متوقف یا فایروال بین نودها | `sudo journalctl -u k3s-agent` و جدول پورت‌ها |
| `404 page not found` | Host درخواست با Ingress جور نیست | بررسی `host` و `ingressClassName` |
| permission denied روی `k3s.yaml` | `KUBECONFIG` تنظیم نشده | گام ۲ |

کوبرنتیز دریافت ایمیج و ری‌استارت کانتینر خراب را با فاصلهٔ رو به افزایش، تا سقف ۵ دقیقه، تکرار می‌کند؛ بعد از رفع علت، صبر کنید یا پاد را حذف کنید تا پاد تازه ساخته شود.

## امنیت و نگهداری کلاستر

- **API را عمومی نکنید.** برای kubectl روی کامپیوتر خودتان، kubeconfig گام ۲ را کپی کنید (با root، خود `/etc/rancher/k3s/k3s.yaml` را) و تونل SSH بزنید؛ آدرس داخل فایل `https://127.0.0.1:6443` است و بدون تغییر کار می‌کند. نسخهٔ kubectl شما حداکثر یک نسخهٔ فرعی با سرور فاصله داشته باشد:

```
mkdir -p ~/.kube
scp user@SERVER_IP:.kube/config ~/.kube/k3s-server.yaml
chmod 600 ~/.kube/k3s-server.yaml
ssh -N -L 6443:127.0.0.1:6443 user@SERVER_IP
# in a second terminal
export KUBECONFIG=~/.kube/k3s-server.yaml
kubectl get nodes
```
- **کمترین دسترسی با RBAC.** `k3s.yaml` را به CI، برنامه‌ها یا هم‌تیمی‌ها ندهید؛ برای هر کدام یک ServiceAccount با Role محدود به Namespace خودش بسازید.
- **NodePort برای سرویس داخلی نه.** مثل پورت‌های منتشرشدهٔ داکر، ترافیک NodePort و LoadBalancer با قانون‌های NAT پیش از قانون‌های ورودی UFW هدایت می‌شود و `ufw deny` معمولاً جلویش را نمی‌گیرد. سرویس داخلی را ClusterIP نگه دارید و ارتباط پادها را با NetworkPolicy، که k3s پشتیبانی می‌کند، محدود کنید.
- **بکاپ.** در k3s تک‌سرور، پوشهٔ `/var/lib/rancher/k3s/server/db/` را همراه فایل `/var/lib/rancher/k3s/server/token` نگه دارید؛ بدون توکن، بکاپ بازگردانی نمی‌شود. PVها و دیتابیس‌ها بکاپ جدا می‌خواهند؛ داده‌های StorageClass پیش‌فرض k3s (`local-path`) روی دیسک همان نود، زیر `/var/lib/rancher/k3s/storage`، ذخیره می‌شود و پاد را به همان نود می‌بندد.
- **ارتقا.** اسکریپت نصب را با همان متغیرهای نصب اول دوباره اجرا کنید؛ روی کارگرها بدون `K3S_URL` و `K3S_TOKEN`، اسکریپت به‌جای کارگر یک سرور تازه نصب می‌کند. اول سرورها یکی‌یکی و بعد کارگرها را ارتقا دهید و از روی نسخهٔ فرعی نپرید (از 1.35 مستقیم به 1.37 نروید)؛ با کانال هر نسخه گام‌به‌گام بروید:

```
curl -sfL https://get.k3s.io | INSTALL_K3S_CHANNEL=v1.37 sh -
```

### چرخهٔ پشتیبانی نسخه‌ها

کوبرنتیز تقریباً سالی ۳ نسخهٔ فرعی می‌دهد و هر نسخه حدود ۱۴ ماه وصله می‌گیرد (۱۲ ماه عادی و ۲ ماه نگهداری). در زمان نگارش این مطلب (آبان ۱۴۰۵)، طبق [صفحهٔ انتشارهای کوبرنتیز](https://kubernetes.io/releases/) این سه نسخه پشتیبانی می‌شوند و پشتیبانی 1.34 در ۵ آبان ۱۴۰۵ تمام شد:

| نسخه | پایان پشتیبانی |
| --- | --- |
| 1.37 | ۶ آبان ۱۴۰۶ (۲۸ اکتبر ۲۰۲۷) |
| 1.36 | ۷ تیر ۱۴۰۶ (۲۸ ژوئن ۲۰۲۷) |
| 1.35 | ۹ اسفند ۱۴۰۵ (۲۸ فوریهٔ ۲۰۲۷) |

## سرور مناسب برای کوبرنتیز

برای یادگیری و کلاستر کوچک k3s، سرور مجازی لینوکس با ۲ هسته و ۲ تا ۴ گیگابایت رم کافی است. هاکان سرور، سرور مجازی را در ۵۲ لوکیشن ارائه می‌کند؛ در صفحهٔ [خرید سرور مجازی](https://hakanserver.com/buy-a-virtual-server/) لوکیشن نزدیک به کاربرانتان را انتخاب کنید و همهٔ نودهای یک کلاستر را در یک لوکیشن بگیرید.

با یک نود شروع کنید؛ ارتقای منابع سرویس با ثبت تیکت انجام می‌شود. IP سرویس تا زمانی که سرویس تمدید شود ثابت می‌ماند، پس `K3S_URL` و قانون‌های فایروال دست نمی‌خورند. برای کلاستر بزرگ‌تر [خرید سرور اختصاصی](https://hakanserver.com/dedicatedserver/) را ببینید؛ سرور اختصاصی هاکان با لینوکس، ویندوز یا هر پلتفرم مجازی‌سازی دلخواه تحویل داده می‌شود و می‌توانید چند ماشین مجازی روی آن را نود کلاستر کنید؛ فقط خرابی همان سخت‌افزار همهٔ این نودها را با هم از کار می‌اندازد.

## پرسش‌های متداول

### کوبرنتیز به زبان ساده چیست؟

سیستمی که کانتینرهای شما را روی چند سرور اجرا و سالم نگه می‌دارد و جای اجرا، ری‌استارت، توزیع بار و به‌روزرسانی را خودش مدیریت می‌کند.

### تفاوت k3s و k8s چیست؟

k3s خودِ کوبرنتیز است در قالب توزیعی سبک: اجزا در یک فایل اجرایی جمع شده‌اند و در حالت تک‌سرور به‌جای etcd از SQLite استفاده می‌شود. فایل‌های YAML و دستورهای kubectl همان‌اند.

### آیا کوبرنتیز رایگان است؟

بله؛ کوبرنتیز و k3s متن‌باز و با مجوز Apache 2.0 هستند. هزینهٔ واقعی سرورها و زمان نگهداری کلاستر است.

### یادگیری کوبرنتیز را از کجا شروع کنم؟

اول داکر و ساخت ایمیج را یاد بگیرید، بعد Pod، Deployment، Service و Ingress را با kind یا minikube روی لپ‌تاپ یا k3s روی یک سرور مجازی تمرین کنید.

### آیا کوبرنتیز جای داکر را می‌گیرد؟

نه. داکر برای ساخت ایمیج و اجرای محلی رایج می‌ماند و کوبرنتیز همان ایمیج‌ها را روی کلاستر اجرا می‌کند؛ فقط روی نودها به‌جای Docker Engine، containerd کانتینرها را اجرا می‌کند.

### آیا کوبرنتیز روی سرور ایران نصب می‌شود؟

بله، اما چون Docker Hub آی‌پی‌های ایران را مسدود می‌کند، پیش از نصب میرور را در `registries.yaml` تنظیم کنید و اگر GitHub هم باز نیست، k3s را آفلاین نصب کنید.

## جمع‌بندی

کوبرنتیز اجرای کانتینرها روی چند سرور را خودکار می‌کند، اما سربار دارد؛ برای یک سایت یا اپ کوچک Docker Compose کافی است و کوبرنتیز وقتی می‌ارزد که چند سرویس، چند سرور و چند نفر درگیر باشند. از روز اول Secretها، پورت 6443، شبکهٔ بین نودها و ارتقای منظم را جدی بگیرید.

قدم بعدی: k3s را روی یک سرور آزمایشی نصب کنید، برنامهٔ نمونه را منتشر، به‌روز و بازگردانی کنید و بعد یکی از سرویس‌های خودتان را با YAML تعریف کنید. جزئیات در [مستندات مفاهیم کوبرنتیز](https://kubernetes.io/docs/concepts/) و [مستندات k3s](https://docs.k3s.io/) آمده است.

- مطلب قبلی: [رفع خطای ERR_CONNECTION_TIMED_OUT در کروم؛ چک‌لیست کاربر و مدیر سرور](https://hakanserver.com/err-connection-timed-out/index.md)

## مقاله‌های مرتبط

- [نصب داکر روی اوبونتو 24.04 و 26.04 + Docker Compose و میرور ایران](https://hakanserver.com/install-docker-ubuntu/index.md)
- [کدام توزیع لینوکس برای سرور؟ مقایسهٔ اوبونتو، دبیان، آلمالینوکس و راکی](https://hakanserver.com/%D8%A7%D9%86%D9%88%D8%A7%D8%B9-%D8%B3%DB%8C%D8%B3%D8%AA%D9%85-%D8%B9%D8%A7%D9%85%D9%84%D9%87%D8%A7%DB%8C-%D9%82%D8%A7%D8%A8%D9%84-%D9%86%D8%B5%D8%A8-%D8%A8%D8%B1-%D8%B1%D9%88%DB%8C-%D8%B3/index.md)
- [آموزش نصب سی پنل بر روی سرور مجازی](https://hakanserver.com/%D8%A2%D9%85%D9%88%D8%B2%D8%B4-%D9%86%D8%B5%D8%A8-%D8%B3%DB%8C-%D9%BE%D9%86%D9%84-%D8%A8%D8%B1-%D8%B1%D9%88%DB%8C-%D8%B3%D8%B1%D9%88%D8%B1-%D9%85%D8%AC%D8%A7%D8%B2%DB%8C/index.md)

## سرویس‌های مرتبط هاکان سرور

- [سرور مجازی](https://hakanserver.com/buy-a-virtual-server/index.md): ۵۲ لوکیشن در ایران و خارج
- [سرور اختصاصی](https://hakanserver.com/dedicatedserver/index.md): ایران و ۸ کشور دیگر
- [هاست و دامنه](https://hakanserver.com/buy-hosting-and-domain/index.md): هاست سی‌پنل ایران و اروپا

فهرست همهٔ مقاله‌ها: https://hakanserver.com/blog/index.md
فهرست همهٔ صفحه‌ها و راهنمای سایت: https://hakanserver.com/llms.txt