K3S/docs/getting-started.md

Быстрый старт

Полный сценарий от чистой машины до работающего K3S кластера с аддонами.

Требования

На твоей машине

Инструмент	Версия	Установка
Docker	>= 24.0	https://docs.docker.com/get-docker/
make	любая	apt install make / brew install make
SSH ключ	—	ssh-keygen -t ed25519

Ansible, Helm, kubectl, Molecule — устанавливать не нужно. Всё работает внутри Docker-контейнера.

На серверах кластера

Требование	Описание
ОС	Ubuntu 20.04/22.04/24.04, Debian 11/12, Raspberry Pi OS 64-bit
SSH	Доступ с твоего публичного ключа
sudo	Без пароля (NOPASSWD) — рекомендуется
Интернет	Для скачивания K3S, образов, Helm чартов
RAM	master01/worker01: 2+ ГБ; rpi01: 1+ ГБ

---

Шаг 1 — Подготовка серверов

Выполни на каждом сервере:

echo "$USER ALL=(ALL) NOPASSWD:ALL" | sudo tee /etc/sudoers.d/$USER

Шаг 2 — SSH ключи

ssh-keygen -t ed25519 -C "k3s-ansible" -f ~/.ssh/id_ed25519

ssh-copy-id ubuntu@192.168.1.10   # master01
ssh-copy-id ubuntu@192.168.1.11   # worker01
ssh-copy-id pi@192.168.1.12       # rpi01

ssh ubuntu@192.168.1.10 "hostname"  # проверка

Шаг 3 — Клонировать и настроить проект

git clone <url> k3s-ansible && cd k3s-ansible
make setup   # создать .env из шаблона

Отредактируй .env:

VAULT_PASSWORD=придумай-надёжный-пароль

Шаг 4 — Инвентарь

Отредактируй inventory/hosts.ini:

[k3s_master]
master01 ansible_host=192.168.1.10 ansible_user=ubuntu
worker01 ansible_host=192.168.1.11 ansible_user=ubuntu
rpi01    ansible_host=192.168.1.12 ansible_user=pi ansible_python_interpreter=/usr/bin/python3

[k3s_cluster:children]
k3s_master

[k3s_cluster:vars]
ansible_ssh_private_key_file=~/.ssh/id_ed25519

[nfs_server]
master01

Шаг 5 — Переменные кластера

Отредактируй group_vars/all/main.yml:

kube_vip_address: "192.168.1.100"   # свободный IP, не в DHCP пуле
k3s_cni: "flannel"                  # flannel (умолч.) | calico | cilium

kube_vip_interface определяется автоматически через ansible_default_ipv4.interface.

Шаг 6 — Vault с секретами

openssl rand -hex 32   # сгенерировать токен K3S
make vault-create

В редакторе введи:

vault_k3s_token: "сгенерированный-токен"

# Если планируешь Prometheus:
vault_grafana_user: "admin"
vault_grafana_password: "мой-пароль"

Полный шаблон секретов — group_vars/all/vault.yml.example.

Шаг 7 — Собрать Docker образ

make build   # ~3-5 минут

Шаг 8 — Прогнать тесты (рекомендуется)

# Быстрый минимум перед первым деплоем:
make lint
make molecule-k3s
make molecule-cluster

# Полный набор (дольше):
make molecule-addon-all

Рекомендуемый порядок:

1. make lint — проверка синтаксиса плейбуков.
2. make molecule-k3s — роль k3s.
3. make molecule-cluster — топология 3 master + 2 worker.
4. make molecule-addon-all — аддоны (останавливается на первой ошибке).

Шаг 9 — Проверить SSH и dry-run

make ping    # доступность всех нод
make check   # dry-run без изменений

Шаг 10 — Развернуть базовый стек

make install

Что происходит (serial: 1):

1. master01: prereqs → K3S server (cluster-init) → ждёт API
2. worker01: K3S server (join)
3. rpi01: K3S server (join) + taint NoSchedule
4. CNI (если не Flannel)
5. kube-vip: VIP + LoadBalancer

Ожидаемое время: 10-20 минут.

Важно

make install разворачивает только core-компоненты кластера.
Аддоны (nfs-server, csi-nfs, ingress-nginx, cert-manager, prometheus-stack и т.д.) ставятся отдельным шагом.

Шаг 11 — Проверить результат

make verify

export KUBECONFIG=$(pwd)/kubeconfig
kubectl get nodes -o wide
kubectl get svc -n ingress-nginx
kubectl get storageclass

Шаг 12 — Установить аддоны

# group_vars/all/addons.yml — включи нужные:
addon_prometheus_stack: true
addon_cert_manager: true
addon_argocd: true
addon_gitea: true

make install-addons          # все включённые аддоны
make addon-prometheus-stack  # конкретный аддон
make addon-ingress-nginx
make addon-cert-manager
make addon-nfs               # nfs-server + csi-nfs

Полный каталог аддонов — addons.md. Как добавить собственный аддон (каталог, плейбук, интеграция в make и Molecule) — custom-addons.md.

---

Рабочий процесс при изменениях

make molecule-k3s    # тест нужной роли
make molecule-lint   # линтинг
make check           # dry-run
make install         # деплой

Тегированный деплой

make install ANSIBLE_TAGS=k3s
make install ANSIBLE_TAGS=kube_vip
make install ANSIBLE_TAGS=ingress