KubeSphere на Ubuntu 22.04 через KubeKey

логотип или схема кластера KubeSphere

О чём этот материал

Это подробный практический гайд для инженеров DevOps и системных администраторов. Пошагово рассматривается:

подготовка трёх серверов Ubuntu 22.04;
создание пользователя с sudo без пароля;
настройка SSH‑ключей для безпарольного доступа;
установка зависимостей;
загрузка и использование KubeKey (kk) для автоматического развёртывания Kubernetes и KubeSphere;
проверка работоспособности кластера и деплой простого приложения (Nginx);
операционные рекомендации, чек‑листы и сценарии отката.

Краткие определения:

Kubernetes — система оркестрации контейнеров; управляет подами, сервисами и сетями.
KubeSphere — веб‑панель управления и набор дополнительных модулей поверх Kubernetes.
KubeKey (kk) — утилита для автоматизированного развёртывания Kubernetes и KubeSphere.

Основные преимущества метода

Быстрое автоматическое развёртывание мульти‑нодового кластера.
Готовая админ‑панель для управления приложениями и DevOps‑пайплайнами.
Подходит для гибридных и локальных сред.

Содержание

Предварительные требования
Подготовка хостов и пользователя
Настройка SSH‑ключей
Установка зависимостей
Загрузка KubeKey
Создание конфигурации развёртывания
Запуск развёртывания
Верификация кластера и деплой Nginx
Чек‑листы для ролей
Критерии приёмки
Тесты и контрольные проверки
Отказоустойчивость, откат и инструкция при инциденте
Альтернативные подходы и когда этот метод не подходит
Безопасность и рекомендации по жёсткомуening
Краткие заметки по совместимости и миграции
Краткое резюме

Предварительные требования

Чтобы следовать инструкции, подготовьте:

Три сервера с Ubuntu 22.04. Рекомендуется выделить 2 CPU и 4–8 ГБ RAM на узел для минимального тестового кластера.
Один сервер будет контроллером (control‑plane/etcd), два — worker‑ноды.
Нету ограничений на виртуальные или физические сервера, но стабильная сеть и доступность между ними обязательны.
Нетривиальный доступ: на всех серверах должен быть пользователь с правами sudo. В инструкции используется пользователь ubuntu с возможностью sudo без пароля.
SSH‑доступ между мастер‑узлом и рабочими узлами.
Доступ к интернету для загрузки бинарей и образов (в офлайн‑сценариях потребуется подготовленный локальный registry и зеркала).

Важно: если вы развертываете в изолированной сети, подготовьте локальные зеркала пакетов и registry‑mirror.

Подготовка хостов и пользователя

На всех серверах сделайте однотипные действия: отредактируйте /etc/hosts, создайте пользователя ubuntu и разрешите ему использовать sudo без пароля.

Откройте /etc/hosts на каждом сервере:

sudo nano /etc/hosts

Добавьте соответствия IP ↔ hostname (пример вашей сети):

192.168.5.35    master    master
192.168.5.121   node1     node1
192.168.5.122   node2     node2

Сохраните файл и закройте редактор.

Создайте пользователя ubuntu и установите пароль:

sudo useradd -m -s /bin/bash ubuntu
sudo passwd ubuntu

Добавьте правило sudo без пароля для пользователя ubuntu. На всех серверах выполните:

cat <

После этого перейдите к настройке SSH‑ключей.

`Настройка SSH‑доступа по ключу (без пароля)`

Этот шаг гарантирует, что мастер‑узел сможет подключаться к рабочим узлам для установки пакетов и выполнения команд через KubeKey.

На master выполните вход под пользователем ubuntu и сгенерируйте ключ:

su - ubuntu
ssh-keygen -t ed25519

По умолчанию ключи сохранятся в ~/.ssh/id_ed25519 и ~/.ssh/id_ed25519.pub.

Скопируйте публичный ключ на все узлы (включая localhost):

ssh-copy-id ubuntu@master
ssh-copy-id ubuntu@node1
ssh-copy-id ubuntu@node2

При первом подключении подтвердите fingerprint (yes) и введите пароль пользователя. После успешного копирования вы увидите сообщение вроде “Number of key(s) added: 1”.

Примеры вывода при копировании ключа на локальный хост и узлы приведены ниже.

Проверьте подключение:

ssh ubuntu@node1
ssh ubuntu@node2

Если подключение проходит без запроса пароля — настройка успешна.

`Установка зависимостей на всех узлах`

KubeKey будет устанавливать kubeadm и другие компоненты, но требуются базовые системные утилиты. Выполните эти команды с мастер‑узла и по SSH на каждом рабочем узле.

На master:

sudo apt update
sudo apt install -y curl socat conntrack ebtables ipset

ssh-keyscan -H master >> ~/.ssh/known_hosts

На node1 и node2 (подключившись через ssh ubuntu@nodeX):

sudo apt update
sudo apt install -y curl socat conntrack ebtables ipset

Эти пакеты используются сетевыми и системными компонентами Kubernetes.

Примечание: используйте ключ -y для автоматического подтверждения.

`Загрузка KubeKey на мастер`

KubeKey — однобинарный инструмент для развёртывания Kubernetes и KubeSphere. Скачайте последнюю совместимую версию или укажите определённую.

На master выполните:

curl -sfL https://get-kk.kubesphere.io | VERSION=v3.0.2 sh -
chmod +x kk

Проверьте версию и доступные параметры:

./kk version
./kk help

В директории появится исполняемый файл kk. KubeKey поддерживает развёртывание с KubeSphere и без, а также установку дополнительных аддонов.

`Генерация конфигурации KubeKey`

Для мульти‑нодового развёртывания удобнее подготовить YAML‑файл с описанием хостов и ролей. KubeKey может сгенерировать шаблон, который вы затем отредактируете.

Сгенерируйте конфиг и укажите версии Kubernetes и KubeSphere (пример):

./kk create config -f deployment-kubesphre.yml --with-kubernetes v1.24.2 --with-kubesphere v3.3.1

Откройте получившийся файл:

nano deployment-kubesphre.yml

Отредактируйте блок metadata и hosts согласно вашей сети. Пример содержания:

apiVersion: kubekey.kubesphere.io/v1alpha2
kind: Cluster
metadata:
  name: testdeployment
spec:
  hosts:
  - {name: master, address: 192.168.5.35, internalAddress: 192.168.5.35, user: ubuntu, privateKeyPath: "~/.ssh/id_ed25519"}
  - {name: node1, address: 192.168.5.121, internalAddress: 192.168.5.121, user: ubuntu, privateKeyPath: "~/.ssh/id_ed25519"}
  - {name: node2, address: 192.168.5.122, internalAddress: 192.168.5.122, user: ubuntu, privateKeyPath: "~/.ssh/id_ed25519"}
  roleGroups:
    etcd:
    - master
    control-plane:
    - master
    worker:
    - node1
    - node2

Сохраните файл. KubeKey будет использовать указанный приватный ключ для SSH‑подключения при установке.

Советы:

Убедитесь, что путь privateKeyPath указывает на существующий приватный ключ на master.
Если вы используете нестандартные SSH‑порты или прокси, внесите соответствующие поля в конфиг.

`Развёртывание Kubernetes и KubeSphere`

Запустите развертывание командой:

./kk create cluster -f deployment-kubesphre.yml

KubeKey выполнит предварительную проверку требований, затем попросит подтвердить действие. Подтвердите вводом yes.

Примерное время установки для минимальной конфигурации — от 5 до 20 минут, в зависимости от сети и производительности узлов.

По завершении в выводе вы увидите сведения о кластере и учетные данные для KubeSphere (логин и временный пароль). Скопируйте их и сохраните в безопасном месте.

`Первичный вход в KubeSphere`

Откройте браузер и перейдите по адресу:

http://:30880/

Например:

http://192.168.5.35:30880/

Войдите под учётной записью admin и временным паролем (по умолчанию P@88w0rd в примере). Система предложит сменить пароль — обязательно выполните это.

После входа в панель вы увидите дашборд KubeSphere с версией и списком доступных кластеров.

Перейдите в Platform → Cluster Management, чтобы увидеть ваш кластер и его состояние.

`Проверка узлов и системных компонентов`

Через консоль master проверьте список нод:

kubectl get nodes

Ожидаемый результат — три ноды в статусе Ready (или Initializing сразу после установки).

kubectl describe node

Просмотрите также системные поды во всех неймспейсах:

kubectl get pods --all-namespaces

Вам будут доступны неймспейсы kube-system, kubesphere-system, kubesphere-control-system, kubesphere-monitoring-system и т. п., с контейнерами в состоянии Running.

`Деплой тестового приложения (Nginx)`

Проверим, что кластер работает, развернув простой Nginx‑деплоймент.

Создайте деплоймент с 2 репликами:

kubectl create deployment nginx --image=nginx:alpine --replicas=2

Создайте сервис NodePort, чтобы открыть доступ извне:

kubectl create service nodeport nginx --tcp=80:80

Проверьте поды и сервисы:

kubectl get pods
kubectl get svc

NodePort будет проброшен на одном из портов диапазона (в примере — 32241). Получив порт на хосте, выполните curl с любого узла к nodeX:PORT или на внутреннем IP кластера:

curl 10.233.14.102
curl node1:32241
curl node2:32241

Результат — HTML главной страницы Nginx.

В интерфейсе KubeSphere вы увидите Workloads → Deployments и сервисы в разделе Services.

`Роль‑ориентированные чек‑листы`

Чек‑листы упрощают контроль на этапе подготовки, развёртывания и верификации.

Оператор / Инженер по развёртыванию:

Уверен, что все три узла доступны по сети.
/etc/hosts синхронизирован на всех машинах.
Пользователь ubuntu создан и добавлен в sudoers.d без пароля.
SSH ключи сгенерированы и добавлены на все узлы.
Установлены базовые пакеты (curl, socat, conntrack, ebtables, ipset).
Файл deployment-kubesphre.yml настроен и privateKeyPath корректен.
Выполнен ./kk create cluster и подтверждение прошло успешно.
Сохранены учетные данные KubeSphere.

DevOps / Сетевой инженер:

Проверил доступность портов межузловых соединений.
Проверил MTU и сетевые политики (если есть).
Убедился, что CNI‑плагин (по умолчанию KubeKey установит подходящий) корректно настроился.

Администратор безопасности:

Сменил пароль admin сразу после первичного входа.
Проверил права доступа в KubeSphere и RBAC в Kubernetes.
Проверил TLS и сертификаты, при необходимости настроил собственный CA.

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

Кластер считается готовым для начальной эксплуатации, когда выполнены следующие условия:

Все узлы отображаются в kubectl get nodes со статусом Ready.
Системные поды в kube-system и kubesphere-* находятся в состоянии Running.
KubeSphere доступна по веб‑интерфейсу и выполнен вход под админом.
Тестовый Nginx‑деплоймент с 2 репликами работает и доступен по NodePort с хотя бы одного узла.

`Тестовые сценарии и критерии приёмки`

Проверка подключения kubelet: kubectl get nodes — все Ready.
Проверка системных подов: kubectl get pods -n kube-system — нет CrashLoopBackOff.
Проверка доступа к KubeSphere: HTTP 200 на порт 30880 и возможность смены пароля.
Проверка сетевого доступа: curl service IP и NodePort с обеих worker‑нод.

`Инцидентный план и откат`

Краткий runbook при критических ошибках во время развёртывания:

Отключите автоматический прогресс: не перезапускайте процессы, если вы не уверены.
Просмотрите логи KubeKey на master: вывод kk содержит ошибки и подсказки.
Если проблема связана с SSH, проверьте ~/.ssh/authorized_keys и права доступа.
Если часть узлов не прошла установку, выполните восстановление на конкретном узле:Подключитесь по SSH и проверьте логи /var/log и systemd‑юниты kubelet.
Для полного отката можно удалить кластер командой (только если требуется чистая переустановка):

./kk delete cluster -f deployment-kubesphre.yml

После удаления вручную очистите оставшиеся Docker/containerd данные и iptables, если необходимо.

Важно: удаление кластера — деструктивная операция. Делайте бэкап данных etcd перед финальным удалением в продуктивной среде.

`Когда этот подход не подходит и альтернативы`

Когда не выбирать KubeKey + KubeSphere:

Ограниченная офлайн‑среда без доступа к образам и пакетам — потребуется подготовка зеркал.
Требуется очень тонкая настройка kubeadm с нестандартными параметрами, не поддерживаемыми KubeKey.
Нужна enterprise‑поддержка с SLA выше самоподдерживаемого решения.

Альтернативы:

kubeadm — ручная установка и управление; даёт максимальную гибкость, но требует больше ручной работы.
k3s — лёгкая версия Kubernetes для edge/IoT, упрощённая конфигурация.
Rancher — комплексная платформа управления кластерами с UI и мультикластерностью.
OpenShift — корпоративная платформа с дополнительными требованиями лицензирования.

`Ментальные модели и рекомендации`

Модели для принятия решений при развёртывании:

Разделение ответственности: master/etcd vs worker — держите etcd на отказоустойчивых узлах (не на временных виртуалках).
Идём от минимального рабочего варианта к продуктовой стабильности: сначала один контрольный плейн + два воркера, затем масштабирование.
Сетевой слой: CNI и MTU — любые сетевые проблемы чаще всего проявляются как проблемы с подами, не поднимающимися.
Бэкап etcd — критически важен для восстановления кластера.

`Безопасность и жёсткие настройки`

Ключевые рекомендации по безопасности:

Смените временный пароль admin сразу после входа.
Настройте RBAC и роли в KubeSphere в соответствии с принципом наименьших привилегий.
Включите TLS‑шифрование и используйте действительные сертификаты (при необходимости интегрируйте с внутренним CA).
Ограничьте доступ к API‑серверу через firewall и/или API‑Gateway.
Отключите доступ по паролю SSH (оставьте только ключи).
Мониторьте логи и установите систему оповещений (Prometheus + Alertmanager / внешние SLM).

Примечание о приватности: KubeSphere собирает информацию о состоянии кластера только в рамках админ‑панели. Обратите внимание на регламенты GDPR, если в логах или метриках появляются персональные данные.

`Совместимость и миграция`

Проверяйте совместимость версий KubeSphere и Kubernetes перед развёртыванием (в конфиге указаны совместимые пары).
При обновлении KubeSphere используйте рекомендованные процедуры в официальной документации.
Для миграции приложений между кластерами используйте стандартные инструменты: kubectl manifests, Helm charts, Velero для бэкапа/восстановления.

`Быстрый SOP для повторного развёртывания`

Подготовить три сервера с Ubuntu 22.04 и сетевыми настройками.
Создать ubuntu-пользователя и добавить sudo без пароля.
Сгенерировать SSH‑ключ на master и разнести на все узлы.
Установить базовые пакеты на всех узлах.
Скачать kk, сделать его исполняемым.
Создать конфигурационный YAML командой kk create config и отредактировать hosts.
Запустить ./kk create cluster -f deployment-kubesphre.yml.
Войти в KubeSphere, сменить пароль, проверить pods и nodes.
Развернуть тестовое приложение и убедиться в доступности.

`Частые проблемы и способы устранения`

Проблема: узел в состоянии NotReady

Проверьте службу kubelet: sudo systemctl status kubelet
Посмотрите логи: sudo journalctl -u kubelet -b
Проверьте сетевые настройки и доступность DNS.

Проблема: CrashLoopBackOff для системного пода

kubectl describe pod -n
kubectl logs -n — найти причину падения.

Проблема: KubeSphere недоступен по HTTP

Проверьте, слушает ли порт 30880 на master: sudo ss -ltnp | grep 30880
Убедитесь, что firewall/iptables не блокируют порт.

`Факто‑бокс: ключевые параметры`

Количество узлов в примере: 3 (1 master, 2 worker)
Порт по умолчанию для KubeSphere UI в этом развёртывании: 30880
Версия Kubernetes в примере: v1.24.2
Версия KubeSphere в примере: v3.3.1
Команда для запуска KubeKey: ./kk create cluster -f deployment-kubesphre.yml

`Пример диаграммы принятия решения по развёртыванию (Mermaid)`

flowchart TD
  A[Есть сетевой доступ к интернету?] -->|Да| B[Использовать KubeKey]
  A -->|Нет| C[Подготовить офлайн зеркала]
  C --> D{Можно ли подготовить зеркало?}
  D -->|Да| B
  D -->|Нет| E[Рассмотреть локальные решения: k3s или ручной kubeadm]
  B --> F[Выбрать версии Kubernetes и KubeSphere]
  F --> G[Сгенерировать config и отредактировать hosts]
  G --> H[Запустить ./kk create cluster]
  H --> I{Успешно?}
  I -->|Да| J[Проверить pods и войти в KubeSphere]
  I -->|Нет| K[Откат/анализ логов]

`Локальные альтернативы и подводные камни для России и СНГ`

При развёртывании в закрытых сетях российских дата‑центров заранее проверьте доступность зеркал apt и контейнерных registry. Часто требуется проксирование или собственные зеркала.
Если политика безопасности запрещает публичные образы, подготовьте приватный registry и настройте KubeKey/CRs для использования зеркала.

`Список полезных команд сводкой`

SSH‑доступ и проверка:

ssh ubuntu@node1
ssh ubuntu@node2

Основные команды kube‑ctl:

kubectl get nodes
kubectl get pods --all-namespaces
kubectl describe node 
kubectl create deployment nginx --image=nginx:alpine --replicas=2
kubectl create service nodeport nginx --tcp=80:80

Управление KubeKey:

./kk version
./kk create config -f deployment-kubesphre.yml --with-kubernetes v1.24.2 --with-kubesphere v3.3.1
./kk create cluster -f deployment-kubesphre.yml
./kk delete cluster -f deployment-kubesphre.yml

`Заключение`

В этой инструкции вы прошли полный цикл развёртывания Kubernetes и KubeSphere на Ubuntu 22.04 с помощью KubeKey: подготовили сервера, настроили SSH‑доступ, установили зависимости, сгенерировали конфигурационный файл, развернули кластер и проверили работоспособность через деплой Nginx. KubeKey значительно упрощает начальную установку, но при переходе в продуктивную эксплуатацию важно позаботиться о безопасности, резервных копиях etcd и процедурах обновления.

Важно:

Смена пароля admin и настройка RBAC — обязательны.
Регулярно делайте резервные копии etcd.

Дополнительные ресурсы: обратитесь к официальной документации KubeSphere и Kubernetes для продвинутых сценариев обновления и интеграции.

Развёртывание Kubernetes и KubeSphere на Ubuntu 22.04 с помощью KubeKey