Установка k3s на Linux: кластер из server и agent-узлов

K3s — компактный дистрибутив Kubernetes, в котором API server, scheduler, controller manager, containerd и необходимые системные компоненты поставляются как единое решение. Одного server-узла достаточно для лаборатории и некритичного внутреннего сервиса. Для производственной отказоустойчивости архитектуру, хранилище и резервное копирование нужно спроектировать до установки.

Ниже создадим учебный кластер из Linux-сервера 10.20.30.11 и agent-узла 10.20.30.21. Kubernetes API не будет открыт в интернет: узлы находятся в серверном VLAN, а администратор подключается через управляющую сеть или VPN. Команды запускайте сначала на тестовых машинах и сверяйте версию с официальной документацией k3s.

Архитектура и требования

Server хранит состояние кластера и запускает компоненты control plane. Agent запускает рабочие Pod через kubelet и containerd. В односерверной установке по умолчанию используется SQLite; она проста, но не подходит для нескольких server-узлов. Для HA применяют три или больше server-узла с embedded etcd либо поддерживаемую внешнюю базу.

У каждого узла должны быть уникальное имя, стабильный IP или DNS-имя, синхронизированное время и быстрый диск. K3s рекомендует SSD, поскольку производительность кластера зависит от хранилища данных. Минимальные характеристики годятся для лаборатории; production-размер рассчитывают по количеству узлов, Pod и активности API.

Сетевой план

По умолчанию k3s использует 10.42.0.0/16 для Pod и 10.43.0.0/16 для Service. Эти диапазоны не должны пересекаться с офисными VLAN, VPN, филиалами и облачными сетями. Если пересечение возможно, выберите собственные диапазоны до первого запуска: менять их в работающем кластере значительно сложнее.

Server должен принимать TCP 6443 от узлов и администраторских адресов. При стандартном Flannel VXLAN узлам требуется UDP 8472 друг к другу; этот порт нельзя открывать всему интернету. Для metrics-server нужен TCP 10250 между узлами. HA с embedded etcd дополнительно использует TCP 2379–2380 между server-узлами. Открывайте только тот набор, который соответствует выбранному CNI и архитектуре.

Подготовка Linux

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

# На первом узле
sudo hostnamectl set-hostname k3s-server-1

# На рабочем узле
sudo hostnamectl set-hostname k3s-agent-1

ip -br address
ip route
timedatectl status

Установите обновления штатным способом дистрибутива и перезагрузитесь, если обновилось ядро. Убедитесь, что NetworkManager или другой сетевой менеджер поддерживает выбранную конфигурацию. Не отключайте firewall: добавьте точечные правила между известными подсетями.

Закрепление версии

Команда с get.k3s.io удобна, но в воспроизводимой инфраструктуре не следует каждый раз устанавливать случайную «последнюю» версию. Выберите поддерживаемый релиз после проверки release notes и задайте его через INSTALL_K3S_VERSION. Пример ниже содержит заполнитель, который необходимо заменить:

export INSTALL_K3S_VERSION='vX.Y.Z+k3sN'
curl -sfL https://get.k3s.io -o /tmp/install-k3s.sh
less /tmp/install-k3s.sh
sudo --preserve-env=INSTALL_K3S_VERSION sh /tmp/install-k3s.sh

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

Конфигурация server через YAML

Параметры удобнее хранить в /etc/rancher/k3s/config.yaml, а не в длинной строке systemd. Перед установкой создайте каталог и файл:

sudo install -d -m 0755 /etc/rancher/k3s
sudoedit /etc/rancher/k3s/config.yaml

Минимальный учебный пример:

write-kubeconfig-mode: "0600"
node-ip: 10.20.30.11
cluster-cidr: 10.42.0.0/16
service-cidr: 10.43.0.0/16
secrets-encryption: true
tls-san:
  - k3s-api.corp.example
  - 10.20.30.11

Имена в tls-san должны указывать на реальные адреса, по которым администраторы и узлы обращаются к API. Не добавляйте произвольные внешние имена. Значения cluster-cidr, service-cidr и ряда других критичных параметров обязаны совпадать на всех server-узлах.

Проверка первого server

После установки проверьте службу и системные Pod:

sudo systemctl status k3s --no-pager
sudo journalctl -u k3s -n 100 --no-pager
sudo k3s kubectl get nodes -o wide
sudo k3s kubectl get pods -A

Файл kubeconfig создаётся в /etc/rancher/k3s/k3s.yaml. Не делайте его доступным всем пользователям и не отправляйте в чат: учётные данные дают административные полномочия. Для удалённой рабочей станции создайте ограниченный доступ согласно RBAC, а не копируйте бессрочный admin-конфиг без контроля.

Подключение agent-узла

Токен регистрации находится на server в /var/lib/rancher/k3s/server/node-token. Считайте его секретом. Передавайте токен на agent через защищённый канал или систему управления секретами, не сохраняйте в shell history.

На agent можно подготовить /etc/rancher/k3s/config.yaml:

server: https://k3s-api.corp.example:6443
token: "ЗАМЕНИТЕ_СЕКРЕТОМ"
node-ip: 10.20.30.21
node-label:
  - "node-role.corp/worker=true"

Затем загрузите, просмотрите и запустите тот же установщик с той же закреплённой версией, указав режим agent:

export INSTALL_K3S_VERSION='vX.Y.Z+k3sN'
curl -sfL https://get.k3s.io -o /tmp/install-k3s.sh
less /tmp/install-k3s.sh
sudo --preserve-env=INSTALL_K3S_VERSION sh /tmp/install-k3s.sh agent

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

sudo k3s kubectl get nodes -o wide
sudo k3s kubectl describe node k3s-agent-1

Первый тестовый workload

Не начинайте с бизнес-приложения. Создайте отдельный namespace, простой Deployment и внутренний Service, затем проверьте DNS, сеть и удаление. Манифесты храните в Git и применяйте из проверенного состояния. Не используйте тег образа latest в production — закрепляйте версию или digest.

kubectl create namespace lab
kubectl -n lab create deployment web --image=nginx:1.27-alpine
kubectl -n lab expose deployment web --port=80 --type=ClusterIP
kubectl -n lab rollout status deployment/web
kubectl -n lab get pods,svc -o wide

После теста удалите весь namespace: kubectl delete namespace lab. Не публикуйте NodePort в корпоративной сети без отдельного правила firewall и документации владельца.

Резервное копирование до production

Резервная копия приложения состоит не только из YAML. Нужны состояние datastore, данные PersistentVolume, внешние базы, ключи шифрования и инструкции восстановления. Для single-server SQLite резервируйте каталог данных по официальной процедуре. Для embedded etcd используйте снимки k3s и обязательно копируйте server token: без него восстановление зашифрованных данных может оказаться невозможным.

Проверяйте восстановление на отдельной инфраструктуре. Наличие файла в объектном хранилище не доказывает, что из него запускается кластер и приложение возвращает корректные данные.

Документация и следующие шаги

• K3s Quick Start;
• требования и сетевые порты k3s;
• варианты конфигурации k3s;
• HA с embedded etcd;
• сегментация корпоративной сети на Netcraze.

Статья может содержать партнёрские ссылки. Это не влияет на стоимость для вас, но помогает развивать блог.