K3s — лёгкий Kubernetes: установка, настройка и эксплуатация

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

• 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, идеально подходящая для разработки и окружений с ограниченными ресурсами. Проект вошёл в состав Cloud Native Computing Foundation (CNCF), изначально был разработан Rancher.

K3s поставляется единым бинарником размером менее 50 МБ. Несмотря на компактность, K3s включает всё необходимое для запуска готового к продакшену Kubernetes-кластера. Проект ориентирован на устройства с ограничёнными ресурсами, где важны стабильность и простота обслуживания. Сегодня K3s часто разворачивают на периферии (edge) и на IoT‑устройствах, но он также удобен для локальной разработки.

Getting Started With K3s

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

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

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

Подтвердите успешную установку, проверив статус службы k3s:

$ sudo service k3s status

Если вы видите active (running) зеленым — кластер готов к использованию.

Важно: скрипт установки делает изменения в системе — проверяйте скрипт перед запуском в открытых окружениях.

Interacting With Your Cluster

Если вы установили K3s через официальный скрипт, в комплект входит kubectl, доступный через команду k3s kubectl.

$ k3s kubectl get pods

Вы можете получить ошибку, связанную с правами доступа к kubeconfig:

$ 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

Исправьте права на файл, чтобы запускать kubectl без sudo:

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

После этого команды kubectl можно запускать от обычного пользователя.

Альтернатива: используйте свою установку kubectl и указывайте конфиг K3s через переменную окружения или флаг --kubeconfig:

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

$ kubectl get pods

No resources found in default namespace.

Совет по удобству: добавьте экспорт KUBECONFIG в профиль пользователя (~/.bashrc или ~/.profile) для постоянного доступа.

An Example Workload

Проверку кластера можно выполнить, создав простой деплоймент NGINX:

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

deployment.apps/nginx created

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

service/nginx exposed

Узнайте IP созданного сервиса:

$ 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

В примере сервис NGINX доступен по IP 10.43.49.20. Откройте этот адрес в браузере, чтобы увидеть стандартную страницу NGINX.

Краткая полезная проверка статуса подов и сервиса:

$ k3s kubectl get pods -o wide
$ k3s kubectl describe svc nginx

Критерии приёмки: NGINX pod в статусе Running; сервис имеет назначенный ClusterIP; при типе LoadBalancer — внешний IP может быть в локальной среде без LB.

Setting Kubernetes Options

K3s позволяет передавать аргументы отдельным компонентам Kubernetes через флаги командной строки при запуске бинарника. Также поддерживаются переменные окружения, но соответствие между флагом и именем переменной не всегда тривиально.

Наиболее часто используемые флаги:

• --etcd-arg — передать аргумент в Etcd.
• --kube-apiserver-arg — аргумент для kube-apiserver.
• --kube-controller-manager-arg — аргумент для controller-manager.
• --kubelet-arg — аргумент для kubelet.

Многие другие опции позволяют отключать встроенные компоненты, например Traefik: --disable traefik.

Для удобства управления настройками лучше использовать YAML‑конфиг: положите его в /etc/rancher/k3s/config.yaml. Имена полей соответствуют CLI‑аргументам без префикса --.

Пример минимального конфига (оригинальный минимал):

node-name: first-worker

bind-address: 1.2.3.4

Ниже — улучшенный и корректно отформатированный пример config.yaml, который можно поместить в /etc/rancher/k3s/config.yaml:

# Пример /etc/rancher/k3s/config.yaml
node-name: first-worker
bind-address: 1.2.3.4
kube-apiserver-arg:
  - "feature-gates=SomeFeature=true"
kubelet-arg:
  - "eviction-hard=imagefs.available<15%"
disable:
  - traefik

Важно: после изменения конфига перезапустите службу K3s: sudo systemctl restart k3s.

Multi-Node Clusters

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

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

Этот скрипт установит K3s и настроит его как worker, который подключится к серверу по адресу 192.168.0.1. Токен кластера можно получить на сервере:

$ cat /var/lib/rancher/k3s/server/node-token

Советы по масштабированию и отказоустойчивости:

• Для HA используйте несколько серверных нод и общий datastore (например, внешний etcd или встроенный с кластеризацией).
• Обновляйте серверную ноду первой, затем последовательно worker‑ноды.
• Следите за метриками ресурсов (CPU, память, диск) — K3s хорошо работает в ограниченных ресурсах, но ограничения всё же есть.

Using Images In Private Registries

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

mirrors:

example-registry.com:

endpoint:

• “https://example-registry.com:5000”

Эти строки в исходном тексте были разбиты — ниже приведён правильно оформленный пример registries.yaml.

Правильный вариант файла для зеркала и авторизации:

mirrors:
  example-registry.com:
    endpoint:
      - "https://example-registry.com:5000"
configs:
  "example-registry.com:5000":
    auth:
      username: ""
      password: ""
    tls:
      cert_file: /etc/k3s/certs/registry-cert.pem
      key_file: /etc/k3s/certs/registry-key.pem
      ca_file: /etc/k3s/certs/ca.pem

Пояснения:

• mirrors — список зеркал, по которым будут запрашиваться образы.
• configs — словарь конфигураций по конкретным endpoint; требуется для указания логина/пароля и TLS.
• Поля cert_file, key_file, ca_file указывают на файлы сертификатов, доступные на сервере K3s.

После внесения файла перезапустите K3s, чтобы учётные данные были распространены на воркеры.

Замечание: если ваш реестр использует стандартный порт 443 и корректный TLS — часто достаточно указать только auth.

Upgrading Your Cluster

Для обновления K3s используйте тот же официальный скрипт установки — он обнаружит существующую установку и выполнит миграцию:

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

Если при установке вы использовали специфичные переменные окружения, повторите их при обновлении:

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

Процесс для мульти‑нодовых кластеров:

1. Обновите серверную ноду(ы) первой(ых).
2. Обновите worker ноды по одной и дождитесь стабилизации.

Можно установить конкретную версию или канал релизов:

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

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

По умолчанию K3s будет устанавливать последнюю стабильную версию Kubernetes, если переменные не заданы.

Резервирование перед обновлением: всегда делайте резервную копию важных данных (persistent volumes, manifests, конфиги) и тестируйте обновления в staging.

Uninstalling K3s

Утилита установки включает скрипт для удаления, который удалит сервисы, бинарник и данные кластера:

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

Для удаления worker‑узла используйте специальный скрипт:

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

Важно: скрипт удаляет все данные кластера по умолчанию. Если вам нужно сохранить часть данных — сделайте резервную копию заранее.

Security hardening — базовые рекомендации

• Запустите K3s с минимально необходимыми правами и используйте SELinux/AppArmor по возможности.
• Ограничьте доступ к /etc/rancher/k3s/k3s.yaml и к ключам TLS: права 600/640 и только для администраторов.
• Используйте RBAC и ограничивайте привилегии ServiceAccount через Pod Security Policies или PodSecurityAdmission.
• Храните учётные данные реестров в registries.yaml и защищайте доступ к файлам сертификатов.
• Для production используйте зашифрованный datastore или внешний etcd с TLS.

Когда K3s не подходит — контрпримеры

• Если вам нужна максимально «чистая» upstream‑инсталляция Kubernetes с нулевой модификацией, K3s может вносить собственные упрощения.
• В окружениях с высокими требованиями к производительности сетевого стека или с поддержкой специфичных CNI‑плагинов K3s встроенные решения могут не подойти.
• Для крупных корпоративных кластеров с сотнями нод и сложными политиками управления чаще используют полнофункциональные дистрибуции Kubernetes и специализированные инструменты для управления.

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

• Minikube — локальный Kubernetes с акцентом на разработку в VM.
• MicroK8s — компактный Kubernetes от Canonical с snap‑пакетом и модульной архитектурой.
• Полноразмерные решения (kubeadm, managed Kubernetes в облаке) — для продакшен‑кластера с высоким SLA.

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

1. Проверить статус службы: sudo service k3s status.
2. Посмотреть логи K3s: sudo journalctl -u k3s -b.
3. Проверить состояние подов: k3s kubectl get pods --all-namespaces -o wide.
4. Описать проблемный pod: k3s kubectl describe pod -n .
5. Посмотреть логи контейнера: k3s kubectl logs -c .
6. Проверить диск и inode: df -h, df -i — проблемы с хранением часто вызывают падения.

Мини‑чеклист при диагностике:

• Есть ли сетевой доступ между нодами?
• Доступен ли datastore (etcd) и нет ли разрывов?
• Правильные ли права на k3s.yaml и сертификаты?

Ролевые чеклисты

Для разработчика:

• Экспортировать KUBECONFIG для локального kubectl.
• Запустить тестовый deployment и service.
• Использовать локальные manifests в отдельном namespace.

Для SRE/оператора:

• Конфигурировать /etc/rancher/k3s/config.yaml и управлять флагами.
• Настроить резервное копирование и мониторинг.
• Проводить обновления по плану и по нодам.

Для администратора сети/безопасности:

• Проверить TLS в кластере и между нодами.
• Настроить RBAC и ограничения доступа.
• Обеспечить безопасное хранение токенов и секретов.

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

• Кластер стартует, служба K3s активна.
• kube-apiserver отвечает на запросы (kubectl get nodes).
• Под примерного приложения запускаются и остаются в статусе Running.
• Конфигурационные файлы и секреты защищены правами доступа.

Тесты и контроль качества (примерные сценарии)

• Smoke test: создание деплоймента NGINX и проверка ответа HTTP.
• Persistence test: создание PVC и проверка записи/чтения данных.
• Scaling test: увеличение replicas и проверка распределения по нодам.
• Upgrade test: обновление сервера на staging и проверка непрерывности сервисов.

Decision flow: когда выбирать K3s

Mermaid диаграмма для быстрой оценки (при необходимости скопируйте в поддерживающий редактор):

flowchart TD
  A[Нужен легкий Kubernetes?] -->|Да| B{Запуск на edge/IoT/локально}
  B -->|Да| C[K3s]
  B -->|Нет| D[Оценить Minikube / MicroK8s / managed Cloud]
  A -->|Нет| D

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

• K3s поддерживает стандартные объекты Kubernetes; при миграции проверяйте версии API (deprecated API могут быть удалены между версиями).
• Для переноса данных persistent volumes используйте инструменты резервного копирования/восстановления или миграцию на уровне storage.
• Тестируйте манифесты в staging, так как некоторые системные компоненты K3s могут отличаться от full‑stack Kubernetes.

Примеры конфигов и сниппеты (cheat sheet)

Быстрый запуск worker‑ноды:

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

Установка определённой версии:

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

Резервное копирование manifests:

$ k3s kubectl get all --all-namespaces -o yaml > cluster-manifests.yaml

Заключение

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

K3s предоставляет гибкие способы настройки: флаги CLI, YAML‑конфиг, поддержка приватных реестров и простые механизмы для масштабирования на несколько нод. Тем не менее перед выбором K3s оцените требования к безопасности, масштабируемости и необходимым CNI/CSI‑функциям — в некоторых случаях полнофункциональные дистрибуции дадут больше контроля.

Важно: всегда тестируйте процедуры обновления и резервного копирования в изолированной среде до применения в продакшене.

Короткое резюме — когда использовать K3s:

• Быстрая локальная разработка без виртуальных машин.
• Edge‑устройства и IoT с ограниченными ресурсами.
• Простая production‑среда с умеренными требованиями к масштабу.

Если вам нужно краткое объявление для команды или соцсетей, используйте следующий текст:

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