kubeadm کلاستر را bootstrap می‌کند، اما هنوز OS، CNI، HA etcd، گواهی، add-on و تکرارپذیری روی ده‌ها سرور باقی می‌ماند. تیم‌هایی که bare metal یا VM چندابری دارند، معمولاً به لایهٔ Infrastructure as Code نیاز دارند.

Kubespray پاسخ رسمی جامعهٔ Kubernetes (زیر kubernetes-sigs) است:

Deploy a Production Ready Kubernetes Cluster

یعنی مجموعهٔ playbookهای Ansible برای استقرار کلاستر HA، قابل ترکیب، روی اکثر توزیع‌های لینوکس — از AWS تا bare metal.

Docs: kubespray.io · Repo: github.com/kubernetes-sigs/kubespray · Slack: #kubespray · لایسنس: Apache-2.0

Kubespray چیست؟ (و چه چیزی نیست)

شعارهای README:

• استقرار روی AWS، GCE، Azure، OpenStack، vSphere، Equinix Metal، OCI (experimental)، Baremetal
• کلاستر Highly available
• Composable (مثلاً انتخاب network plugin)
• پشتیبانی از بیشتر توزیع‌های محبوب لینوکس
• CI/e2e مستمر (اسپانسرهایی مثل CNCF، Equinix Metal، OVHcloud، ELASTX)

مشکل: از kubeadm تا production

فقط kubeadm:
  OS prep دستی × N
  etcd HA دستی
  CNI جدا
  cert rotation / upgrade پراکنده
  تکرارپذیری ضعیف

با Kubespray:
  inventory + group_vars
       │
       ▼
  ansible-playbook cluster.yml
       │
       ├─ kernel / swap / packages
       ├─ containerd | cri-o | docker
       ├─ etcd HA
       ├─ kubeadm control plane + workers
       ├─ CNI (Calico/…)
       └─ CoreDNS، metrics، اختیاری MetalLB/Helm/…

Idempotent است: اجرای دوبارهٔ playbook باید به همان وضعیت برسد و استقرار قطع‌شده قابل ادامه است.

مقایسه: Kubespray در برابر گزینه‌ها

در برابر kubeadm و kops (از docs رسمی)

طبق comparisons.md:

جمع‌بندی رسمی: Kubespray دانش lifecycle را از kubeadm می‌گیرد و کارهای عمومی OS را با Ansible جدا می‌کند — هر دو طرف سود می‌برند.

در برابر distributionها

اگر تیم از قبل Ansible دارد و می‌خواهد upstream Kubernetes با کنترل کامل → Kubespray. اگر می‌خواهد باینری امن و opinionated → RKE2. اگر edge سبک → K3s.

معماری منطقی و نقش نودها

Ansible control machine (laptop / CI)
        │ SSH + become
        ▼
┌─────────────────────────────────────────┐
│ inventory                               │
│  kube_control_plane (فرد برای HA)       │
│  etcd (اغلب هم‌جا با CP در lab)         │
│  kube_node (workers)                    │
└─────────────────────────────────────────┘
        │
        ▼ playbooks
   OS → CRI → etcd → kubeadm → CNI → addons

برای HA API اغلب load balancer (HAProxy/Nginx/kube-vip) جلوی چند control plane می‌نشیند — docs: HA mode.

Playbookهای اصلی

اجزای پشتیبانی‌شده (نسخهٔ فعلی README)

اعداد با release عوض می‌شوند؛ نمونه از README فعلی repo:

حداقل Kubernetes پشتیبانی‌شده در README فعلی: v1.34.0+. CRI-O باید minor با Kubernetes هم‌تراز باشد.

جزئیات CNI: مقایسه CNI · Cilium · Kube-OVN. Runtime: containerd · CRI-O. etcd: etcd.

سیستم‌عامل‌های پشتیبانی‌شده

طیف گسترده (خلاصه از README):

• Debian / Ubuntu LTS جدید
• RHEL / CentOS Stream / Alma / Rocky / Oracle Linux
• Fedora / Fedora CoreOS / Flatcar
• openSUSE Leap / Tumbleweed
• چند مورد experimental: Amazon Linux 2، Kylin، UOS، openEuler، Rocky 10

پشتیبانی نمی‌شود: init از نوع Upstart/SysV. برای کرنل < 4.19 docs کرنل را بخوانید.

حداقل حافظهٔ safeguarded: Control plane ۲ GB، Worker ۱ GB — برای production واقعی بالاتر بروید.

پیش‌نیازها

شروع سریع

با کانتینر رسمی

docker run --rm -it \
  --mount type=bind,source="$(pwd)"/inventory/sample,dst=/inventory \
  --mount type=bind,source="${HOME}"/.ssh/id_rsa,dst=/root/.ssh/id_rsa \
  quay.io/kubespray/kubespray:v2.31.0 bash

# داخل کانتینر:
ansible-playbook -i /inventory/inventory.ini \
  --private-key /root/.ssh/id_rsa cluster.yml

نسخهٔ image را با آخرین tag عوض کنید.

مسیر Ansible کلاسیک (مفهومی)

git clone https://github.com/kubernetes-sigs/kubespray.git
cd kubespray
python3 -m venv .venv && source .venv/bin/activate
pip install -U -r requirements.txt

cp -rfp inventory/sample inventory/mycluster
# ویرایش inventory/mycluster/inventory.ini و group_vars/

ansible-playbook -i inventory/mycluster/inventory.ini \
  --become --become-user=root cluster.yml

ابزار inventory_builder / اسکریپت‌های contrib می‌توانند از لیست IP، inventory بسازند. برای lab محلی: Vagrant (vagrant up پس از نصب Ansible).

نمونهٔ نقش‌ها در inventory:

[kube_control_plane]
cp1 ansible_host=10.0.0.11
cp2 ansible_host=10.0.0.12
cp3 ansible_host=10.0.0.13

[etcd:children]
kube_control_plane

[kube_node]
worker1 ansible_host=10.0.0.21
worker2 ansible_host=10.0.0.22

[k8s_cluster:children]
kube_control_plane
kube_node

متغیر شبکه (مثال):

# inventory/mycluster/group_vars/k8s_cluster/k8s-cluster.yml
kube_network_plugin: calico   # یا cilium، flannel، kube-ovn، …
container_manager: containerd

پس از موفقیت، kubeconfig معمولاً از اولین control plane قابل کپی است (مسیر دقیق در docs Getting Started).

عملیات روزمره

Terraform در contrib/terraform و پروژه‌هایی مثل Kubean روی Kubespray سوار شده‌اند.

برای GitOps بعد از بالا آمدن کلاستر: Flux · Helm · Argo. برای TLS: cert-manager.

چه وقت Kubespray را انتخاب کنیم؟

Managed cloud کافی است؟ ──yes──► EKS/GKE/AKS
         │ no
         ▼
تیم Ansible + bare metal / چند cloud؟ ──yes──► Kubespray
         │ no
         ▼
نیاز FIPS/CIS باینری opinionated؟ ──yes──► RKE2
         │ no
         ▼
Edge / منابع کم؟ ──yes──► K3s
         │ no
         ▼
یادگیری تک‌نود؟ ──► kubeadm / kind

Kubespray می‌درخشد وقتی مالک زیرساخت هستید و تکرارپذیری + انتخاب CNI/CRI مهم است.

یکپارچگی با استک P30Light

Terraform/IPMI ──► VM/Bare metal
Ansible (Kubespray) ──► Kubernetes upstream + CNI
Flux/Argo ──► workloads

خلاصه

قدم بعدی

1. با image quay.io/kubespray/kubespray روی ۳ VM lab یک cluster.yml خشک اجرا کنید.
2. kube_network_plugin را بین Calico و Cilium در دو inventory جدا مقایسه کنید.
3. یک worker با scale.yml اضافه و با remove-node.yml حذف کنید.
4. مسیر air-gap را اگر دیتاسنتر بدون اینترنت دارید از docs Offline بخوانید.
5. upgrade-cluster.yml را روی lab قبل از production تمرین کنید.
6. پس از پایداری، GitOps و observability را جدا از Kubespray لایه کنید.

منابع

• GitHub — kubernetes-sigs/kubespray
• kubespray.io
• Comparisons (vs kops / kubeadm)
• Getting started
• Offline / Air-gap
• kubernetes.io — Kubespray

منتشر شده در P30Light — بخش زیرساخت و سرور