Kubeadm: установка Kubernetes шаг за шагом

Графика с логотипом Kubernetes

Kubeadm автоматизирует создание кластера Kubernetes на Debian/Ubuntu. В статье описаны подготовка среды, установка containerd, kubeadm/kubectl/kubelet, отключение swap, настройка br_netfilter, запуск control plane, добавление worker и базовые шаги по безопасности и отладке.

Быстрые ссылки

Установка контейнерного рантайма
Установка kubeadm, kubectl и kubelet
Отключение swap
Загрузка модуля br_netfilter
Создание кластера
Подготовка kubeconfig
Установка сетевого аддона для Pod
Работа с кластером
Добавление второго узла
Итоги

Введение

Kubernetes часто считают сложным, но современные релизы делают установку достаточно предсказуемой. Kubeadm предоставляет надежный и воспроизводимый путь для разворачивания control plane и регистрации worker узлов. В этом руководстве показан рабочий процесс с нуля на Debian-подобной системе. Тестировалось на Ubuntu 22.04 и Kubernetes v1.25.

Важно понимать одно предложение

Kubeadm — инструмент для разворачивания и управления базовой инсталляцией upstream Kubernetes, он не заменяет решения для production-операций, но дает максимальную совместимость с проектом Kubernetes.

1. Требования и предварительная проверка

Перед началом выполните базовую проверку системы

ОС: Debian/Ubuntu или совместимая. Этот гайд ориентирован на apt-пакеты
Ресурсы: минимум 2 CPU и 2 ГБ RAM для control plane при тестовой установке
Сеть: доступ по SSH между узлами, порты API-сервера открыты на control plane
Доступ root или sudo на всех узлах

Проверьте время на хосте

$ timedatectl status

Если часы сильно расходятся, синхронизируйте через systemd-timesyncd или NTP

2. Установка контейнерного рантайма

Kubernetes требует CRI совместимый рантайм. Популярный вариант — containerd. Он также используется в современных релизах Docker.

Шаги установки containerd через официальный репозиторий Docker

$ sudo apt update
$ sudo apt install -y ca-certificates curl gnupg lsb-release
$ sudo mkdir -p /etc/apt/keyrings
$ curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
$ echo 'deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable' | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
$ sudo apt update
$ sudo apt install -y containerd.io

Проверка статуса

$ sudo systemctl status containerd

Если service показывает active running, продолжаем.

Настройка containerd для корректной работы с systemd cgroup

$ sudo containerd config default > /etc/containerd/config.toml

Откройте файл /etc/containerd/config.toml и найдите SystemdCgroup. Поставьте значение true

SystemdCgroup = true

Перезапустите сервис

$ sudo systemctl restart containerd

Почему это важно

Без systemd cgroup kubelet и контейнеры control plane могут некорректно управлять ресурсами, что приводит к перезапускам Pod-ов.

Важно

Если вы используете другой рантайм, например CRI-O, адаптируйте инструкции. Kubeadm поддерживает любой CRI совместимый рантайм.

3. Установка kubeadm, kubectl и kubelet

Kubeadm, kubectl и kubelet поставляются через репозиторий Google Cloud.

Установка ключа и репозитория

$ sudo curl -fsSLo /etc/apt/keyrings/kubernetes.gpg https://packages.cloud.google.com/apt/doc/apt-key.gpg
$ echo 'deb [signed-by=/etc/apt/keyrings/kubernetes.gpg] https://apt.kubernetes.io/ kubernetes-xenial main' | sudo tee /etc/apt/sources.list.d/kubernetes.list
$ sudo apt update
$ sudo apt install -y kubeadm kubectl kubelet
$ sudo apt-mark hold kubeadm kubectl kubelet

Почему фиксировать пакеты

Автоматические обновления могут привести к неожиданным изменениям API или к переходу на несовместимую версию kubelet. Обновления кластера должны контролироваться вручную.

Критерии приёмки

kubeadm доступен в PATH
kubelet запускается и не падает
kubectl может обращаться к локальному kubeconfig после инициализации

4. Отключение swap

Kubernetes не поддерживает включенный swap. Отключите его перед запуском kubeadm.

$ sudo swapoff -a

Удалите или закомментируйте swap записи в /etc/fstab, например строку с swapfile

/swapfile none swap sw 0 0

Если не отключить swap, kubelet не стартует и процесс создания кластера зависнет.

5. Загрузка модуля br_netfilter

Модуль br_netfilter нужен, чтобы iptables видел трафик через bridge. Без него сетевой трафик между Pod-ами может быть невидим для фильтров.

$ sudo modprobe br_netfilter
$ echo br_netfilter | sudo tee /etc/modules-load.d/kubernetes.conf

Проверьте, что параметр net.bridge.bridge-nf-call-iptables включен

$ sudo sysctl net.bridge.bridge-nf-call-iptables

Если он равен 0, включите

$ sudo sysctl -w net.bridge.bridge-nf-call-iptables=1

Добавьте в /etc/sysctl.d/kubernetes.conf

net.bridge.bridge-nf-call-ip6tables = 1
net.bridge.bridge-nf-call-iptables = 1
net.ipv4.ip_forward = 1

и примените

$ sudo sysctl --system

6. Создание control plane

Запустите kubeadm init. В примере ниже указан pod network CIDR для Flannel. Если вы планируете другой аддон, проверьте требуемый CIDR.

$ sudo kubeadm init --pod-network-cidr=10.244.0.0/16

Наблюдайте за выводом. В конце вы увидите сообщение об успешной инициализации и инструкции по работе с kubeconfig.

Типичные причины проблем на этом этапе

network CIDR конфликтует с существующей сетью
firewall блокирует порты API
некорректный containerd или kubelet

7. Подготовка kubeconfig

Скопируйте автогенерированный kubeconfig в домашний каталог и установите владельца

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

После этого kubectl будет работать от вашего пользователя.

8. Установка сетевого аддона для Pod

Kubernetes требует сетевого плагина для передачи трафика между Pod-ами. Два популярных варианта — Flannel и Calico. В этом руководстве используется Flannel ради простоты.

Установка Flannel

$ kubectl apply -f https://raw.githubusercontent.com/flannel-io/flannel/master/Documentation/kube-flannel.yml

Через несколько минут проверьте статус узлов

$ kubectl get nodes

и Pod-ов

$ kubectl get pods --all-namespaces

Опции выбора сетевого аддона

Flannel: простая установка, меньше функций маршрутизации, хорош для тестовых и простых окружений
Calico: поддержка сетевых политик, BGP, более функционален для production
Cilium: использует eBPF, подходит для высокопроизводительных сценариев

Сравнение Flannel и Calico

Характеристика	Flannel	Calico
Простота установки	высокая	средняя
Поддержка сетевых политик	нет	да
Подходит для production	да при простых сетях	да

Выбор зависит от потребностей по безопасности и сетевому функционалу.

9. Базовое взаимодействие с кластером

При необходимости разрешите планировать Pod-ы на control plane, если вы используете single-node кластер для разработки

$ kubectl taint node $(kubectl get nodes -o name | head -n1 | sed 's/node\///') node-role.kubernetes.io/control-plane:NoSchedule-

Пример запуска nginx Pod и экспонирования через NodePort

$ kubectl run nginx --image nginx:latest
$ kubectl expose pod nginx --port 80 --type NodePort
$ kubectl get services
$ curl http://localhost:30647

Порт NodePort назначается автоматически. В примере это 30647.

Критерии приёмки

узел показывает STATUS Ready
системные Pod-ы kube-system Running
вы можете получить ответ от сервиса через NodePort

10. Добавление рабочего узла

На новом worker повторите разделы: установка containerd, kubeadm, kubelet, отключение swap, br_netfilter. Затем выполните команду kubeadm join, созданную при инициализации control plane.

Пример однострочной команды join

$ sudo kubeadm join 192.168.122.229:6443 --node-name node-b --token  --discovery-token-ca-cert-hash sha256:

Где получить токен и hash

$ kubeadm token list

Для хеша CA

$ openssl x509 -pubkey -in /etc/kubernetes/pki/ca.crt | openssl rsa -pubin -outform der 2>/dev/null | openssl dgst -sha256 -hex | sed 's/^.* //'

После успешного join вы увидите сообщения о том, что узел присоединился и TLS bootstrap завершен.

11. Минимальный список проверок после установки

kubectl get nodes показывает все узлы Ready
kubectl get pods –all-namespaces показывает Running для kube-system Pod-ов
Сервис NodePort отвечает
systemd журнал не содержит частых перезапусков kubelet

12. Безопасность и hardening

Быстрые рекомендации

Включите RBAC и используйте минимально привилегированные роли
Закройте порты API-сервера с помощью firewall и разрешите доступ только с доверенных хостов
Обновляйте сертификаты и токены по расписанию
В production используйте сетевые политики для ограничения трафика между Pod-ами
Аудит и логирование: интегрируйте с внешними системами логирования и аудитом

Пример базовых iptables правил на control plane

разрешить вход на 6443 только с доверенных IP
разрешить межузловую связь по нужным портам

Примечание

Это общий список. Для production подготовьте отдельный security review с учетом вашей политики соответствия.

13. Точка отказа и операции восстановления

Что проверить при проблемах

containerd и kubelet активны
контроль времени и сертификатов
соответствие версий kubelet и control plane
сетевые правила и br_netfilter

Если control plane упал

проверьте /var/log/pods и /var/log/syslog
убедитесь, что etcd работает и доступен
при необходимости восстановите etcd из бэкапа

14. Альтернативные подходы

Если требуется более простой запуск для разработки

Minikube: одноузловой кластер для локальной разработки
MicroK8s: снэп-пакет, быстрый для single-node
K3s: лёгкая сборка для edge и IoT

Для production рассмотрите управляемые сервисы типа GKE, EKS, AKS

15. Маленький методологический чеклист перед обновлением кластера

Сделать бэкап etcd
Проверить совместимость версий kubeadm и kubelet
Тестировать апгрейд на staging
Обновлять контрол-план поэтапно
Наблюдать за SLO/SLI во время апгрейда

16. Playbook: добавление worker узла

Шаги

На worker установить containerd, kubeadm, kubelet
Отключить swap и загрузить br_netfilter
Проверить сетевую связность до control plane
Выполнить kubeadm join с токеном и CA hash
Проверить на control plane через kubectl get nodes

Роль-based чеклист

Администратор сеть: проверить firewall и маршруты
Администратор ОС: выполнить установку пакетов и настройки kernel
K8s оператор: выполнить kubeadm join и верифицировать состояние

17. Модель принятия решения при выборе сетевого плагина

flowchart TD
  A[Нужна простота?] -->|Да| B[Flannel]
  A -->|Нет| C[Нужны сетевые политики?]
  C -->|Да| D[Calico или Cilium]
  C -->|Нет| B
  D --> E{Высокая нагрузка?}
  E -->|Да| F[Cilium]
  E -->|Нет| D

18. Справочный блок: ключевые команды

kubeadm init
kubeadm join
kubectl apply -f
kubectl get nodes
kubectl get pods –all-namespaces
containerd config default > /etc/containerd/config.toml

19. Глоссарий в одну строку

kubeadm: инструмент инициализации кластера Kubernetes
kubelet: агент на узле, запускает контейнеры и следит за состоянием
kubectl: клиент для взаимодействия с API-сервером
Pod network CIDR: диапазон адресов для Pod-ов

20. Частые вопросы и ответы

Вопрос: Можно ли использовать этот подход на CentOS или RHEL

Ответ: Да, принципы те же. Пакеты и команды для установки рантайма и репозиториев будут отличаться, используйте менеджер yum или dnf и соответствующие репозитории.

Вопрос: Как продлить срок действия токена join

Ответ: Создайте новый токен через kubeadm token create или используйте автоматическую процедуру с RBAC и bootstrap.

Итоги

Kubeadm предоставляет управляемый и гибкий путь для развёртывания upstream Kubernetes. Для тестовой и учебной работы этот подход идеален, а для production необходимо предусмотреть дополнительные меры безопасности, мониторинга и бэкапы. Проверьте базовые предварительные требования, установите CRI, отключите swap, загрузите br_netfilter, затем инициализируйте кластер и установите сетевой аддон.

Ключевые выводы

Установите containerd и включите systemd cgroup
Фиксируйте версии kubeadm/kubelet/kubectl и планируйте апгрейды
Отключите swap и загрузите br_netfilter
Установите сетевой аддон до завершения присоединения worker

Дополнительные ресурсы

Официальная документация Kubernetes
Руководства по Flannel, Calico и Cilium

Важно

Эта инструкция описывает базовую установку. Для production среды потребуется более глубокая проработка сетевой безопасности, резервного копирования etcd, мониторинга и логирования.