Установка Kubernetes с помощью K3s
Установите K3s на Debian или Ubuntu, работайте с kubectl, разверните первое приложение, добавьте узел и защитите порты кластера.
На этой странице
Ваши значения
Укажите их один раз, и команды в руководстве обновятся.
K3s — это облегчённый сертифицированный дистрибутив Kubernetes, поставляемый в виде одного бинарного файла. Он хорошо подходит для VPS или выделенного сервера: в него, в частности, встроены kubectl, Ingress-контроллер Traefik, простой балансировщик нагрузки и локальное хранилище.
Это руководство проведёт вас от установки до кластера из двух узлов под управлением Debian 12/13 или Ubuntu 22.04/24.04:
- установить серверный узел;
- использовать
kubectl, не открывая API наружу; - развернуть первое приложение;
- добавить узел-агент;
- обновить и сохранить резервную копию кластера.
Заказать сервер
Для размещения вашего кластера HostMyServers предлагает несколько вариантов:
Предварительные требования
| Роль | Минимум CPU | Минимум ОЗУ |
|---|---|---|
| Сервер | 2 ядра | 2 ГБ |
| Агент | 1 ядро | 512 МБ |
Эти значения взяты из документации K3s и не включают ресурсы ваших приложений.
Вам также понадобятся:
- SSH-доступ с пользователем, имеющим права
sudo; - разные имена хостов на каждом узле;
- IP-адрес, доступный другим узлам, как правило, публичный;
- модуль ядра WireGuard, если ваши узлы общаются через Интернет.
Проверьте наличие WireGuard на каждом узле:
sudo modprobe wireguard && lsmod | grep wireguardПорты
| Порт | Протокол | Источник | Назначение |
|---|---|---|---|
| 22 | TCP | Ваш компьютер | SSH и туннель к API |
| 6443 | TCP | Агенты | API Kubernetes и супервизор K3s |
| 10250 | TCP | Все узлы | Метрики и API kubelet |
| 51820 | UDP | Все узлы | Flannel WireGuard по IPv4 |
| 51821 | UDP | Все узлы | Flannel WireGuard по IPv6, если используется |
| 80, 443 | TCP | Интернет | Приложения, опубликованные через Traefik |
Подготовка сервера
sudo apt update
sudo apt upgrade -y
sudo apt install -y curl ufwДокументация K3s рекомендует отключить UFW, но сервер, доступный из Интернета, должен оставаться под фильтрацией. Если вы оставляете UFW, как здесь, внутренние сети K3s нужно разрешить. Замените 22, если вы используете другой порт SSH:
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 22/tcp
sudo ufw allow 80,443/tcp
sudo ufw allow from 10.42.0.0/16 to any
sudo ufw allow from 10.43.0.0/16 to any
sudo ufw enable10.42.0.0/16 — сеть подов по умолчанию, а 10.43.0.0/16 — сеть служб.
Установка серверного узла
Подготовьте конфигурацию до установки. Так сеть кластера будет зашифрована с самого начала, и позже вы сможете добавить узел через Интернет.
sudo mkdir -p /etc/rancher/k3s
sudo nano /etc/rancher/k3s/config.yamlnode-external-ip: IP_ВАШЕГО_СЕРВЕРА
flannel-backend: wireguard-native
flannel-external-ip: true
tls-san:
- IP_ВАШЕГО_СЕРВЕРАЗатем установите K3s официальным скриптом, который по умолчанию использует канал stable:
curl -sfL https://get.k3s.io | sh -Проверьте службу и узел. Переход в состояние Ready может занять минуту:
sudo systemctl status k3s --no-pager
sudo k3s kubectl get nodes -o wide
sudo k3s kubectl get pods -AИспользование kubectl
Файл /etc/rancher/k3s/k3s.yaml даёт полный административный доступ к кластеру и доступен для чтения только root. Не делайте его доступным для всех. Лучше создайте личную копию:
mkdir -p ~/.kube
install -m 600 /dev/null ~/.kube/config
sudo k3s kubectl config view --raw > ~/.kube/config
echo 'export KUBECONFIG="$HOME/.kube/config"' >> ~/.bashrc
export KUBECONFIG="$HOME/.kube/config"
kubectl get nodesУправление кластером с вашего компьютера
SSH-туннель позволяет не открывать порт 6443 для вашего компьютера. Установите kubectl на свою машину, затем скопируйте конфигурацию:
mkdir -p ~/.kube
scp ВАШ_ПОЛЬЗОВАТЕЛЬ@IP_ВАШЕГО_СЕРВЕРА:.kube/config ~/.kube/k3s-hms
chmod 600 ~/.kube/k3s-hms
ssh -N -L 6443:127.0.0.1:6443 ВАШ_ПОЛЬЗОВАТЕЛЬ@IP_ВАШЕГО_СЕРВЕРАОставьте этот туннель открытым и в другом терминале выполните:
export KUBECONFIG=~/.kube/k3s-hms
kubectl get nodesK3s обновляет сертификаты своего административного файла при каждом запуске. Если ваша копия перестала работать, скопируйте её заново.
Развёртывание первого приложения
Создайте манифест:
nano demo.yamlapiVersion: v1
kind: Namespace
metadata:
name: demo
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: web
namespace: demo
spec:
replicas: 2
selector:
matchLabels:
app: web
template:
metadata:
labels:
app: web
spec:
containers:
- name: nginx
image: nginx:stable-alpine
ports:
- containerPort: 80
resources:
requests:
cpu: 50m
memory: 32Mi
limits:
memory: 128Mi
---
apiVersion: v1
kind: Service
metadata:
name: web
namespace: demo
spec:
selector:
app: web
ports:
- port: 80
targetPort: 80
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web
namespace: demo
spec:
ingressClassName: traefik
rules:
- host: demo.ваш-домен.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: web
port:
number: 80Примените его и проследите за развёртыванием:
kubectl apply -f demo.yaml
kubectl -n demo rollout status deployment/web
kubectl -n demo get pods,svc,ingressПроверьте приложение с вашего компьютера, даже если DNS ещё не настроен:
curl -H 'Host: demo.ваш-домен.com' http://IP_ВАШЕГО_СЕРВЕРА/Вы должны получить стартовую страницу Nginx.
Удалите пример, когда он станет не нужен:
kubectl delete namespace demoДобавление узла-агента
В этом разделе IP_АГЕНТА обозначает IP-адрес нового узла.
Открытие трафика между узлами
На сервере:
sudo ufw allow from IP_АГЕНТА to any port 6443 proto tcp
sudo ufw allow from IP_АГЕНТА to any port 10250 proto tcp
sudo ufw allow from IP_АГЕНТА to any port 51820 proto udpНа агенте:
sudo apt update
sudo apt install -y curl ufw
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 22/tcp
sudo ufw allow 80,443/tcp
sudo ufw allow from 10.42.0.0/16 to any
sudo ufw allow from 10.43.0.0/16 to any
sudo ufw allow from IP_ВАШЕГО_СЕРВЕРА to any port 10250 proto tcp
sudo ufw allow from IP_ВАШЕГО_СЕРВЕРА to any port 51820 proto udp
sudo ufw enableПорты 80 и 443 нужны на агенте, поскольку Traefik может быть опубликован на каждом узле. Если узлов больше двух, откройте порты 10250/TCP и 51820/UDP между всеми узлами.
Подключение к кластеру
На сервере выведите токен:
sudo cat /var/lib/rancher/k3s/server/node-tokenНа агенте укажите его внешний адрес, затем запустите установку. Команда read ждёт, пока вы вставите токен, не отображая его и не сохраняя в истории:
sudo mkdir -p /etc/rancher/k3s
echo 'node-external-ip: IP_АГЕНТА' | sudo tee /etc/rancher/k3s/config.yaml
read -rs K3S_TOKEN
curl -sfL https://get.k3s.io | K3S_URL=https://IP_ВАШЕГО_СЕРВЕРА:6443 K3S_TOKEN="$K3S_TOKEN" sh -
unset K3S_TOKEN
sudo systemctl status k3s-agent --no-pagerНа сервере новый узел должен появиться в состоянии Ready:
kubectl get nodes -o wideОбновление K3s
Сначала сделайте резервную копию кластера и прочитайте примечания к выпуску. Обновляйте сначала серверы, по одному, затем агенты, не пропуская минорные версии Kubernetes.
На сервере снова запустите скрипт. Конфигурация из config.yaml сохраняется:
curl -sfL https://get.k3s.io | sh -На каждом агенте передайте те же переменные:
read -rs K3S_TOKEN
curl -sfL https://get.k3s.io | K3S_URL=https://IP_ВАШЕГО_СЕРВЕРА:6443 K3S_TOKEN="$K3S_TOKEN" sh -
unset K3S_TOKENЕсли ваш кластер отстаёт на несколько минорных версий, обновляйтесь поэтапно с соответствующим каналом, например:
curl -sfL https://get.k3s.io | INSTALL_K3S_CHANNEL=v1.36 sh -Затем проверьте версии командой kubectl get nodes.
Резервное копирование и восстановление
При использовании SQLite сохраняйте базу и токен сервера: без этого токена резервная копия бесполезна. Остановка K3s гарантирует согласованную копию и не останавливает уже запущенные контейнеры.
sudo systemctl stop k3s
sudo tar -czpf "/root/k3s-$(date +%F).tar.gz" /var/lib/rancher/k3s/server/db /var/lib/rancher/k3s/server/token /etc/rancher/k3s/config.yaml
sudo systemctl start k3s
sudo chmod 600 /root/k3s-*.tar.gzТома, созданные локальным хранилищем, находятся в /var/lib/rancher/k3s/storage. Сохраняйте их тоже, лучше всего — средствами самих приложений, например экспортом базы данных. Храните также ваши манифесты в приватном Git-репозитории.
Чтобы восстановить базу на сервере:
sudo systemctl stop k3s
sudo rm -rf /var/lib/rancher/k3s/server/db
sudo tar -xzpf /root/k3s-ГГГГ-ММ-ДД.tar.gz -C /
sudo systemctl start k3s
kubectl get nodesЕсли что-то не работает
Unable to read /etc/rancher/k3s/k3s.yaml
У вашего пользователя нет доступа к административному файлу. Вернитесь к разделу Использование kubectl и проверьте echo $KUBECONFIG. Не делайте этот файл доступным для всех с помощью --write-kubeconfig-mode 644.
Служба k3s не запускается
sudo journalctl -u k3s -n 80 --no-pager
sudo k3s check-configЕсли в журналах упоминается WireGuard, проверьте sudo modprobe wireguard. Если модуль недоступен в кластере из одного узла, перед новой установкой удалите flannel-backend и flannel-external-ip из config.yaml. Не заменяйте WireGuard на VXLAN между узлами, связанными через Интернет.
Агент не присоединяется к кластеру
sudo journalctl -u k3s-agent -n 80 --no-pager
curl -vk -m 5 https://IP_ВАШЕГО_СЕРВЕРА:6443/pingconnection refusedили превышено время ожидания: проверьте UFW и адрес вK3S_URL.- Недопустимый
token: заново скопируйте содержимоеnode-token. Node password rejected, duplicate hostname: другой узел носит то же имя, или этот узел уже был зарегистрирован. Измените имя хоста или удалите старый узел командойkubectl delete node ИМЯ_УЗЛА.
Узел остаётся в состоянии NotReady
kubectl describe node ИМЯ_УЗЛА
ip link show flannel-wgПроверьте порты 10250/TCP и 51820/UDP между узлами, а также значения node-external-ip.
Под остаётся в состоянии Pending или ImagePullBackOff
kubectl -n demo describe pod ИМЯ_ПОДА
kubectl -n demo logs ИМЯ_ПОДАPending часто сигнализирует о нехватке CPU или памяти. ImagePullBackOff указывает на неверное имя образа, отказ в доступе к реестру или лимит загрузок.
Ingress возвращает 404 или порты 80/443 не отвечают
kubectl -n kube-system get pods,svc | grep -E 'traefik|svclb'
sudo ss -tlnp | grep -E ':(80|443)\b'Ошибка 404 обычно означает, что заголовок Host не совпадает с полем host в Ingress. Если поды svclb остаются в состоянии Pending, вероятно, системная служба, например Nginx или Apache, уже занимает порты 80 и 443.
Удаление K3s
/usr/local/bin/k3s-uninstall.shНа агенте:
/usr/local/bin/k3s-agent-uninstall.shЧто дальше
Чтобы хранить образы контейнеров, обратитесь к руководству Установка Harbor. Чтобы автоматизировать подготовку ваших узлов, обратитесь к руководству Автоматизация серверов с помощью Ansible.