RU

Приложения

Установка Kubernetes с помощью K3s

Установите K3s на Debian или Ubuntu, работайте с kubectl, разверните первое приложение, добавьте узел и защитите порты кластера.

7 мин чтения, обновлено 18 ноября 2026 г.

На этой странице

Ваши значения

Укажите их один раз, и команды в руководстве обновятся.

K3s — это облегчённый сертифицированный дистрибутив Kubernetes, поставляемый в виде одного бинарного файла. Он хорошо подходит для VPS или выделенного сервера: в него, в частности, встроены kubectl, Ingress-контроллер Traefik, простой балансировщик нагрузки и локальное хранилище.

Это руководство проведёт вас от установки до кластера из двух узлов под управлением Debian 12/13 или Ubuntu 22.04/24.04:

  1. установить серверный узел;
  2. использовать kubectl, не открывая API наружу;
  3. развернуть первое приложение;
  4. добавить узел-агент;
  5. обновить и сохранить резервную копию кластера.

Заказать сервер

Для размещения вашего кластера 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 enable

10.42.0.0/16 — сеть подов по умолчанию, а 10.43.0.0/16 — сеть служб.

Установка серверного узла

Подготовьте конфигурацию до установки. Так сеть кластера будет зашифрована с самого начала, и позже вы сможете добавить узел через Интернет.

Терминал
sudo mkdir -p /etc/rancher/k3s
sudo nano /etc/rancher/k3s/config.yaml
YAML
node-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 nodes

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

Развёртывание первого приложения

Создайте манифест:

Терминал
nano demo.yaml
YAML
apiVersion: 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/ping
  • connection 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.

Справочные материалы