آموزش نصب کوبرنتیز: راه اندازی کلاستر Kubernetes با kubeadm

بیشتر تیم ها وقتی سراغ کوبرنتیز می روند که تعداد سرویس هایشان از حد مدیریت دستی کانتینرها گذشته باشد. آموزش نصب کوبرنتیز با kubeadm مسیر استانداردی است برای ساختن کلاستر روی سرورهای خودتان، بدون وابستگی به ابر. در این راهنما نودها را آماده می کنیم، containerd را نصب و تنظیم می کنیم، نود کنترل را با kubeadm بالا می آوریم، شبکه pod را نصب می کنیم، نود worker اضافه می کنیم و در پایان چیزهایی را مرور می کنیم که فرق یک کلاستر آزمایشی با یک کلاستر قابل نگهداری را می سازند.

قبل از شروع: kubeadm برای چه کسی مناسب است؟

kubeadm ابزار رسمی پروژه کوبرنتیز برای ساخت کلاستر است. کنترل کامل به شما می دهد و همان چیزی را نصب می کند که در مستندات رسمی توضیح داده شده، ولی نگهداری کلاستر هم با خودتان است: ارتقا، بکاپ etcd، تمدید گواهی ها و شبکه.

اگر هدف شما یک محیط کوچک یا لبه شبکه است، توزیع هایی مثل k3s سبک تر و سریع تر راه می افتند. اگر تیم زیرساخت ندارید و ابر برایتان گزینه است، سرویس مدیریت شده بخش بزرگی از این نگهداری را برمی دارد. kubeadm وقتی انتخاب درستی است که سرورها در دیتاسنتر خودتان باشند و بخواهید ساختار کلاستر دقیقا مشخص باشد.

پیش نیازها

اگر نودها را از روی یک تمپلیت ماشین مجازی کلون کرده اید، یکتا بودن product_uuid را حتما بررسی کنید:

sudo cat /sys/class/dmi/id/product_uuid
ip link

خاموش کردن swap و تنظیمات کرنل

این مرحله را روی همه نودها اجرا کنید:

sudo swapoff -a
sudo sed -i '/ swap / s/^/#/' /etc/fstab

cat <<EOF | sudo tee /etc/modules-load.d/k8s.conf
overlay
br_netfilter
EOF
sudo modprobe overlay
sudo modprobe br_netfilter

cat <<EOF | sudo tee /etc/sysctl.d/k8s.conf
net.ipv4.ip_forward = 1
net.bridge.bridge-nf-call-iptables = 1
net.bridge.bridge-nf-call-ip6tables = 1
EOF
sudo sysctl --system

غیرفعال کردن swap در fstab را فراموش نکنید، وگرنه بعد از اولین ریبوت کلاستر بالا نمی آید.

نصب container runtime

کوبرنتیز خودش کانتینر اجرا نمی کند و به یک runtime سازگار با CRI نیاز دارد. containerd رایج ترین انتخاب است و از مخزن docker-ce یا مخزن توزیع نصب می شود. بعد از نصب، فایل تنظیمات پیش فرض را بسازید:

sudo mkdir -p /etc/containerd
containerd config default | sudo tee /etc/containerd/config.toml >/dev/null

حالا مهم ترین تنظیم کل این مرحله: cgroup driver باید systemd باشد. در فایل config.toml مقدار SystemdCgroup را برابر true بگذارید:

[plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runc.options]
  SystemdCgroup = true

sudo systemctl restart containerd
sudo systemctl enable containerd

اگر این مقدار false بماند، kubelet و containerd دو مدیر cgroup متفاوت خواهند داشت و kubeadm init در مرحله بالا آمدن kubelet گیر می کند. این شایع ترین خطای نصب است. توجه کنید که ساختار فایل config.toml در نسخه های مختلف containerd کمی فرق دارد؛ خروجی containerd config default همان نسخه نصب شده را به شما نشان می دهد، پس مقدار را در همان ساختار عوض کنید و از کپی کردن فایل قدیمی خودداری کنید.

نصب kubeadm و kubelet و kubectl

مخزن رسمی pkgs.k8s.io برای هر نسخه فرعی آدرس جداگانه دارد. نسخه را آگاهانه انتخاب کنید: پروژه کوبرنتیز فقط سه نسخه فرعی آخر را پشتیبانی می کند و هر نسخه حدود یک سال وصله می گیرد. در دستورهای زیر نسخه v1.37 نوشته شده؛ اگر نسخه دیگری نصب می کنید، همان شماره را در هر دو آدرس عوض کنید.

روی Ubuntu و Debian:

sudo apt update
sudo apt install -y apt-transport-https ca-certificates curl gpg
sudo mkdir -p -m 755 /etc/apt/keyrings
curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.37/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg
echo 'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.37/deb/ /' | sudo tee /etc/apt/sources.list.d/kubernetes.list
sudo apt update
sudo apt install -y kubelet kubeadm kubectl
sudo apt-mark hold kubelet kubeadm kubectl

روی AlmaLinux و خانواده RHEL:

cat <<EOF | sudo tee /etc/yum.repos.d/kubernetes.repo
[kubernetes]
name=Kubernetes
baseurl=https://pkgs.k8s.io/core:/stable:/v1.37/rpm/
enabled=1
gpgcheck=1
gpgkey=https://pkgs.k8s.io/core:/stable:/v1.37/rpm/repodata/repomd.xml.key
exclude=kubelet kubeadm kubectl cri-tools kubernetes-cni
EOF

sudo dnf install -y kubelet kubeadm kubectl --disableexcludes=kubernetes
sudo systemctl enable --now kubelet

دستور apt-mark hold و گزینه exclude کار یکسانی می کنند: جلوگیری از ارتقای ناخواسته این سه بسته هنگام به روزرسانی معمول سرور. ارتقای کلاستر باید با ترتیب مشخص و با دستور kubeadm upgrade انجام شود، نه با apt upgrade.

ساخت نود کنترل

روی نود اول دستور init را اجرا کنید:

sudo kubeadm init \
  --pod-network-cidr=192.168.0.0/16 \
  --control-plane-endpoint=k8s-api.corp.local:6443 \
  --upload-certs

دو نکته در همین دستور مهم است. اول، بازه pod-network-cidr نباید با شبکه داخلی شرکت، شبکه سرورها یا شبکه VPN تداخل داشته باشد؛ تداخل این بازه ها یکی از مشکلاتی است که ماه ها بعد به شکل قطع شدن دسترسی به یک سرویس خاص خودش را نشان می دهد. دوم، control-plane-endpoint را حتی برای کلاستر تک نودی روی یک نام DNS بگذارید. اگر بعدا بخواهید نود کنترل دوم و سوم اضافه کنید، بدون این گزینه باید کلاستر را از نو بسازید.

بعد از اتمام، دسترسی kubectl را تنظیم کنید:

mkdir -p $HOME/.kube
sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config
kubectl get nodes

در این مرحله نود در وضعیت NotReady است. طبیعی است؛ هنوز شبکه pod نصب نشده.

نصب شبکه CNI

کوبرنتیز شبکه pod را خودش پیاده سازی نمی کند و به یک افزونه CNI نیاز دارد. Calico و Cilium دو انتخاب رایج برای محیط داخلی هستند؛ Cilium روی eBPF کار می کند و امکانات شبکه و مشاهده پذیری بیشتری می دهد، Calico ساده تر و جاافتاده تر است.

برای Calico، ابتدا اپراتور Tigera و سپس منبع سفارشی نصب را اعمال می کنید. شماره نسخه را از مستندات رسمی پروژه بردارید و بازه IP در فایل custom-resources.yaml را با همان مقداری که در kubeadm init دادید یکی کنید:

kubectl create -f https://raw.githubusercontent.com/projectcalico/calico/v3.32.2/manifests/tigera-operator.yaml
curl -O https://raw.githubusercontent.com/projectcalico/calico/v3.32.2/manifests/custom-resources.yaml
# مقدار cidr را بررسی و در صورت نیاز اصلاح کنید
kubectl create -f custom-resources.yaml

بعد از چند دقیقه وضعیت را بررسی کنید:

kubectl get pods -A
kubectl get nodes -o wide

نود باید Ready شود و podهای سیستمی در وضعیت Running باشند.

اضافه کردن نود worker

خروجی kubeadm init یک دستور join به شما داده است. همان را روی هر worker اجرا کنید:

sudo kubeadm join k8s-api.corp.local:6443 \
  --token <token> \
  --discovery-token-ca-cert-hash sha256:<hash>

توکن join حدود یک روز اعتبار دارد. اگر دیر اقدام کردید یا دستور را گم کردید، روی نود کنترل دستور زیر را بزنید تا دستور تازه بسازد:

kubeadm token create --print-join-command

دسترسی از بیرون: ingress و load balancer

برای اینکه سرویس ها از بیرون کلاستر در دسترس باشند، دو قطعه لازم دارید. روی سرورهای داخلی که Load Balancer ابری ندارند، معمولا MetalLB نصب می شود تا سرویس های نوع LoadBalancer یک IP از بازه شبکه شما بگیرند. بعد از آن نوبت لایه مسیریابی HTTP است.

اینجا یک تغییر مهم را در نظر بگیرید: پروژه ingress-nginx که سال ها گزینه پیش فرض بود بازنشسته شده و مخزن آن آرشیو شده است؛ یعنی نسخه جدید و وصله امنیتی نمی گیرد. برای کلاستر جدید سراغ Gateway API و یکی از پیاده سازی های فعال آن بروید، یا کنترلری انتخاب کنید که پشتیبانی فعال دارد. اگر کلاستر قدیمی با ingress-nginx دارید، مهاجرت از آن را در برنامه امسال بگذارید.

برای گواهی های TLS هم cert-manager را نصب کنید تا صدور و تمدید گواهی ها خودکار باشد.

نکات تولیدی که معمولا جا می مانند

• سه نود کنترل: etcd برای تصمیم گیری به اکثریت نیاز دارد، پس تعداد نودهای کنترل باید فرد باشد. با یک نود کنترل، از کار افتادن همان سرور یعنی از دست رفتن مدیریت کل کلاستر.
• بکاپ etcd: کل وضعیت کلاستر در etcd است. با etcdctl snapshot save بکاپ منظم بگیرید، فایل را بیرون از کلاستر نگه دارید و یک بار بازیابی را تمرین کنید. برای بکاپ منابع و volumeها ابزارهایی مثل Velero را اضافه کنید.
• گواهی ها: گواهی هایی که kubeadm می سازد یک ساله هستند. با دستور kubeadm certs check-expiration وضعیت را ببینید و تمدید را در تقویم بگذارید. منقضی شدن این گواهی ها یعنی قطع شدن دسترسی به API کلاستر.
• ارتقای نسخه: با پشتیبانی حدودا یک ساله هر نسخه، ارتقا یک کار دوره ای است نه یک پروژه چندساله. نسخه kubelet نودها نباید از نسخه control plane جلو بزند.
• requests و limits: برای هر workload مقدار حافظه و CPU تعیین کنید، وگرنه یک برنامه پرمصرف کل نود را به هم می ریزد.
• ذخیره سازی: یک StorageClass واقعی تعریف کنید. استفاده از hostPath برای داده ماندگار در محیط چندنودی جواب نمی دهد.
• مشاهده پذیری: بدون متریک و لاگ متمرکز، عیب یابی در کلاستر حدس زدن است. راه اندازی این لایه در سرویس مانیتورینگ و مشاهده پذیری انجام می شود.

اشتباه های رایج در نصب

1. روشن ماندن swap یا فراموش کردن غیرفعال کردن آن در fstab.
2. تنظیم نکردن SystemdCgroup روی containerd و گیر کردن kubeadm init.
3. انتخاب بازه pod که با شبکه داخلی یا VPN تداخل دارد.
4. اجرای kubeadm init بدون control-plane-endpoint و بسته شدن مسیر افزودن نود کنترل دوم.
5. ارتقای ناخواسته بسته ها با apt upgrade و ناسازگار شدن نسخه ها.
6. نداشتن بکاپ etcd. اسنپ شات ماشین مجازی جای بکاپ etcd را نمی گیرد.
7. نصب نسخه ای که دیگر پشتیبانی نمی شود، فقط به این دلیل که در یک آموزش قدیمی دیده شده است.

یک کلاستر آزمایشی را می شود در یک بعدازظهر بالا آورد؛ کلاستری که سال ها بدون ترس از به روزرسانی کار کند، به طراحی نودها، بکاپ، مانیتورینگ و مستندات نیاز دارد. اگر می خواهید کلاستر فعلی تان بازبینی شود یا از ابتدا برای محیط تولید ساخته شود، در سرویس راه اندازی کلاستر کوبرنتیز طراحی نودها و شبکه، بکاپ etcd و runbook به روزرسانی را با هم مشخص می کنیم. شروع کار هم می تواند یک بررسی ساده از وضعیت فعلی باشد؛ درخواستش را از صفحه پشتیبانی Kubernetes ثبت کنید.