Установка Kubernetes с kubeadm — пошаговое руководство

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

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

Цель и варианты использования

Это руководство предназначено для инженеров DevOps и администраторов, которые хотят развернуть upstream Kubernetes с помощью kubeadm. Варианты: тестовая среда, лабораторные стенды, небольшие кластеры для разработки. Для production-кластеров рекомендуется дополнительно планировать безопасность, резервирование и мониторинг.

Важно: в примерах предполагается Debian/Ubuntu (проверено на Ubuntu 22.04) и Kubernetes v1.25. Многие команды легко адаптируются под другие дистрибутивы.

Предпосылки

• Как минимум одна машина для control plane (можно использовать отдельную VM или физический сервер).
• Для воркеров — одна или несколько машин с сетевой доступностью к control plane.
• root-доступ или sudo на всех узлах.
• Интернет-доступ для загрузки пакетов и манифестов (или локальный mirror).
• Проверить, что на каждой машине отключён swap и включён br_netfilter (детали ниже).

Совет: используйте минимальную одинаковую версию ОС на всех узлах, чтобы снизить вероятность несовместимостей.

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

Kubernetes требует совместимого CRI (Container Runtime Interface). Стабильный и популярный выбор — containerd; он используется современными версиями Docker.

Ниже приведён пример установки containerd через Docker Apt-репозиторий. Сначала обновите список пакетов:

$ sudo apt update

Затем установите зависимости:

$ sudo apt install -y \

ca-certificates \

curl \

gnupg \

lsb-release

Добавьте GPG-ключ репозитория Docker в директорию keyrings:

$ sudo mkdir -p /etc/apt/keyrings

$ curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

Добавьте репозиторий Docker для вашей архитектуры и релиза Ubuntu:

$ 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

Обновите список пакетов и установите containerd:

$ sudo apt update

$ sudo apt install -y containerd.io

Проверьте статус сервиса containerd:

$ sudo service containerd status

Пример ожидаемого вывода:

containerd.service - containerd container runtime

Loaded: loaded (/lib/systemd/system/containerd.service; enabled; vendor preset: enabled)

Active: active (running) since Tue 2022-09-13 16:50:12 BST; 6s ago

Некоторые настройки containerd важны для корректной работы с Kubernetes. Сгенерируйте конфигурацию по умолчанию:

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

В открытом файле /etc/containerd/config.toml найдите строку:

SystemdCgroup = false

и измените на:

SystemdCgroup = true

Это включает управление cgroup через systemd и предотвращает периодические рестарты системных контейнеров Kubernetes.

После правки перезапустите containerd:

$ sudo service containerd restart

Важно: если вы используете другие рантаймы (CRI-O, Docker Engine -> dockerd), учитывайте рекомендации совместимости и настройки cgroups.

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

Эти три компонента обеспечивают администрирование кластера и работу агентов на узлах:

• kubeadm — инструменты для инициализации и управления кластером;
• kubectl — CLI для взаимодействия с кластером;
• kubelet — агент, запускаемый на каждом узле;

Добавьте GPG ключ и репозиторий Kubernetes, затем установите пакеты:

$ 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

Зафиксируйте версии пакетов, чтобы apt не обновил их автоматически и не вызвал несовместимость в кластере:

$ sudo apt-mark hold kubeadm kubectl kubelet

Совет: всегда планируйте апгрейд Kubernetes; делайте это через kubeadm upgrade с тестированием на стейджинге.

Отключение swap

Kubernetes не работает при включённом swap. Отключите swap до инициализации кластера:

$ sudo swapoff -a

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

UUID=ec6efe91-5d34-4c80-b59c-cafe89cc6cb2 / ext4 errors=remount-ro 0 1

/swapfile none swap sw 0 0

Убедитесь, что известные swap-строки удалены, чтобы swap не включался после перезагрузки.

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

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

Загрузите модуль сейчас:

$ sudo modprobe br_netfilter

Чтобы модуль загружался автоматически после перезагрузки, добавьте его в список модулей:

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

Проверьте доступность bridged трафика для iptables:

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

Ожидаемое значение: 1. Если 0, выполните:

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

Создание кластера

На узле, который станет control plane, выполните:

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

Флаг –pod-network-cidr указывает диапазон подсетей Pod и должен соответствовать сетевому аддону (Flannel использует 10.244.0.0/16 по умолчанию). Если в вашей сети уже используются эти адреса — скорректируйте диапазон.

Инициализация может занять несколько минут. При успешной инициализации вы увидите сообщение:

Your Kubernetes control-plane has initialized successfully!

Вы также получите инструкции по копированию kubeconfig и команде kubeadm join для воркеров.

Подготовка kubeconfig

Скопируйте автоматически сгенерированный файл конфигурации для 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 будет работать от имени вашего пользователя.

Установка сетевого аддона Pod

Kubernetes требует сетевого аддона для организации сети Pod-to-Pod. Среди популярных вариантов — Flannel и Calico. В этом руководстве применяется Flannel из-за простоты установки.

Примените манифест Flannel:

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

Подождите несколько секунд и проверьте узлы:

$ kubectl get nodes

Пример вывода:

NAME STATUS ROLES AGE VERSION

ubuntu22 Ready control-plane 7m19s v1.25.0

Проверьте все Pod’ы в kube-system:

$ kubectl get pods --all-namespaces

Вы должны увидеть, что контроллеры, CoreDNS и Flannel находятся в состоянии Running.

Работа с кластером

По умолчанию Kubernetes помечает control plane узлы «taint», запрещая запуск обычных Pod’ов. Для тестовой среды можно снять таинт, чтобы разрешить запуск Pod’ов на control plane:

$ kubectl taint node ubuntu22 node-role.kubernetes.io/control-plane:NoSchedule-

Замените ubuntu22 на имя вашего узла.

Запустите тестовый nginx Pod:

$ kubectl run nginx --image nginx:latest

Экспонируйте его через NodePort:

$ kubectl expose pod/nginx --port 80 --type NodePort

Узнайте, какой порт назначен на хосте:

$ kubectl get services

Пример вывода:

NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE

kubernetes ClusterIP 10.96.0.1 443/TCP 18m

nginx NodePort 10.106.44.155 80:30647/TCP 27s

В примере порт на хосте — 30647. Проверьте страницу NGINX:

$ curl http://localhost:30647

Должна вернуться стандартная страница Welcome to nginx!

Добавление ещё одного узла

Повторите этапы установки containerd, kubeadm и kubelet на каждом воркере. Убедитесь, что узел имеет сетевой доступ к control plane (порт 6443).

Команда join выглядит так (пример из вывода kubeadm init):

kubeadm join 192.168.122.229:6443 \

--node-name node-b \

--token  \

--discovery-token-ca-cert-hash sha256:

Значения и были выведены при инициализации control plane. Их можно получить повторно:

Токен

$ kubeadm token list

Вывод содержит колонку TOKEN, где будет ваш токен.

Хеш CA

Считайте 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 вы увидите сообщения о CSR и подключении kubelet.

Проверьте на control plane:

$ kubectl get nodes

Частые ошибки и устранение неполадок

Важно: прежде чем паниковать, проверьте следующие очистки:

• Установлен ли containerd/dockerd/CRI-O и запущен ли сервис?
• Отключён ли swap? (swapoff -a)
• Загружен ли br_netfilter и включено ли net.bridge.bridge-nf-call-iptables=1?
• Установлен ли сетевой аддон (Flannel/Calico)?

Проблемы и решения:

• Kubelet не стартует: проверьте journalctl -u kubelet и /var/log/syslog, конфигурации cgroups и наличие файла /var/lib/kubelet/config.yaml.
• Подсеть Pod конфликтует с вашей сетью: измените –pod-network-cidr при kubeadm init и используйте совместимый аддон.
• TLS ошибки при join: проверьте токен и хеш CA; токены истекают (по умолчанию 24 часа).

Диагностика статуса Pod’ов:

$ kubectl get pods -n kube-system

Посмотрите логи проблемного Pod:

$ kubectl logs  -n 

Если flannel CrashLoopBackOff — проверьте, правильно ли назначен CIDR и доступность IPAM.

Роли и чек-листы

Контрольный список для control plane (минимум):

• Установлен и настроен containerd
• Kubeadm, kubelet, kubectl установлены и зафиксированы
• Swap отключён
• br_netfilter загружен и net.bridge.bridge-nf-call-iptables = 1
• kubeadm init выполнен с корректным –pod-network-cidr
• kubeconfig скопирован в $HOME/.kube/config
• Сетевой аддон установлен и Pod’ы в kube-system Running

Контрольный список для worker:

• containerd и kubelet установлены
• Swap отключён
• br_netfilter загружен
• kubeadm join выполнен успешно
• Узел отображается как Ready

Альтернативные подходы и когда их выбирать

• Minikube, MicroK8s, K3s — удобны для локальной разработки и одиночных нод; выбирайте, если нужен быстрый старт.
• Управляемые сервисы (GKE, EKS, AKS) — если не хотите управлять control plane и инфраструктурой.
• kubeadm — хороший компромисс для гибкости и близости к upstream Kubernetes.

Когда не выбирать kubeadm: если вам нужен мгновенный single-command кластер для локального dev-а — используйте Minikube/Kind/MicroK8s.

Безопасность и лучшие практики

• В production: запланируйте HA для control plane (несколько control plane узлов).
• Ограничьте доступ к API Server через firewall/SEC groups и используйте RBAC.
• Включите audit logging для Kubernetes API.
• Шифруйте секреты и используйте внешние решения (HashiCorp Vault, KMS).
• Настройте TLS на ingress и сетевые политики с помощью Calico или Cilium.

Playbook: добавление воркера — краткий SOP

1. На новом узле: установить containerd, kubeadm, kubelet, kubectl.
2. Отключить swap: sudo swapoff -a; удалить swap из /etc/fstab.
3. Загрузить br_netfilter и установить net.bridge.bridge-nf-call-iptables=1.
4. Выполнить команду kubeadm join с токеном и CA-hash.
5. На control plane: kubectl get nodes — убедиться, что узел в состоянии Ready.
6. Выполнить smoke-тест: деплой nginx и проверить, что Pod запущен на новом узле.

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

• Узел отображается как Ready
• Pod может быть запущен и нормально отвечает на запросы

Инцидентный план — если ноду нельзя добавить

1. Проверить сетевое соединение до порта 6443 control plane: nc -vz 6443
2. Проверить корректность токена и хеша CA на control plane.
3. Посмотреть логи kubelet на воркере: sudo journalctl -u kubelet -b
4. На control plane: kubectl get csr — проверить незавершённые запросы и подписать их при необходимости.
5. Если проблема c CRI — проверить статус containerd и его логи: sudo journalctl -u containerd
6. При длительных проблемах — пересоздать токен: kubeadm token create –print-join-command

Выбор сетевого CIDR — рекомендации

• Flannel по умолчанию использует 10.244.0.0/16. Если ваша инфраструктура использует этот диапазон, выберите другой (например 10.100.0.0/16) и укажите тот же диапазон в –pod-network-cidr при kubeadm init.
• Всегда согласовывайте CIDR с сетевыми командами и правилами безопасности.

Сравнение популярных контейнерных рантаймов (кратко)

• containerd: лёгкий, простой, рекомендован для production.
• CRI-O: ориентирован на Kubernetes, хорошо интегрируется с OpenShift.
• Docker (dockerd): привычен многим, но требует использования адаптера cri-dockerd для совместимости с Kubernetes.

Выбор зависит от требований к поддержке и экосистемы в вашей организации.

Decision flowchart: выбор способа установки

flowchart TD
  A[Нужен локальный single-node для dev?] -->|Да| B[Используйте Minikube/Kind/MicroK8s]
  A -->|Нет| C[Требуется гибкий upstream-кластер?]
  C -->|Да| D[Используйте kubeadm]
  C -->|Нет| E[Рассмотрите managed-сервисы 'GKE/EKS/AKS']

Короткий глоссарий

• kubeadm — инструмент для bootstrap Kubernetes-кластера.
• kubelet — агент на каждом узле, отвечает за запуск Pod’ов.
• kubectl — CLI для взаимодействия с Kubernetes.
• Pod — базовая единица развертывания в Kubernetes.
• CNI — интерфейс для сетевых плагинов Kubernetes.

Тесты приёмки после установки

1. kubectl get nodes — все узлы в Ready.
2. kubectl get pods -n kube-system — системные Pod’ы Running.
3. Успешный запуск тестового nginx и ответ на запрос через NodePort.
4. Проверка сетевых политик при необходимости.

Советы по обновлению кластера

• Планируйте upgrade с помощью kubeadm upgrade; обновляйте control plane первым, затем воркеры.
• Тестируйте процесс обновления на стейджинге.
• Снимайте бэкапы etcd перед критическими обновлениями.

Локальные альтернативы и нюансы для России/Европы

• Если доступ к GitHub/raw.githubusercontent может быть медленным или ограничен, храните копии манифестов локально в вашем mirror.
• Для корпоративных сред настройте внутренний Apt/Container registry и обновляйте пакеты из локального зеркала.

Резюме

Kubeadm упрощает многие шаги настройки кластера Kubernetes, но требует соблюдения ряда предварительных условий: установленный CRI, отключённый swap, загруженный br_netfilter и установленный сетевой аддон. Для сред разработки kubeadm даёт гибкость и близость к upstream Kubernetes; для быстрой локальной работы стоит рассмотреть Minikube или MicroK8s.

Важные проверки при возникновении проблем: статус containerd, отключение swap, наличие br_netfilter и корректность установки сетевого аддона.

Ключевые ресурсы и команды для копирования из статьи сохранены в кодовых блоках выше. Следуйте пошагово и тестируйте после каждого крупного шага.