eccc1c2a01
- 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 уже существовали)
190 lines
4.9 KiB
Markdown
190 lines
4.9 KiB
Markdown
# Быстрый старт
|
||
|
||
Полный сценарий от чистой машины до работающего 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 molecule-all # ~15-20 минут
|
||
```
|
||
|
||
## Шаг 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
|
||
6. NFS server + CSI NFS Driver → StorageClass `nfs-master01`
|
||
7. ingress-nginx
|
||
|
||
Ожидаемое время: **15-25 минут**.
|
||
|
||
## Шаг 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 # конкретный аддон
|
||
```
|
||
|
||
Полный каталог аддонов — [addons.md](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
|
||
```
|