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

Полный сценарий от чистой машины до работающего 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 — Подготовка серверов

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

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

## Шаг 2 — SSH ключи

```bash
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 — Клонировать и настроить проект

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

Отредактируй `.env`:
```
VAULT_PASSWORD=придумай-надёжный-пароль
```

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

Отредактируй `inventory/hosts.ini`:
```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`:
```yaml
kube_vip_address: "192.168.1.100"   # свободный IP, не в DHCP пуле
k3s_cni: "flannel"                  # flannel (умолч.) | calico | cilium
```

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

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

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

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

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

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

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

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

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

```bash
# Быстрый минимум перед первым деплоем:
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

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

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

```bash
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 — Проверить результат

```bash
make verify

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

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

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

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

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

---

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

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

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

```bash
make install ANSIBLE_TAGS=k3s
make install ANSIBLE_TAGS=kube_vip
make install ANSIBLE_TAGS=ingress
```