626 lines
37 KiB
Markdown
626 lines
37 KiB
Markdown
# Kubernetes Infrastructure
|
||
|
||
> **Корпоративный стандарт.** Ansible-развёртывание кластера Kubernetes на Rocky Linux 9.
|
||
> Локальный запуск через CLI и автоматизированный запуск через GitLab CI/CD.
|
||
|
||
---
|
||
|
||
## Содержание
|
||
|
||
- [Инфраструктура](#инфраструктура)
|
||
- [Стек технологий](#стек-технологий)
|
||
- [Структура репозитория](#структура-репозитория)
|
||
- [Роли и компоненты](#роли-и-компоненты)
|
||
- - **Стандарт работы с хранилищем** [`roles/longhorn/README.md`](roles/longhorn/README.md)
|
||
- - **Стандарт публикации сервисов** [`roles/traefik/README.md`](roles/traefik/README.md)
|
||
- - **Стандарт GitOps-деплоя приложений** [`roles/flux/README.md`](roles/flux/README.md)
|
||
- - **Стандарт объектного хранилища S3** [`roles/minio/README.md`](roles/minio/README.md)
|
||
- - **Стандарт централизованного сбора логов** [`roles/logging/README.md`](roles/logging/README.md)
|
||
- - Sealed Secrets (kubeseal)
|
||
- [CI/CD-пайплайн](#cicd-пайплайн)
|
||
- [Порядок развёртывания](#порядок-развёртывания)
|
||
- [Архитектурные решения](#архитектурные-решения)
|
||
- [Локальная разработка](#локальная-разработка)
|
||
- [Добавление нового компонента](#добавление-нового-компонента)
|
||
|
||
---
|
||
|
||
## Инфраструктура
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ Operator workstation (manager_nodes) │
|
||
│ k8s-manager-01 10.203.0.92 │
|
||
│ kubectl · helm · k9s · kubectx/kubens │
|
||
│ Kubernetes Dashboard token → ~/.kube/dashboard-token │
|
||
└────────────────────────┬────────────────────────────────────────┘
|
||
│ kubectl / helm (kubeconfig)
|
||
┌────────────────────────▼────────────────────────────────────────┐
|
||
│ Kubernetes cluster (k8s_cluster) │
|
||
│ │
|
||
│ ┌──────────────────────────────────────────────────────────┐ │
|
||
│ │ Control plane k8s-master-01 10.203.0.97 │ │
|
||
│ │ kube-apiserver · etcd · controller-manager · scheduler │ │
|
||
│ └──────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌──────────────────────────────────────────────────────────┐ │
|
||
│ │ Worker k8s-worker-01 10.203.0.96 │ │
|
||
│ │ kubelet · kube-proxy · Longhorn disk agent │ │
|
||
│ │ Traefik DaemonSet │ │
|
||
│ │ :10001 → kubernetes-dashboard (ClusterIP :443) │ │
|
||
│ │ :10002 → longhorn-frontend (ClusterIP :80) [auth] │ │
|
||
│ │ :10003 → grafana (ClusterIP :80) │ │
|
||
│ │ :10005 → minio (ClusterIP :9000) │ │
|
||
│ │ :10006 → minio-console (ClusterIP :9001) │ │
|
||
│ │ :10103 → db/bgbilling-dev (TCP :3306) │ │
|
||
│ └──────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ CNI: Flannel v0.26.1 │ Storage: Longhorn 1.7.2 │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### Узлы кластера
|
||
|
||
| Hostname | IP | Группа инвентаря | Роль |
|
||
|---|---|---|---|
|
||
| k8s-manager-01 | 10.203.0.92 | `manager_nodes` | Рабочая станция оператора |
|
||
| k8s-master-01 | 10.203.0.97 | `control_plane` | API server, etcd, scheduler |
|
||
| k8s-worker-01 | 10.203.0.96 | `workers` | Вычислительный узел |
|
||
| k8s-worker-02 | 10.203.0.212 | `workers` → `gpu_workers` | GPU-узел (NVIDIA), Ollama-стек |
|
||
| k8s-worker-NN | TBD | `workers` | Дополнительные вычислительные узлы |
|
||
|
||
> `manager_nodes` — **не** Kubernetes-узел. Это рабочая станция оператора, с которой запускаются `kubectl` и `helm`.
|
||
|
||
### Сервисы и точки доступа
|
||
|
||
| Сервис | URL | Аутентификация |
|
||
|---|---|---|
|
||
| Kubernetes Dashboard | `http://10.203.0.96:10001` | токен из `~/.kube/dashboard-token` |
|
||
| Longhorn UI | `http://10.203.0.96:10002` | BasicAuth (Secret `traefik-auth-longhorn` в ns `traefik`) |
|
||
| Grafana | `http://10.203.0.96:10003` | логин Grafana (admin, пароль из Secret `grafana-admin-secret`) |
|
||
| MinIO S3 API | `http://10.203.0.96:10005` | AWS Signature v4 (встроенная аутентификация MinIO) |
|
||
| MinIO Console | `http://10.203.0.96:10006` | логин MinIO (rootUser из Secret `minio-root-credentials`) |
|
||
| MariaDB BGBilling | `10.203.0.96:10103` | TCP-проброс (без HTTP); аутентификация средствами MariaDB |
|
||
| Ollama Proxy (k8s_ai) | `http://10.203.0.96:10200` | своя аутентификация приложения |
|
||
| Open WebUI (k8s_ai) | `http://10.203.0.96:10201` | своя аутентификация приложения |
|
||
|
||
---
|
||
|
||
## Стек технологий
|
||
|
||
| Компонент | Версия | Управляется |
|
||
|---|---|---|
|
||
| ОС | Rocky Linux 9 | Ansible |
|
||
| Kubernetes | 1.33 (pkgs.k8s.io) | Ansible → `k8s_control_plane`, `k8s_worker` |
|
||
| Container runtime | containerd (Docker CE repo) | Ansible |
|
||
| CNI | Flannel v0.26.1 / Calico v3.27.0 | Ansible → `k8s_control_plane` |
|
||
| Постоянное хранилище | Longhorn 1.7.2 | Ansible → `longhorn_prereqs`, `longhorn` |
|
||
| Ingress / proxy | Traefik 32.1.0 | Ansible → `traefik` |
|
||
| Kubernetes Dashboard | v2.7.0 | Ansible → `k8s_manager` |
|
||
| Объектное хранилище | MinIO 5.4.0 (chart) | Ansible → `minio` |
|
||
| Централизованные логи | Loki 7.0.0 + Grafana Alloy 1.8.2 + Grafana 10.5.15 | Ansible → `logging` |
|
||
| Шифрование Secret'ов | Sealed Secrets 2.16.1 | Ansible → `sealed_secrets` |
|
||
| GitOps | Flux CD (latest stable) | Ansible → `flux` |
|
||
| GitLab Agent | agentk (latest stable) | Ansible → `gitlab_agent` |
|
||
| Автоматизация | Ansible (посм. requirements.yml) | — |
|
||
| CI/CD | GitLab CI/CD | `.gitlab-ci.yml` |
|
||
|
||
---
|
||
|
||
## Структура репозитория
|
||
|
||
```
|
||
.gitlab-ci.yml — CI/CD-пайплайн (стадии validate → setup)
|
||
ansible.cfg — кэширование фактов, pipelining, YAML-вывод
|
||
requirements.yml — коллекции Ansible Galaxy
|
||
|
||
inventory/prod/
|
||
hosts.yml — статический список хостов (3 группы)
|
||
group_vars/
|
||
all.yml — SSH-учётные данные из переменных окружения
|
||
k8s_cluster.yml — общие переменные для control_plane + workers
|
||
control_plane.yml — k8s_version, CIDR, CNI
|
||
workers.yml — конфигурация дисков Longhorn
|
||
manager_nodes.yml — версии инструментов, часовой пояс
|
||
traefik.yml — traefik_port_map: таблица портов и backend-сервисов
|
||
gpu_workers.yml — node_labels, override дисков Longhorn для GPU-узлов
|
||
|
||
playbooks/ — один плейбук = одна CI/CD-задача
|
||
setup_manager.yml
|
||
setup_control_plane.yml
|
||
setup_worker_plane.yml
|
||
setup_longhorn.yml
|
||
setup_traefik.yml
|
||
setup_flux.yml
|
||
setup_gitlab_agent.yml
|
||
setup_minio.yml
|
||
setup_logging.yml
|
||
setup_sealed_secrets.yml
|
||
setup_gpu.yml
|
||
|
||
roles/
|
||
k8s_manager/
|
||
k8s_control_plane/
|
||
k8s_worker/
|
||
longhorn_prereqs/
|
||
longhorn/ README.md ← стандарт работы с хранилищем
|
||
traefik/ README.md ← стандарт публикации сервисов
|
||
flux/ README.md ← стандарт GitOps-деплоя приложений
|
||
gitlab_agent/
|
||
minio/ README.md ← стандарт объектного хранилища S3
|
||
logging/ README.md ← стандарт централизованного сбора логов
|
||
sealed_secrets/
|
||
gpu_prereqs/ — nvidia-container-toolkit + containerd runtime на GPU-узле
|
||
gpu_device_plugin/ — node label + NVIDIA k8s-device-plugin с manager-ноды
|
||
gpu_model_storage/ README.md ← стандарт локального RAID1-хранилища под модели
|
||
```
|
||
|
||
---
|
||
|
||
## Роли и компоненты
|
||
|
||
### `k8s_control_plane` · `k8s_worker` · `k8s_manager`
|
||
|
||
Базовые роли развёртывания кластера. Не имеют отдельного role-README — полное описание в разделе [Архитектурные решения](#архитектурные-решения).
|
||
|
||
| Роль | Что делает | Плейбук |
|
||
|---|---|---|
|
||
| `k8s_control_plane` | containerd → kubelet → kubeadm init → CNI → kubeconfig | `setup_control_plane.yml` |
|
||
| `k8s_worker` | containerd → kubelet → kubeadm join | `setup_worker_plane.yml` |
|
||
| `k8s_manager` | kubectl / helm / k9s, Kubernetes Dashboard | `setup_manager.yml` |
|
||
|
||
<details>
|
||
<summary>Переменные k8s_control_plane</summary>
|
||
|
||
| Переменная | Значение по умолчанию | Описание |
|
||
|---|---|---|
|
||
| `k8s_version` | `1.33` | Версия Kubernetes |
|
||
| `pod_network_cidr` | `10.244.0.0/16` | Сеть подов (Flannel) |
|
||
| `service_cidr` | `10.96.0.0/12` | Сеть сервисов |
|
||
| `cni_plugin` | `flannel` | `flannel` или `calico` |
|
||
| `flannel_version` | `v0.26.1` | Версия манифеста Flannel |
|
||
| `calico_version` | `v3.27.0` | Версия манифеста Calico |
|
||
| `kubeconfig_fetch_to_managers` | `true` | Копировать kubeconfig на manager-узел |
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary>Переменные k8s_worker</summary>
|
||
|
||
| Переменная | Значение по умолчанию | Описание |
|
||
|---|---|---|
|
||
| `k8s_version` | `1.33` | Должна совпадать с control plane |
|
||
| `worker_join_source_host` | первый хост `control_plane` | Откуда читать join-команду |
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary>Переменные k8s_manager</summary>
|
||
|
||
| Переменная | Значение по умолчанию | Описание |
|
||
|---|---|---|
|
||
| `dashboard_insecure` | `false` | HTTP-режим Dashboard (переопределяется в `true` в group_vars) |
|
||
| `dashboard_manifest_url` | GitHub raw v2.7.0 | Без зависимости от CDN |
|
||
| `k8s_manager_upgrade_packages` | `false` | Полное обновление ОС (opt-in) |
|
||
|
||
</details>
|
||
|
||
---
|
||
|
||
### `gpu_prereqs` · `gpu_device_plugin`
|
||
|
||
Подключение GPU-узла к кластеру. Драйвер NVIDIA ставится вручную заранее — роль его не устанавливает, только проверяет наличие (`nvidia-smi`). Запускается **после** `setup_worker_plane.yml`, отдельным плейбуком `setup_gpu.yml`, только для узлов группы `gpu_workers` (подгруппа `workers`).
|
||
|
||
| Роль | Запускается на | Что делает |
|
||
|---|---|---|
|
||
| `gpu_prereqs` | `gpu_workers` | Проверка драйвера, установка `nvidia-container-toolkit`, `nvidia-ctk runtime configure` для containerd (default runtime) |
|
||
| `gpu_device_plugin` | `manager_nodes` | `kubectl label node <host> gpu=nvidia` для каждого узла `gpu_workers`; `kubectl apply` манифеста NVIDIA k8s-device-plugin |
|
||
|
||
<details>
|
||
<summary>Переменные gpu_prereqs / gpu_device_plugin</summary>
|
||
|
||
| Переменная | Значение по умолчанию | Описание |
|
||
|---|---|---|
|
||
| `nvidia_container_toolkit_version` | `""` (последняя) | Версия пакета `nvidia-container-toolkit` |
|
||
| `node_labels` | `{gpu: nvidia}` (в `gpu_workers.yml`) | Лейблы, навешиваемые на узел после join |
|
||
| `gpu_device_plugin_version` | `v0.17.0` | Тег релиза NVIDIA k8s-device-plugin |
|
||
| `gpu_device_plugin_manifest_url` | GitHub raw для указанной версии | Статический манифест DaemonSet |
|
||
|
||
</details>
|
||
|
||
> Порядок обязателен: `setup_worker_plane.yml` перезаписывает `/etc/containerd/config.toml` с нуля, поэтому `gpu_prereqs` (донастройка containerd под nvidia runtime) должна выполняться **после**, отдельным прогоном.
|
||
|
||
---
|
||
|
||
### `gpu_model_storage`
|
||
|
||
Выделенный локальный RAID1-раздел под файлы моделей (Ollama) на GPU-узлах. `gpu_workers` исключены из Longhorn (`longhorn_disks: []`), а корневая ФС слишком маленькая (~30 ГБ) для хранения моделей — поэтому под них нарезается отдельный раздел из неразмеченного места на тех же зеркальных дисках, что и ОС. Запускается плейбуком `setup_gpu_model_storage.yml`, независимо от порядка `kubeadm join`.
|
||
|
||
<details>
|
||
<summary>Переменные gpu_model_storage</summary>
|
||
|
||
| Переменная | Значение по умолчанию | Описание |
|
||
|---|---|---|
|
||
| `gpu_model_storage_devices` | `[]` | Диски-члены RAID1 (пусто = роль выключена); задаётся в `gpu_workers.yml` |
|
||
| `gpu_model_storage_partition_size_gb` | `1000` | Размер новой партиции на каждом диске, ГБ |
|
||
| `gpu_model_storage_raid_device` | `/dev/md1` | Имя нового mdadm-массива |
|
||
| `gpu_model_storage_mountpoint` | `/mnt/ollama-models` | Точка монтирования |
|
||
| `gpu_model_storage_fstype` | `xfs` | Файловая система |
|
||
|
||
</details>
|
||
|
||
> **Standard**: [roles/gpu_model_storage/README.md](roles/gpu_model_storage/README.md)
|
||
|
||
---
|
||
|
||
### `longhorn_prereqs` · `longhorn`
|
||
|
||
Двухэтапное развёртывание распределённого блочного хранилища.
|
||
|
||
| Роль | Запускается на | Что делает |
|
||
|---|---|---|
|
||
| `longhorn_prereqs` | `workers` | iSCSI / NFS пакеты, модули ядра, SELinux CIL-политика, форматирование и монтирование дисков XFS |
|
||
| `longhorn` | `manager_nodes` | Аннотации узлов с disk-config JSON, `helm upgrade --install longhorn` |
|
||
|
||
После установки доступен StorageClass `longhorn` (default). Приложения используют его через `storageClassName: longhorn` в PVC.
|
||
|
||
<details>
|
||
<summary>Переменные</summary>
|
||
|
||
| Переменная | Значение по умолчанию | Описание |
|
||
|---|---|---|
|
||
| `longhorn_chart_version` | `1.7.2` | Версия Helm-чарта |
|
||
| `longhorn_namespace` | `longhorn-system` | Namespace |
|
||
| `longhorn_default_replica_count` | `1` | Реплик на том; поднять до 2–3 при добавлении worker-нод |
|
||
| `longhorn_minimal_available_storage_percentage` | `10` | Минимальный свободный % хранилища |
|
||
| `longhorn_storage_over_provisioning_percentage` | `100` | Коэффициент over-provisioning |
|
||
| `longhorn_disks` | `[{device: /dev/sdb, mountpoint: /mnt/longhorn-disk1}, ...]` | Диски для форматирования; переопределяется в hosts.yml |
|
||
|
||
</details>
|
||
|
||
> **Стандарт работы с хранилищем** (PVC, StatefulSet, реплики, бэкапы, диагностика):
|
||
> [`roles/longhorn/README.md`](roles/longhorn/README.md)
|
||
|
||
---
|
||
|
||
### `traefik`
|
||
|
||
HTTP/TCP port-proxy. DaemonSet на worker-нодах. Каждый сервис получает выделенный TCP-порт из диапазона 10001–10999. Вся топология определяется через `traefik_port_map` в `inventory/prod/group_vars/traefik.yml`. Поддерживаются два режима маршрутизации: HTTP (`IngressRoute`, поле `protocol` не задаётся) и raw TCP (`IngressRouteTCP` с `HostSNI("*")`, `protocol: tcp` в port_map).
|
||
|
||
| Задача | Что делает |
|
||
|---|---|
|
||
| `firewall.yml` | Открывает 10000–10999/tcp; помещает `flannel.1`, `cni0` в зону `trusted` |
|
||
| `helm.yml` | `helm upgrade --install traefik` как DaemonSet с EntryPoint-ами из port_map |
|
||
| `middleware.yml` | Применяет `Middleware` CRD (BasicAuth) для записей с `basicauth.enabled: true` |
|
||
| `routes.yml` | Применяет `IngressRoute` (HTTP) или `IngressRouteTCP` (TCP) в зависимости от `protocol` в port_map |
|
||
|
||
<details>
|
||
<summary>Переменные</summary>
|
||
|
||
| Переменная | Значение по умолчанию | Описание |
|
||
|---|---|---|
|
||
| `traefik_chart_version` | `32.1.0` | Версия Helm-чарта |
|
||
| `traefik_namespace` | `traefik` | Namespace |
|
||
| `traefik_port_map` | `[]` | Список сервисов; переопределяется в `group_vars/traefik.yml` |
|
||
|
||
</details>
|
||
|
||
> **Стандарт публикации сервисов** (добавление порта, BasicAuth, диагностика, таблица активных портов):
|
||
> [`roles/traefik/README.md`](roles/traefik/README.md)
|
||
|
||
---
|
||
|
||
### `flux`
|
||
|
||
Устанавливает Flux CD CLI и выполняет `flux bootstrap gitlab`, подключая кластер к fleet-репозиторию `k8s-fleet` на `gitlab.gigacoms.info`.
|
||
|
||
| Задача | Что делает |
|
||
|---|---|
|
||
| `install.yml` | Flux CLI → `/usr/local/bin/flux`, bash-completion, `flux check --pre` |
|
||
| `bootstrap.yml` | `flux bootstrap gitlab` — deploy key, Flux-контроллеры в `flux-system`, манифесты в `clusters/production` |
|
||
|
||
Fleet-репозиторий: `gitlab.gigacoms.info/k8s/k8s-fleet` · путь: `clusters/production`
|
||
|
||
<details>
|
||
<summary>Переменные</summary>
|
||
|
||
| Переменная | Значение по умолчанию | Описание |
|
||
|---|---|---|
|
||
| `flux_version` | `""` (latest stable) | Версия Flux CLI |
|
||
| `flux_gitlab_hostname` | `gitlab.gigacoms.info` | Хост GitLab |
|
||
| `flux_gitlab_owner` | `k8s` | GitLab-группа fleet-репозитория |
|
||
| `flux_gitlab_repository` | `k8s-fleet` | Имя fleet-репозитория |
|
||
| `flux_gitlab_branch` | `main` | Ветка |
|
||
| `flux_gitlab_path` | `clusters/production` | Путь внутри репозитория |
|
||
| `flux_gitlab_token` | из `$GITLAB_FLUX_TOKEN` | GitLab PAT (scope: api) |
|
||
|
||
</details>
|
||
|
||
> **Стандарт GitOps-деплоя приложений** (структура fleet-repo, multi-branch, примеры с Longhorn и Traefik, CI/CD-шаблон):
|
||
> [`roles/flux/README.md`](roles/flux/README.md)
|
||
|
||
---
|
||
|
||
### `minio`
|
||
|
||
S3-совместимое объектное хранилище на базе MinIO. Запускается как standalone StatefulSet на worker-ноде, хранилище предоставляется отдельным StorageClass `longhorn-minio` (reclaimPolicy: Retain). Доступ — через Traefik на портах 10005 (S3 API) и 10006 (Console UI).
|
||
|
||
| Задача | Что делает |
|
||
|---|---|
|
||
| `storageclass.yml` | Создаёт StorageClass `longhorn-minio` (Retain, numberOfReplicas=1) |
|
||
| `namespace.yml` | Создаёт namespace `minio` |
|
||
| `helm.yml` | `helm upgrade --install minio minio/minio` с values из шаблона |
|
||
|
||
**Предварительное условие:** создать Secret `minio-root-credentials` вручную в namespace `minio`:
|
||
```bash
|
||
kubectl create secret generic minio-root-credentials \
|
||
--from-literal=rootUser=minioadmin \
|
||
--from-literal=rootPassword='СИЛЬНЫЙ_ПАРОЛЬ' \
|
||
-n minio
|
||
```
|
||
|
||
<details>
|
||
<summary>Переменные</summary>
|
||
|
||
| Переменная | Значение по умолчанию | Описание |
|
||
|---|---|---|
|
||
| `minio_chart_version` | `5.4.0` | Версия Helm-чарта `minio/minio` |
|
||
| `minio_image_tag` | `RELEASE.2025-04-22T22-12-26Z` | Тег образа MinIO |
|
||
| `minio_namespace` | `minio` | Namespace |
|
||
| `minio_storage_class` | `longhorn-minio` | StorageClass для PVC |
|
||
| `minio_storage_size` | `1Ti` | Размер PVC |
|
||
| `minio_console_url` | `http://10.203.0.96:10006` | URL Console (для MINIO_BROWSER_REDIRECT_URL) |
|
||
| `minio_root_secret` | `minio-root-credentials` | Имя Secret с rootUser/rootPassword |
|
||
| `minio_buckets` | `[backups, artifacts]` | Бакеты, создаваемые при старте |
|
||
|
||
</details>
|
||
|
||
> **Стандарт объектного хранилища S3** (StorageClass, пользователи, lifecycle, интеграция с Loki, масштабирование):
|
||
> [`roles/minio/README.md`](roles/minio/README.md)
|
||
|
||
---
|
||
|
||
### `logging`
|
||
|
||
PLG-стек централизованного сбора логов: **Loki** (S3 backend → MinIO), **Grafana Alloy** (DaemonSet, замена EOL Promtail), **Grafana** (UI + алерты). Все три компонента разворачиваются в namespace `monitoring` из manager-узла через Helm.
|
||
|
||
| Задача | Что делает |
|
||
|---|---|
|
||
| `namespace.yml` | Создаёт namespace `monitoring` |
|
||
| `minio-user.yml` | Создаёт bucket `loki-chunks`, пользователя `loki` с политикой только на этот bucket, Secret `loki-minio-secret` |
|
||
| `loki.yml` | `helm upgrade --install loki` в режиме single-binary с S3 backend (MinIO) |
|
||
| `alloy.yml` | `helm upgrade --install alloy` как DaemonSet — сбор логов подов + journald на всех нодах |
|
||
| `grafana.yml` | `helm upgrade --install grafana` с provisioning datasource Loki |
|
||
|
||
**Предварительное условие:** создать Secret `grafana-admin-secret` вручную в namespace `monitoring`:
|
||
```bash
|
||
kubectl create namespace monitoring
|
||
kubectl create secret generic grafana-admin-secret \
|
||
--from-literal=admin-user=admin \
|
||
--from-literal=admin-password='СИЛЬНЫЙ_ПАРОЛЬ' \
|
||
-n monitoring
|
||
```
|
||
|
||
<details>
|
||
<summary>Переменные</summary>
|
||
|
||
| Переменная | Значение по умолчанию | Описание |
|
||
|---|---|---|
|
||
| `loki_chart_version` | `7.0.0` | Версия Helm-чарта `grafana/loki` |
|
||
| `alloy_chart_version` | `1.8.2` | Версия Helm-чарта `grafana/alloy` |
|
||
| `grafana_chart_version` | `10.5.15` | Версия Helm-чарта `grafana/grafana` |
|
||
| `loki_minio_endpoint` | `http://minio.minio.svc.cluster.local:9000` | S3 endpoint для Loki |
|
||
| `loki_minio_bucket` | `loki-chunks` | Bucket для хранения чанков и индексов |
|
||
| `loki_retention_days` | `31` | Срок хранения логов в днях |
|
||
| `loki_wal_storage_size` | `10Gi` | PVC для WAL/temp Loki (не логи — они в MinIO) |
|
||
| `grafana_storage_size` | `5Gi` | PVC для базы данных Grafana |
|
||
| `grafana_root_url` | `http://10.203.0.96:10003` | Внешний URL Grafana (Traefik) |
|
||
| `grafana_admin_secret` | `grafana-admin-secret` | Имя Secret с admin-user/admin-password |
|
||
|
||
</details>
|
||
|
||
> **Стандарт централизованного сбора логов** (архитектура PLG, масштабирование, переход на Graylog, диагностика):
|
||
> [`roles/logging/README.md`](roles/logging/README.md)
|
||
|
||
---
|
||
|
||
### `sealed_secrets`
|
||
|
||
Разворачивает [Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets) — контроллер для безопасного хранения зашифрованных Secret'ов в Git. Запускается из manager-узла: контроллер — в `kube-system` через Helm, CLI `kubeseal` — на manager-узле.
|
||
|
||
| Задача | Что делает |
|
||
|---|---|
|
||
| `cli.yml` | Скачивает `kubeseal` с GitHub Releases (версия из переменной или latest), идемпотентно |
|
||
| `helm.yml` | `helm upgrade --install sealed-secrets` из `bitnami-labs/sealed-secrets` в `kube-system` |
|
||
|
||
**Использование после установки:**
|
||
```bash
|
||
# Зашифровать Secret
|
||
kubectl create secret generic my-secret --from-literal=password=mysecret --dry-run=client -o yaml \
|
||
| kubeseal --format yaml > my-sealedsecret.yaml
|
||
|
||
# Применить (можно коммитить в Git — зашифрован публичным ключом контроллера)
|
||
kubectl apply -f my-sealedsecret.yaml
|
||
```
|
||
|
||
<details>
|
||
<summary>Переменные</summary>
|
||
|
||
| Переменная | Значение по умолчанию | Описание |
|
||
|---|---|---|
|
||
| `sealed_secrets_chart_version` | `2.16.1` | Версия Helm-чарта |
|
||
| `sealed_secrets_namespace` | `kube-system` | Namespace контроллера |
|
||
| `sealed_secrets_cli_version` | `""` (latest) | Версия kubeseal CLI; пустая — берёт latest с GitHub |
|
||
|
||
</details>
|
||
|
||
---
|
||
|
||
### `gitlab_agent`
|
||
|
||
Устанавливает GitLab Agent for Kubernetes (agentk). Работает совместно с Flux: Flux деплоит, agentk даёт видимость в GitLab UI (Operate → Kubernetes clusters).
|
||
|
||
Agentk инициирует исходящее WebSocket-соединение к KAS — входящих портов не требует.
|
||
|
||
| Задача | Что делает |
|
||
|---|---|
|
||
| `config.yml` | Клонирует fleet-repo, создаёт `.gitlab/agents/production/config.yaml`, коммитит и пушит при изменении |
|
||
| `helm.yml` | `helm upgrade --install gitlab-agent` с токеном и KAS-адресом |
|
||
|
||
**Предварительное условие:** зарегистрировать агент в GitLab UI → Operate → Kubernetes clusters → Connect a cluster → имя `production` → токен в CI/CD переменную `GITLAB_AGENT_TOKEN`.
|
||
|
||
<details>
|
||
<summary>Переменные</summary>
|
||
|
||
| Переменная | Значение по умолчанию | Описание |
|
||
|---|---|---|
|
||
| `gitlab_agent_hostname` | `gitlab.gigacoms.info` | Хост GitLab |
|
||
| `gitlab_agent_name` | `production` | Имя агента (совпадает с именем в GitLab UI) |
|
||
| `gitlab_agent_namespace` | `gitlab-agent` | Namespace |
|
||
| `gitlab_agent_kas_address` | `wss://gitlab.gigacoms.info/-/kubernetes-agent/` | KAS WebSocket-адрес |
|
||
| `gitlab_agent_token` | из `$GITLAB_AGENT_TOKEN` | Токен агента |
|
||
| `gitlab_agent_ci_access_group` | `k8s` | GitLab-группа с доступом к кластеру через CI |
|
||
|
||
</details>
|
||
|
||
---
|
||
|
||
## CI/CD-пайплайн
|
||
|
||
Стадии: **validate** → **setup**
|
||
|
||
| Задача | Триггер | Описание |
|
||
|---|---|---|
|
||
| `validate/lint` | каждый push / MR | `ansible-lint` всех плейбуков и ролей |
|
||
| `validate/syntax-check` | каждый push / MR | Синтаксическая проверка всех плейбуков |
|
||
| `setup/manager_nodes` | ручной, ветка `main` | `setup_manager.yml` |
|
||
| `setup/control_plane` | ручной, ветка `main` | `setup_control_plane.yml` |
|
||
| `setup/workers` | ручной, ветка `main` | `setup_worker_plane.yml` |
|
||
| `setup/longhorn` | ручной, ветка `main` | `setup_longhorn.yml` |
|
||
| `setup/traefik` | ручной, ветка `main` | `setup_traefik.yml` |
|
||
| `setup/flux` | ручной, ветка `main` | `setup_flux.yml` |
|
||
| `setup/gitlab_agent` | ручной, ветка `main` | `setup_gitlab_agent.yml` |
|
||
| `setup/minio` | ручной, ветка `main` | `setup_minio.yml` |
|
||
| `setup/logging` | ручной, ветка `main` | `setup_logging.yml` |
|
||
| `setup/sealed_secrets` | ручной, ветка `main` | `setup_sealed_secrets.yml` |
|
||
| `setup/gpu_workers` | ручной, ветка `main` | `setup_gpu.yml` |
|
||
| `setup/gpu_model_storage` | ручной, ветка `main` | `setup_gpu_model_storage.yml` |
|
||
|
||
`resource_group: production` — все setup-задачи сериализованы, одновременно выполняется только одна.
|
||
|
||
### Переменные GitLab CI/CD (Settings → CI/CD → Variables)
|
||
|
||
| Переменная | Описание |
|
||
|---|---|
|
||
| `ANSIBLE_SSH_USER` | SSH-пользователь для целевых серверов |
|
||
| `ANSIBLE_SSHKEY_ID_RSA` | Содержимое приватного SSH-ключа (тип: File) |
|
||
| `ANSIBLE_BECOME_PASS` | Пароль sudo |
|
||
| `GITLAB_FLUX_TOKEN` | GitLab PAT (scope: api) для Flux bootstrap и клонирования fleet-repo |
|
||
| `GITLAB_AGENT_TOKEN` | Токен GitLab Agent (получить в GitLab → Operate → Kubernetes clusters) |
|
||
| `MINIO_ROOT_PASSWORD` | Пароль root-пользователя MinIO (используется при ручном создании Secret) |
|
||
| `LOKI_MINIO_PASSWORD` | Пароль пользователя `loki` в MinIO (создаётся Ansible при запуске setup_logging) |
|
||
| `GRAFANA_ADMIN_PASSWORD` | Пароль администратора Grafana (задаётся в Secret `grafana-admin-secret` вручную) |
|
||
|
||
---
|
||
|
||
## Порядок развёртывания
|
||
|
||
Для нового кластера — строго в следующем порядке:
|
||
|
||
```
|
||
1. setup:manager_nodes — инструменты оператора
|
||
2. setup:control_plane — Kubernetes, CNI, Dashboard
|
||
3. setup:workers — подключение worker-нод
|
||
4. setup:longhorn — хранилище (prereqs на workers → Helm с manager)
|
||
5. setup:traefik — порт-прокси (firewall на workers → Helm с manager)
|
||
6. setup:minio — объектное хранилище S3 (StorageClass + Helm с manager)
|
||
7. setup:flux — GitOps bootstrap
|
||
8. setup:gitlab_agent — видимость кластера в GitLab UI
|
||
9. setup:logging — PLG-стек (Loki + Alloy + Grafana)
|
||
10. setup:sealed_secrets — контроллер Sealed Secrets + kubeseal CLI
|
||
11. setup:gpu_workers — только для узлов gpu_workers, после их setup:workers
|
||
```
|
||
|
||
> **Перед запуском setup:minio** создать Secret вручную: `kubectl create secret generic minio-root-credentials --from-literal=rootUser=minioadmin --from-literal=rootPassword='...' -n minio`
|
||
|
||
> **Перед запуском setup:logging** создать Secret вручную: `kubectl create namespace monitoring && kubectl create secret generic grafana-admin-secret --from-literal=admin-user=admin --from-literal=admin-password='...' -n monitoring`
|
||
|
||
---
|
||
|
||
## Архитектурные решения
|
||
|
||
### kubeadm: version derive at runtime
|
||
`kubernetesVersion` в конфиге kubeadm определяется из `kubeadm version -o short` в runtime. Исключает ошибки несоответствия версий при изменении пакета без изменения переменной.
|
||
|
||
### single-node: снятие control-plane taint
|
||
Taint `node-role.kubernetes.io/control-plane:NoSchedule` снимается автоматически. Dashboard и прочие workload'ы размещаются на master-узле при single-node-конфигурации.
|
||
|
||
### kubeadm join: ежезапускная генерация токена
|
||
Join-токены истекают через 24 часа. Роль `k8s_worker` генерирует свежий токен на control plane при каждом запуске; шаг join идемпотентен — пропускается, если узел уже в кластере.
|
||
|
||
### Longhorn: монтирование до аннотации
|
||
Диски форматируются как XFS и монтируются по UUID (`nofail`) **до** установки Longhorn. Longhorn обнаруживает диски через аннотации узлов — не через автоопределение. Это предотвращает переформатирование при повторном запуске плейбука.
|
||
|
||
### Traefik: нет hostname, нет TLS
|
||
Каждый сервис получает выделенный порт (10001–10999). Нет hostname-routing, нет TLS — клиент подключается по `http://<worker-ip>:<port>`. TLS терминируется на уровне Traefik при необходимости. Dashboard работает в HTTP-режиме (`dashboard_insecure: true`).
|
||
|
||
### Flux + agentk: разделение ответственности
|
||
Ansible управляет **ОС и кластером** (установка, конфигурация нод). Flux управляет **приложениями внутри кластера** (деплой, обновление образов). agentk обеспечивает **видимость** состояния кластера в GitLab UI.
|
||
|
||
### GPU-узлы: отдельный плейбук, вручную ставится только драйвер
|
||
`gpu_workers` — подгруппа `workers`. NVIDIA-драйвер ставится на сервер вручную и не управляется Ansible (роль `gpu_prereqs` лишь проверяет `nvidia-smi` и падает, если драйвера нет). `setup_gpu.yml` запускается отдельно и **после** `setup_worker_plane.yml`, так как роль `k8s_worker` перегенерирует `/etc/containerd/config.toml` с нуля и стёрла бы настройку nvidia runtime, если бы порядок был обратным. GPU-узлы исключены из дефолтной конфигурации Longhorn (`longhorn_disks: []` в `gpu_workers.yml`) — это compute-нода, не storage-нода.
|
||
|
||
### Firewalld и CNI-интерфейсы
|
||
|
||
> **Критично.** `flannel.1` и `cni0` должны быть в зоне `trusted` на каждом узле кластера.
|
||
|
||
Без этого pod-to-pod-трафик от workers, приходящий на master, обрабатывается зоной `internal` — она пропускает только явно перечисленные порты. Любой порт нового сервиса молча отбрасывается, даже если порт открыт на уровне хоста.
|
||
|
||
При добавлении любой роли с `firewalld` — обязательно добавлять:
|
||
|
||
```yaml
|
||
- name: Firewall | Trust CNI interfaces
|
||
ansible.posix.firewalld:
|
||
zone: trusted
|
||
interface: "{{ item }}"
|
||
permanent: true
|
||
state: enabled
|
||
loop:
|
||
- flannel.1
|
||
- cni0
|
||
```
|
||
|
||
---
|
||
|
||
## Локальная разработка
|
||
|
||
```bash
|
||
# Установка коллекций Ansible Galaxy
|
||
ansible-galaxy collection install -r requirements.yml -p collections/ --force
|
||
|
||
# Проверка синтаксиса
|
||
ansible-playbook --syntax-check -i inventory/prod playbooks/setup_manager.yml
|
||
|
||
# Линтинг
|
||
ansible-lint playbooks/ roles/
|
||
|
||
# Dry-run (режим check + diff)
|
||
ansible-playbook -i inventory/prod playbooks/setup_control_plane.yml --check --diff
|
||
|
||
# Запуск только на одном хосте
|
||
ansible-playbook -i inventory/prod playbooks/setup_worker_plane.yml --limit k8s-worker-01
|
||
```
|
||
|
||
---
|
||
|
||
## Добавление нового компонента
|
||
|
||
1. Добавить хост в `inventory/prod/hosts.yml` (если новая нода)
|
||
2. Создать `inventory/prod/group_vars/<group>.yml` (если новая группа)
|
||
3. Создать роль `roles/<role>/` со стандартной структурой
|
||
4. Создать `roles/<role>/README.md` — подробный корп. стандарт использования компонента
|
||
5. Создать `playbooks/<operation>.yml`
|
||
6. Добавить CI/CD-задачу в `.gitlab-ci.yml` (`stage: setup`, `resource_group: production`)
|
||
7. Обновить **этот README**: краткое описание роли + ссылка на `roles/<role>/README.md`
|
||
8. Обновить `CLAUDE.md`: добавить роль в структуру репозитория и ключевые решения
|