K3s — лёгкий Kubernetes для разработки

K3s — компактная, «один бинарный файл» реализация Kubernetes, удобная для разработки, IoT и edge. Устанавливается скриптом, занимает меньше 50 МБ, поддерживает мульти‑нодовые кластеры, приватные реестры и простые обновления. В статье — пошаговые команды, примеры конфигураций, чек‑листы для разных ролей и рекомендации по безопасности и миграции.

Логотип K3s

Быстрые ссылки

Getting Started With K3s
Interacting With Your Cluster
An Example Workload
Setting Kubernetes Options
Multi-Node Clusters
Using Images In Private Registries
Upgrading Your Cluster
Uninstalling K3s
Conclusion

Введение

K3s — упрощённая и лёгкая дистрибуция Kubernetes, изначально созданная компанией Rancher и теперь входящая в Cloud Native Computing Foundation (CNCF). Программа распространяется как единый бинарный файл размером менее 50 МБ и включает необходимые компоненты для запуска готового к продакшену кластера. Главные преимущества — минимальные требования к ресурсам, простота обслуживания и высокая пригодность для edge/IoT и локальной разработки.

Простой образ мышления: K3s — это «Kubernetes в лаконичном корпусе», где управляющие компоненты и рабочие узлы могут запускаться одним бинарником, а системные сервисы регистрируются автоматически.

Важно: K3s сохраняет совместимость с API Kubernetes и большинством привычных рабочих нагрузок, но некоторые встроенные компоненты (например, Traefik) можно отключать при необходимости.

Начало работы с K3s

Запуск бинарного файла K3s на хосте создаёт локальный Kubernetes‑кластер. Основной процесс K3s запускает компоненты управления: API‑сервер, Kubelet и встроенный runtime containerd.

Официальный и рекомендованный способ быстрой установки — выполнить официальный скрипт установки. Скрипт загружает бинарник, помещает его в PATH и регистрирует системный сервис (systemd или openrc) для автоматического запуска и перезапуска после сбоя или перезагрузки хоста.

Чтобы установить K3s быстро, выполните:

$ curl -sfL https://get.k3s.io | sh -

Установка K3s: процесс в терминале

Проверьте статус сервиса после установки:

$ sudo service k3s status

Если в выводе отображается active (running) зелёным, кластер запущен и готов к использованию.

Совет: для автоматизации установки в инфраструктуре используйте переменные окружения или сохраните конфигурацию в /etc/rancher/k3s/config.yaml (пример ниже).

Работа с кластером

K3s поставляется со встроенной версией kubectl при установке через скрипт. Вызовы kubectl вложены в команду k3s:

$ k3s kubectl get pods

Если вы видите сообщение “No resources found in default namespace”, это нормально — в дефолтном неймспейсе ещё нет подов.

Возможная ошибка при первом запуске:

$ k3s kubectl get pods

WARN[0000] Unable to read /etc/rancher/k3s/k3s.yaml, please start server with –write-kubeconfig-mode to modify kube config permissions

error: error loading config file “/etc/rancher/k3s/k3s.yaml”: open /etc/rancher/k3s/k3s.yaml: permission denied

Это означает, что файл kubeconfig защищён правами, которые мешают обычному пользователю читать конфигурацию. Исправление:

$ sudo chmod 644 /etc/rancher/k3s/k3s.yaml

После этого kubectl можно запускать без sudo, если вы используете встроенный k3s kubectl или указываете переменную KUBECONFIG.

Если вы предпочитаете отдельный kubectl (например, установленный через пакетный менеджер), экспортируйте путь к kubeconfig вручную:

$ export KUBECONFIG=/etc/rancher/k3s/k3s.yaml

Затем можно вызывать обычный kubectl:

$ kubectl get pods

Совет по безопасности: ограничьте доступ к файлу /etc/rancher/k3s/k3s.yaml, особенно на машинах с несколькими пользователями.

Пример рабочей нагрузки

Проверьте кластер, развернув простой Deployment на базе nginx и создав сервис LoadBalancer.

Создание Deployment:

$ k3s kubectl create deployment nginx --image=nginx:latest

Откройте доступ через сервис:

$ k3s kubectl expose deployment nginx --type=LoadBalancer --port=80

Посмотреть сервисы:

$ k3s kubectl get services

Пример вывода (пояснение):

NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE

kubernetes ClusterIP 10.43.0.1 443/TCP 35m

nginx LoadBalancer 10.43.49.20 80:30968/TCP 17s

В этом примере IP сервиса в кластерной сети — 10.43.49.20. В локальной конфигурации LoadBalancer может быть помечен как до тех пор, пока не настроен внешний балансировщик. На single‑node кластере можно использовать NodePort для тестирования доступа извне.

Страница NGINX по умолчанию, запущенная в K3s

Краткая проверка: откройте в браузере адрес узла с NodePort (или используйте port‑forwarding), чтобы увидеть страницу приветствия NGINX.

Настройка опций Kubernetes в K3s

K3s позволяет передавать аргументы напрямую компонентам Kubernetes через флаги CLI. Аргументы можно указывать как флаги при запуске бинарника или в конфигурационном YAML файле /etc/rancher/k3s/config.yaml.

Распространённые флаги:

–etcd-arg — проброс аргумента в Etcd.
–kube-apiserver-arg — проброс аргумента в kube‑apiserver.
–kube-controller-manager-arg — аргумент для kube‑controller‑manager.
–kubelet-arg — аргумент для kubelet.

Пример отключения встроенного Traefik (если вы хотите заменить Ingress):

--disable traefik

Рекомендация: для устойчивости и читаемости используйте config.yaml вместо длинной строки флагов. В config.yaml названия полей соответствуют именам флагов без префикса “–“.

Пример минимальной конфигурации /etc/rancher/k3s/config.yaml:

# Именование узла
node-name: first-worker

# Привязка к конкретному адресу хоста (опционально)
bind-address: 1.2.3.4

# Отключение встроенных компонентов
disable:
  - traefik

# Дополнительные аргументы для компонентов
kube-apiserver-arg:
  - "feature-gates=SomeFeature=true"
kubelet-arg:
  - "eviction-hard=memory.available<100Mi"

Примечание: YAML чувствителен к отступам. Помещая файл в /etc/rancher/k3s/config.yaml, вы добиваетесь одинаковой конфигурации при каждом старте K3s.

Мульти‑нодовые кластеры

K3s поддерживает полноценные мульти‑нодовые кластеры. Чтобы добавить воркер‑узел, используйте переменные окружения K3S_URL и K3S_TOKEN при запуске установщика.

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

$ curl -sfL https://get.k3s.io | K3S_URL=https://192.168.0.1:6443 K3S_TOKEN=token sh -

Где:

K3S_URL — URL и порт K3s сервера (обычно https://:6443).
K3S_TOKEN — секретный токен кластера. Токен можно получить на сервере из файла /var/lib/rancher/k3s/server/node-token.

Процесс установки настроит узел как worker и автоматически подключит его к серверу.

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

Обновляйте сервер (control plane) первым, затем по очереди воркеры.
Проверяйте совместимость версий Kubernetes и используемых CSI/Ingress плагинов.
Настраивайте резервные хранилища и backups ключевых манифестов.

Использование образов из приватных реестров

K3s умеет автоматически подхватывать креденшалы для приватных реестров через файл /etc/rancher/k3s/registries.yaml, который кластер читает при старте.

Пример конфигурации с зеркалом и endpoint:

mirrors:
  example-registry.com:
    endpoint:
      - "https://example-registry.com:5000"

Это позволит подтягивать образы вида example-registry.com/example-image:latest с сервера на порту 5000. В endpoint можно указать несколько URL как fallback.

Добавление учётных данных (auth):

mirrors:
  example-registry.com:
    endpoint:
      - "https://example-registry.com:5000"
    configs:
      "example-registry.com:5000":
        auth:
          username: myuser
          password: mypassword

Если у реестра несколько endpoints, для каждого endpoint нужно добавить соответствующую запись в configs.

TLS для приватных реестров:

configs:
  "example-registry.com:5000":
    auth:
      username: myuser
      password: mypassword
    tls:
      cert_file: /tls/cert
      key_file: /tls/key
      ca_file: /tls/ca

Укажите корректные пути к сертификатам. K3s при старте распространяет эти настройки на воркеры автоматически.

Важно: держите пароли и сертификаты в защищённом хранилище и ограничивайте доступ к файлам на хостах.

Обновление кластера

Обновление K3s выполняется тем же скриптом установки — он обнаружит существующую установку и произведёт миграцию на новую версию.

Простой командный пример обновления:

$ curl -sfL https://get.k3s.io | sh -

Если вы устанавливали K3s с кастомными переменными окружения, повторите их при обновлении:

$ curl -sfL https://get.k3s.io | INSTALL_K3S_BIN_DIR=/usr/bin sh -

Чтобы установить конкретную версию Kubernetes/K3s, задайте INSTALL_K3S_VERSION:

$ curl -sFL https://get.k3s.io | INSTALL_K3S_VERSION=v1.23.0 sh -

Для тестирования предрелизов можно использовать канал:

$ curl -sFL https://get.k3s.io | INSTALL_K3S_CHANNEL=latest sh -

Рекомендации:

Обновляйте сервер прежде, чем воркеры.
Проверяйте changelog и совместимость плагинов.
Тестируйте обновления в staging окружении перед продакшеном.

Удаление K3s

Для полного удаления K3s используйте встроенный скрипт удаления, который удаляет сервисы, бинарник и данные кластера:

$ /usr/local/bin/k3s-uninstall.sh

Для удаления агент‑воркера выполните скрипт:

$ /usr/local/bin/k3s-agent-uninstall.sh

После удаления проверьте, что ключевые каталоги и файлы очищены (/var/lib/rancher/k3s, /etc/rancher/k3s), особенно если вы планируете повторную установку или перенос данных.

Когда K3s — хорошее решение и когда нет

Плюсы K3s:

Низкие требования к ресурсам — подходит для edge/IoT и локальной разработки.
Быстрая установка и простая конфигурация.
Поддержка мульти‑нодовых кластеров, приватных реестров и обновлений.
Совместимость с большинством Kubernetes API объектов.

Ограничения и случаи, когда K3s может не подойти:

Если вы требуете строго управляемого control plane с распределённым etcd и сложными SLA, лучше рассмотреть классический upstream Kubernetes с HA‑конфигурацией и отдельным etcd.
Если в инфраструктуре уже настроен корпоративный кластер с особенными требованиями безопасности/аудита, миграция на K3s потребует дополнительных проверок.
При необходимости узкоспециализированных плагинов и CRD, которые зависят от специфических версий Kubernetes, возможно, придётся свериться с совместимостью.

Альтернативные подходы

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

Minikube — хорош для локальной разработки с возможностью выбора драйверов виртуализации.
MicroK8s — лёгкий, снабжён snap‑пакетом и хорош для Ubuntu‑среды.
kind — запускает Kubernetes в Docker контейнерах, удобно для CI‑тестов.

Выбор зависит от рабочих сценариев: K3s хорош для минимальных систем и edge, Minikube и MicroK8s удобны для отдельной машины разработчика, kind — для CI и тестов.

Практические модели мышления и эвристики

«Один бинарник» — K3s упрощает администрирование: один процесс управляет компонентами.
«Server first, workers later» — при обновлениях и масштабировании сначала обновляйте управляющие узлы.
«Config-as‑file» — предпочитайте /etc/rancher/k3s/config.yaml вместо длинных флагов.
«Least privilege for kubeconfig» — храните /etc/rancher/k3s/k3s.yaml с минимально необходимыми правами.

Чек‑листы по ролям

Чек‑лист для разработчика:

Установить K3s локально через скрипт.
Экспортировать KUBECONFIG для удобства.
Развернуть тестовый nginx и проверить доступ.
Использовать port‑forward или NodePort для локального тестирования.

Чек‑лист для оператора/администратора:

Поместить конфигурацию в /etc/rancher/k3s/config.yaml.
Настроить registries.yaml при использовании приватных реестров.
Реализовать резервное копирование данных (etcd или другой механизм хранения).
Планировать обновления: сначала сервер, затем воркеры.

Чек‑лист для edge‑оператора:

Проверить требования к ресурсам устройства (CPU, RAM, диск).
Настроить автоматический restart systemd service для k3s.
Обеспечить безопасную доставку токенов и сертификатов на устройства.
Развернуть lightweight monitoring (логирование и метрики).

Плейбук: быстрый развёртывание приложения

Установить K3s на сервер: curl -sfL https://get.k3s.io | sh -
Проверить статус: sudo service k3s status
Создать deployment: k3s kubectl create deployment myapp –image=myimage:latest
Открыть сервис: k3s kubectl expose deployment myapp –type=NodePort –port=8080
Проверить pod и service: k3s kubectl get pods,svc
Настроить мониторинг и логи (Prometheus/Fluentd/или лёгкий стек)

Инцидентный план: восстановление после падения узла

Проверить статус сервиса: sudo service k3s status.
Проверить логи: sudo journalctl -u k3s -n 200.
Если процесс упал — попытаться рестартовать: sudo systemctl restart k3s.
Если проблема с данными — восстановить из резервной копии etcd/бэкапа.
При повреждении токена или сертификатов — пересоздать и пересинхронизировать воркеры.
Если узел недоступен физически — удалить node из кластера и пересоздать его как новый воркер.

Безопасность и жёсткое укрепление

Ограничьте доступ к kubeconfig и каталогу /var/lib/rancher/k3s.
Используйте TLS для приватных реестров и проверку сертификатов.
Минимизируйте список включённых компонентов (отключайте ненужные через disable).
Внедрите сетевые политики для сегментации трафика между pod‑ами.
Регулярно обновляйте версии K3s и сторонних плагинов.

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

Перед миграцией проверьте версии API и CRD, используемые приложениями.
Планируйте тестовую миграцию в staging среде.
Для миграции между провайдерами выполните бэкап данных и манифестов, восстановление на новой платформе и проверку состояния.

Риски и способы снижения

Потеря данных при некорректном удалении — делайте бэкапы.
Несовместимость плагинов — тестируйте на staging.
Утечка креденшалов — храните секреты централизованно, ограничьте права доступа.

Заключение

K3s предлагает простой, компактный и производительный путь к использованию Kubernetes в условиях ограниченных ресурсов и на локальных машинах разработчиков. Он не заменяет полноценные HA‑кластеры во всех сценариях, но отлично подходит для edge, IoT, тестирования и локальной разработки, где важны скорость установки и простота эксплуатации.

Краткие рекомендации:

Используйте официальный скрипт для быстрого старта.
Храните конфигурацию в config.yaml для повторяемости установок.
Настройте registries.yaml для приватных реестров.
Тестируйте обновления и поддерживайте бэкапы.

Важно

Перед внедрением в продакшен прогоните полный тестовый цикл, включая сценарии восстановления и нагрузки. K3s даёт гибкие инструменты, но ответственность за архитектуру и SLA остаётся за командой, которая внедряет кластер.

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

K3s сервис запущен и активен на всех узлах.
kubeconfig доступен нужным пользователям с минимально необходимыми правами.
Рабочая нагрузка успешно развёрнута и доступна извне (через NodePort/LoadBalancer/Ingress).
Настроено резервное копирование и мониторинг ключевых компонентов.

Ресурсы для дальнейшего чтения