Розгортання легкова

Конфігурація

Після встановлення K3s кластер готовий до роботи, але для публікації застосунків у зовнішній світ та забезпечення їхньої безпеки (HTTPS) знадобиться додаткове налаштування. Ми розгорнемо Ingress-контролер і налаштуємо автоматичне отримання TLS-сертифікатів за допомогою Caddy.

1. Розгортання Ingress-контролера (Nginx Ingress Controller)

Хоча K3s за замовчуванням включає Traefik, ми його відключили, щоб мати більше контролю. Замість нього ми встановимо популярний Nginx Ingress Controller, який добре себе зарекомендував.

# Устанавливаем Nginx Ingress Controller через Helm
# Сначала добавляем репозиторий Helm
helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm repo update

# Устанавливаем Ingress Controller в namespace ingress-nginx
# Предполагаем версию 4.10.x для 2026 года
helm install ingress-nginx ingress-nginx/ingress-nginx \
    --namespace ingress-nginx --create-namespace \
    --set controller.service.type=NodePort \
    --set controller.service.nodePorts.http=30080 \
    --set controller.service.nodePorts.https=30443 \
    --version 4.10.1

Ми використовуємо NodePort для публікації Ingress-контролера на портах 30080 (HTTP) та 30443 (HTTPS) на VPS. Це дозволить нам проксіювати трафік через Caddy.

Перевірте, що поди Ingress-контролера запущені:

# Проверяем поды Ingress-контроллера
kubectl get pods -n ingress-nginx

Переконайтеся, що всі поди в статусі Running.

2. Встановлення Caddy як Reverse Proxy та ACME-клієнта

Caddy — це потужний веб-сервер з автоматичним HTTPS. Ми будемо використовувати його як зовнішній reverse proxy, який прийматиме трафік з портів 80/443, автоматично отримуватиме та оновлюватиме TLS-сертифікати, а потім проксіюватиме запити на Ingress-контролер K3s.

Створіть файл конфігурації Caddy за шляхом /etc/caddy/Caddyfile:

# Создаём директорию для конфига Caddy
sudo mkdir -p /etc/caddy

# Открываем файл Caddyfile для редактирования
sudo nano /etc/caddy/Caddyfile

Вставте наступний вміст, замінивши your-domain.com на ваш домен:

# /etc/caddy/Caddyfile
{
    email [email protected]
    # Включаем логирование для отладки
    log {
        output file /var/log/caddy/caddy.log
        level INFO
    }
}

your-domain.com {
    # Автоматический HTTPS
    reverse_proxy localhost:30080 {
        # Необходимо для корректной работы Ingress-контроллера
        header_up Host {http.request.host}
        header_up X-Real-IP {http.request.remote}
        header_up X-Forwarded-For {http.request.remote}
        header_up X-Forwarded-Proto {http.request.scheme}
    }
}

Збережіть файл (Ctrl+X, Y, Enter).

Створіть директорію для логів Caddy:

# Создаём директорию для логов Caddy и устанавливаем права
sudo mkdir -p /var/log/caddy
sudo chown caddy:caddy /var/log/caddy

Встановіть Caddy. Ми будемо використовувати офіційний репозиторій для Ubuntu:

# Устанавливаем зависимости
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https

# Добавляем ключ GPG Caddy
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg

# Добавляем репозиторий Caddy
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list

# Обновляем список пакетов и устанавливаем Caddy
sudo apt update
sudo apt install -y caddy

Увімкніть та запустіть сервіс Caddy:

# Запускаем Caddy
sudo systemctl enable caddy
sudo systemctl start caddy
sudo systemctl status caddy

Переконайтеся, що Caddy працює і не видає помилок. Якщо є проблеми, перевірте логи Caddy: sudo journalctl -u caddy --no-pager.

Важливо: переконайтеся, що ваш домен (your-domain.com) вказує на IP-адресу вашого VPS у DNS-записах (A-запис).

3. Розгортання першого застосунку (Nginx)

Розгорнемо простий веб-застосунок Nginx, щоб перевірити роботу кластера та Ingress-контролера.

Створіть файл nginx-app.yaml:

# Создаём файл манифеста Nginx
nano nginx-app.yaml

Вставте наступний вміст:

# nginx-app.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  labels:
    app: nginx
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.25.4-alpine # Актуальная версия на 2026 год
        ports:
        - containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
  name: nginx-service
spec:
  selector:
    app: nginx
  ports:
    - protocol: TCP
      port: 80
      targetPort: 80
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: nginx-ingress
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
spec:
  ingressClassName: nginx # Указываем, что это Ingress для Nginx Ingress Controller
  rules:
  - host: your-domain.com # Замените на ваш домен
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: nginx-service
            port:
              number: 80

Збережіть файл і застосуйте його до кластера:

# Применяем манифест Nginx
kubectl apply -f nginx-app.yaml

Перевірте статус розгортання:

# Проверяем поды Nginx
kubectl get pods -l app=nginx

# Проверяем сервис Nginx
kubectl get service nginx-service

# Проверяем Ingress Nginx
kubectl get ingress nginx-ingress

Переконайтеся, що под Nginx запущений, сервіс та Ingress існують.

4. Перевірка працездатності

Тепер, коли все налаштовано, відкрийте ваш домен (https://your-domain.com) у браузері. Ви повинні побачити стандартну вітальну сторінку Nginx. Якщо ви бачите її, значить, K3s, Nginx Ingress Controller та Caddy працюють коректно, і HTTPS-сертифікат був автоматично випущений та встановлений.

Якщо виникли проблеми, перевірте:

• Логи подів Nginx Ingress Controller: kubectl logs -n ingress-nginx -l app.kubernetes.io/name=ingress-nginx
• Логи Caddy: sudo journalctl -u caddy --no-pager
• DNS-записи вашого домену.
• Статус K3s: sudo systemctl status k3s

Ви також можете використовувати curl для перевірки доступності:

# Проверяем HTTP-доступ
curl http://your-domain.com

# Проверяем HTTPS-доступ
curl -k https://your-domain.com # -k игнорирует проверку сертификата, если есть проблемы

Резервне копіювання та обслуговування

Регулярне резервне копіювання та своєчасне обслуговування — запорука стабільності та безпеки вашого K3s кластера.

Що резервувати

Для K3s на одному вузлі, ключові дані для резервного копіювання:

• Конфігурація K3s: Файли /etc/rancher/k3s/k3s.yaml та /var/lib/rancher/k3s/server/node-token.
• Стан кластера (etcd): K3s використовує SQLite за замовчуванням, тому файл бази даних знаходиться за шляхом /var/lib/rancher/k3s/server/db/state.db. Якщо ви переналаштували K3s на використання зовнішнього etcd, вам потрібно резервувати etcd.
• Дані додатків: Якщо ваші додатки використовують постійні томи (Persistent Volumes), переконайтеся, що їхні дані резервуються. Для K3s за замовчуванням використовується локальний провізіонер PV, що означає, що дані зберігаються на диску самого VPS. Шлях зазвичай /var/lib/rancher/k3s/storage/....
• Конфігураційні файли Caddy/Nginx: /etc/caddy/Caddyfile.

Простий скрипт авторезервування

Ви можете створити простий скрипт для резервного копіювання ключових файлів та бази даних K3s. Приклад з використанням rsync та tar:

# Створіть файл /usr/local/bin/backup_k3s.sh
sudo nano /usr/local/bin/backup_k3s.sh

Вміст скрипта (замініть /path/to/backup/destination на ваш шлях):

#!/bin/bash

BACKUP_DIR="/tmp/k3s_backup_$(date +%Y%m%d%H%M%S)"
DESTINATION="/path/to/backup/destination" # Змініть на реальний шлях або S3 бакет

mkdir -p $BACKUP_DIR
mkdir -p $DESTINATION

echo "Starting K3s backup at $(date)"

# Резервне копіювання конфігурації K3s
cp /etc/rancher/k3s/k3s.yaml $BACKUP_DIR/k3s.yaml
cp /var/lib/rancher/k3s/server/node-token $BACKUP_DIR/node-token

# Резервне копіювання бази даних SQLite K3s
# K3s надає команду для створення знімка бази даних
sudo k3s etcd-snapshot --etcd-snapshot-dir $BACKUP_DIR

# Резервне копіювання даних Persistent Volumes (якщо використовуються локально)
# Увага: для реальних PV потрібна складніша стратегія (наприклад, Velero)
# cp -R /var/lib/rancher/k3s/storage/ $BACKUP_DIR/k3s-storage/

# Резервне копіювання конфігів Caddy
cp /etc/caddy/Caddyfile $BACKUP_DIR/Caddyfile

# Архівуємо всі резервні копії
tar -czvf $DESTINATION/k3s_backup_$(date +%Y%m%d%H%M%S).tar.gz -C $BACKUP_DIR .

# Очищаємо тимчасову директорію
rm -rf $BACKUP_DIR

echo "K3s backup finished at $(date)"

Зробіть скрипт виконуваним:

# Робимо скрипт виконуваним
sudo chmod +x /usr/local/bin/backup_k3s.sh

Додайте його в cron для щоденного виконання (наприклад, о 3:00 ночі):

# Відкриваємо crontab для редагування
sudo crontab -e

Додайте рядок:

# Щоденне резервне копіювання K3s о 03:00
0 3   * /usr/local/bin/backup_k3s.sh >> /var/log/k3s_backup.log 2>&1

Куди зберігати резервні копії

Ніколи не зберігайте резервні копії на тому ж сервері, який резервуєте. Розгляньте наступні варіанти:

• Зовнішнє S3-сумісне сховище: Дешеве та надійне рішення (наприклад, Backblaze B2, DigitalOcean Spaces). Використовуйте s3cmd або rclone для завантаження.
• Окремий VPS: Ви можете орендувати невеликий VPS лише для зберігання резервних копій та використовувати rsync з SSH-ключами для їх передачі.
• NFS-шара: Якщо у вас є мережеве сховище.

Оновлення: rolling vs maintenance window

Для K3s на одному вузлі концепція "rolling update" непридатна, оскільки немає інших вузлів, на які можна перенести навантаження. Оновлення K3s завжди означатиме простій кластера на короткий час.

• Оновлення K3s: Регулярно перевіряйте нові версії K3s (наприклад, кожні 3-6 місяців). Оновлення K3s здійснюється шляхом повторного запуску інсталяційного скрипта з новою версією або за допомогою утиліти k3s-upgrade.

  
  # Приклад оновлення K3s до нової версії
  curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION="v1.32.0+k3s1" sh -s - --disable traefik
  

  Це призведе до перезапуску K3s та короткочасного простою.

• Оновлення ОС та пакетів: Регулярно оновлюйте операційну систему: sudo apt update && sudo apt upgrade -y. Плануйте ці оновлення в період низького трафіку, оскільки вони можуть вимагати перезавантаження сервера.
• Оновлення додатків: Оновлюйте свої контейнерні образи та Helm-чарти. Kubernetes дозволяє робити це без простою, використовуючи rolling updates для Deployment'ів.

Завжди тестуйте оновлення на тестовому стенді, перш ніж застосовувати їх до продакшн-сервера.

Вирішення проблем + FAQ

У цьому розділі ми розглянемо типові проблеми, з якими можна зіткнутися при роботі з K3s, та дамо відповіді на часті запитання.

Не можу підключитися до кластера за допомогою kubectl

Що перевірити: Переконайтеся, що змінна оточення KUBECONFIG встановлена правильно (echo $KUBECONFIG має повернути /home/ваш_пользователь/.kube/config). Перевірте права на файл ~/.kube/config (мають бути 600). Переконайтеся, що K3s сервіс запущено (sudo systemctl status k3s) і файрвол (UFW) дозволяє порт 6443/tcp.

Як виправити: Перезапустіть K3s: sudo systemctl restart k3s. Перевірте логи K3s: sudo journalctl -u k3s --no-pager. Переконайтеся, що у файлі ~/.kube/config IP-адреса сервера вказана коректно.

Мій додаток недоступний через домен, Caddy видає помилку

Що перевірити: Перевірте DNS-запис для вашого домену (A-запис має вказувати на IP вашого VPS). Переконайтеся, що Caddy запущено (sudo systemctl status caddy) і його Caddyfile налаштовано правильно, вказуючи на localhost:30080. Перевірте логи Caddy (sudo journalctl -u caddy --no-pager) на предмет помилок з Let's Encrypt або проксіюванням. Переконайтеся, що Ingress-контролер запущено і його поди в статусі Running (kubectl get pods -n ingress-nginx).

Як виправити: Виправте DNS-записи. Перевірте синтаксис Caddyfile командою sudo caddy validate --config /etc/caddy/Caddyfile. Перезапустіть Caddy: sudo systemctl reload caddy. Переконайтеся, що ваш Ingress-ресурс у Kubernetes (kubectl get ingress) має правильний хост і посилається на існуючий сервіс та порт.

Поди додатків знаходяться в статусі Pending або CrashLoopBackOff

Що перевірити: Якщо под у статусі Pending, це часто означає нестачу ресурсів (CPU/RAM) або проблеми з Persistent Volume. Якщо CrashLoopBackOff, це означає, що додаток всередині контейнера постійно падає. Перевірте логи пода: kubectl logs <ім'я_пода> та опис пода: kubectl describe pod <ім'я_пода>.

Як виправити: Для Pending: збільште ресурси VPS або зменшіть запити ресурсів у маніфесті пода. Для CrashLoopBackOff: вивчіть логи додатка, можливо, проблема в його конфігурації, змінних оточення або відсутності необхідних залежностей.

Який VPS-конфіг мінімально підійде?

Для K3s без важких додатків достатньо 1 CPU ядра, 1 ГБ RAM та 20-30 ГБ SSD. Цього вистачить для запуску самого K3s та кількох дуже легких сервісів. Однак, якщо ви плануєте запускати реальні веб-додатки або бази даних, рекомендується мінімум 2 CPU ядра, 4 ГБ RAM та 50 ГБ SSD для комфортної роботи та можливості масштабування.

Що обрати — VPS чи dedicated для цього завдання?

Для розгортання K3s на одному вузлі для більшості особистих проектів, стартапів або тестових середовищ VPS є оптимальним вибором за співвідношенням ціна/продуктивність. Dedicated-сервери виправдані, коли потрібна максимальна продуктивність, гарантовані ресурси, дуже великий обсяг дискового простору або якщо ви плануєте запускати безліч ресурсоємних кластерів/додатків, де VPS вже не справляється з навантаженням або обмеженнями по CPU/RAM/IOPS.

K3s не запускається після перезавантаження сервера

Що перевірити: Переконайтеся, що сервіс K3s увімкнено для автозапуску: sudo systemctl is-enabled k3s. Якщо його не увімкнено, виконайте sudo systemctl enable k3s. Перевірте логи сервісу: sudo journalctl -u k3s --no-pager.

Як виправити: Якщо в логах є помилки, пов'язані з файрволом або мережею, переконайтеся, що UFW дозволяє всі необхідні порти, а мережеві інтерфейси підняті. Якщо це помилка бази даних, можливо, пошкоджено файл /var/lib/rancher/k3s/server/db/state.db. У такому випадку може знадобитися відновлення з резервної копії.

Як оновити K3s до нової версії?

Що перевірити: Перед оновленням обов'язково зробіть резервну копію кластера. Перевірте офіційну документацію K3s на предмет змін у новій версії, які можуть вплинути на ваші додатки або конфігурацію.

Як виправити: Оновлення K3s на одному вузлі виконується шляхом повторного запуску інсталяційного скрипта із зазначенням нової версії: curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION="vX.Y.Z+k3s1" sh -. Це автоматично завантажить нову версію, оновить бінарники та перезапустить K3s. Ваші додатки тимчасово будуть недоступні під час оновлення K3s.

Висновки та наступні кроки

Вітаємо! Ви успішно розгорнули легковажний Kubernetes кластер K3s на своєму VPS, налаштували Ingress-контролер з автоматичним HTTPS та опублікували перший додаток. Тепер у вас є потужна та гнучка платформа для хостингу ваших контейнеризованих додатків, керована декларативно та з мінімальними накладними витратами.

Куди рухатися далі?

1. Моніторинг та логування: Встановіть системи моніторингу, такі як Prometheus та Grafana, а також централізоване логування (наприклад, Loki або ELK стек) для відстеження стану кластера та додатків.
2. Керування секретами: Вивчіть інструменти для безпечного зберігання та керування секретами в Kubernetes (наприклад, HashiCorp Vault, Sealed Secrets) замість використання змінних оточення або файлів.
3. Масштабування та відмовостійкість: Якщо ваш проект зросте, розгляньте можливість додавання додаткових робочих нод K3s або міграцію на повноцінний багатоузловий Kubernetes кластер для підвищення відмовостійкості та продуктивності.