docs: полная документация проекта — docs/ и README.md для каждого аддона

- README.md: перепиcан как компактный обзор (98 строк) с навигацией по docs/
- docs/: 13 файлов — getting-started, architecture, configuration, addons,
  storage, security, cicd, observability, networking, operations,
  make-reference, molecule-testing, troubleshooting
- addons/*/README.md: 31 новый файл — описание, параметры, примеры кода
  для каждого из 34 аддонов (vault и external-secrets уже существовали)

docs/operations.md

@@ -0,0 +1,199 @@
+# Операции с кластером
+
+## Управление нодами
+
+### Добавить ноду
+
+1. Добавь ноду в `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
+
+[k3s_workers]
+worker04 ansible_host=192.168.1.14 ansible_user=ubuntu
+```
+
+2. Добавить:
+```bash
+make add-node NODE=worker04
+```
+
+Новые ноды подключаются через VIP (kube_vip_address). После добавления нода появляется в кластере автоматически.
+
+### Удалить ноду
+
+```bash
+make remove-node NODE=worker04
+```
+
+Порядок:
+1. `cordon` — запретить новые поды
+2. `drain` — вытеснить поды (таймаут 180 сек)
+3. `delete` — удалить из Kubernetes API
+4. Запуск K3S uninstall на удалённом хосте
+5. Очистка директорий K3S
+
+После удаления убери ноду из `inventory/hosts.ini`.
+
+**Ограничения:**
+- Нельзя удалить первый мастер (`groups['k3s_master'][0]`) — точка инициализации кластера
+- При удалении мастера etcd-кворум уменьшается: 3→2 нод — рекомендуется добавить замену
+
+---
+
+## etcd резервное копирование
+
+etcd хранит **всё состояние кластера**. Снимки хранятся на `{{ k3s_data_dir }}/server/db/snapshots`.
+
+### Создать снимок
+
+```bash
+make etcd-backup
+```
+
+Создаёт снимок `k3s-etcd-<timestamp>.db`, удаляет старые сверх `etcd_backup_retention` (умолч. 5).
+
+Копировать снимок на локальную машину:
+```yaml
+etcd_backup_copy_to_local: true
+etcd_backup_local_dir: "./etcd-backups"
+```
+
+### Список снимков
+
+```bash
+make etcd-list-snapshots
+```
+
+### Восстановление
+
+```bash
+make etcd-restore SNAPSHOT=k3s-etcd-20250101T120000.db
+
+# Без подтверждения:
+FORCE=true make etcd-restore SNAPSHOT=k3s-etcd-20250101T120000.db
+```
+
+Что происходит:
+1. K3S останавливается на **всех** нодах
+2. `k3s server --cluster-reset --cluster-reset-restore-path=<snapshot>` на первом мастере
+3. K3S запускается на первом мастере → ждёт API
+4. K3S запускается на остальных мастерах
+5. K3S-agent на воркерах
+
+### Параметры
+
+| Переменная | Умолч. | Описание |
+|---|---|---|
+| `etcd_backup_dir` | `{{ k3s_data_dir }}/server/db/snapshots` | Директория снимков |
+| `etcd_backup_retention` | `5` | Количество хранимых снимков |
+| `etcd_backup_copy_to_local` | `false` | Копировать на Ansible-хост |
+| `etcd_backup_local_dir` | `./etcd-backups` | Локальная директория |
+
+---
+
+## Обновление K3S
+
+```bash
+make upgrade VERSION=v1.30.0+k3s1
+```
+
+Обновление происходит по очереди (`serial: 1` в `upgrade.yml`):
+1. Drain ноды → вытеснить поды
+2. Обновить K3S бинарник
+3. Перезапустить сервис
+4. Дождаться `Ready`
+5. Uncordon → восстановить планирование
+6. Перейти к следующей ноде
+
+HA-режим гарантирует доступность кластера: пока одна нода обновляется, остальные обслуживают трафик.
+
+---
+
+## Диагностика
+
+```bash
+make health     # Статус сервисов, поды, диск, память
+make verify     # Nodes, pods, services, storageclass, ingress
+
+# Открыть shell в ansible-контейнере:
+make shell
+```
+
+Внутри контейнера:
+```bash
+ansible all -m shell -a "systemctl status k3s"
+ansible k3s_master -m shell -a "k3s kubectl get nodes -o wide"
+ansible k3s_master -m shell -a "k3s kubectl get pods -A | grep -v Running"
+ansible k3s_master -m shell -a "k3s etcd-snapshot ls"
+```
+
+Локально с kubectl:
+```bash
+export KUBECONFIG=$(pwd)/kubeconfig
+
+kubectl top nodes
+kubectl top pods -A
+kubectl get events -A --sort-by='.lastTimestamp' | tail -20
+kubectl get nodes -o wide
+kubectl get pods -A | grep -v Running
+```
+
+### Проверка etcd
+
+```bash
+kubectl -n kube-system exec -it \
+  $(kubectl -n kube-system get pods -l component=etcd -o name | head -1) \
+  -- etcdctl --endpoints=https://127.0.0.1:2379 \
+     --cacert=/var/lib/kubernetes/k3s/server/tls/etcd/server-ca.crt \
+     --cert=/var/lib/kubernetes/k3s/server/tls/etcd/server-client.crt \
+     --key=/var/lib/kubernetes/k3s/server/tls/etcd/server-client.key \
+     member list
+```
+
+---
+
+## Сброс и переустановка
+
+```bash
+# Удалить весь стек (с подтверждением)
+make uninstall
+
+# Переустановить базовый стек
+make install
+```
+
+---
+
+## Ротация сертификатов K3S
+
+Systemd-таймер автоматически проверяет срок истечения сертификатов:
+
+```yaml
+k3s_cert_auto_rotate: true
+k3s_cert_validity_years: 5
+k3s_cert_rotate_before_days: 90
+k3s_cert_check_schedule: "monthly"
+```
+
+Ручная ротация:
+```bash
+make shell
+ansible k3s_master -m shell -a "k3s certificate rotate"
+ansible k3s_master -m shell -a "systemctl restart k3s"
+```
+
+---
+
+## Ansible Vault операции
+
+```bash
+make vault-create     # Создать новый vault файл
+make vault-edit       # Редактировать зашифрованные секреты
+make vault-view       # Просмотреть содержимое
+
+# Зашифровать одну строку:
+make vault-encrypt-string STR="my-secret" NAME="vault_my_secret"
+```