4eaf91e2d2
- Добавлен docs/custom-addons.md: структура addons/<name>, playbook, group_vars, playbooks/addons.yml, Makefile, Molecule, чеклист и см. также. - docs/addons.md, getting-started.md: отсылки на custom-addons.md. - README.md: строка в таблице документации. - docs/molecule-testing.md: уточнены molecule-prometheus/istio (тесты аддонов), разделы prometheus-stack/istio, ссылка на руководство в блоке про новые тесты. - docs/make-reference.md: примечание к make addon-<name>.
208 lines
5.9 KiB
Markdown
208 lines
5.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 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
|
||
```
|