diff --git a/.vitepress/config.mts b/.vitepress/config.mts index 4180bec..f2b720c 100644 --- a/.vitepress/config.mts +++ b/.vitepress/config.mts @@ -99,6 +99,10 @@ export default defineConfig({ collapsed: false, items: [ { text: 'Обзор', link: '/infrastructure/test-contour/' }, + { text: 'Визуальные гайды', link: '/infrastructure/test-contour/guides/' }, + { text: 'Gitea: теги и CI/CD', link: '/infrastructure/test-contour/guides/gitea-ci' }, + { text: 'ArgoCD: приложения', link: '/infrastructure/test-contour/guides/argocd' }, + { text: 'Grafana / Prometheus / Loki', link: '/infrastructure/test-contour/guides/monitoring' }, { text: 'Что сделано + перенос на сервер', link: '/infrastructure/test-contour/test-contour-article' }, { text: 'Система тегов CI/CD', link: '/infrastructure/test-contour/tags' }, { text: 'ArgoCD: sova-root и data-test', link: '/infrastructure/test-contour/argocd-apps' } diff --git a/.vitepress/theme/style.css b/.vitepress/theme/style.css index be53921..b8cd738 100644 --- a/.vitepress/theme/style.css +++ b/.vitepress/theme/style.css @@ -13,3 +13,21 @@ max-width: 100%; height: auto; } + +/* Platform guide screenshots */ +.vp-doc img[src*="/screenshots/"] { + display: block; + margin: 1rem auto 0.5rem; + max-width: 100%; + border: 1px solid var(--vp-c-divider); + border-radius: 10px; + box-shadow: 0 8px 24px rgba(0, 0, 0, 0.08); +} + +.vp-doc img[src*="/screenshots/"] + em, +.vp-doc p:has(+ img[src*="/screenshots/"]) { + display: block; + text-align: center; + color: var(--vp-c-text-2); + font-size: 0.9em; +} diff --git a/infrastructure/test-contour/guides/argocd.md b/infrastructure/test-contour/guides/argocd.md new file mode 100644 index 0000000..6771e8a --- /dev/null +++ b/infrastructure/test-contour/guides/argocd.md @@ -0,0 +1,105 @@ +# ArgoCD: приложения test-контура + +ArgoCD — GitOps UI: следит за `sova-deploy` и `sova-mocks`, раскатывает Helm charts в кластер. + +Краткая теория: [sova-root и data-test](../argocd-apps). + +## 1. Вход + +http://argocd.sova.local — логин **admin**, пароль: + +```bash +kubectl -n argocd get secret argocd-initial-admin-secret \ + -o jsonpath='{.data.password}' | base64 -d && echo +``` + +![ArgoCD login](../screenshots/07-argocd-login.png) + +## 2. Список Applications + +На главной — все приложения test-контура: + +| Application | Что деплоит | Есть URL? | +|-------------|-------------|-----------| +| `backend-test` | Symfony API | api.test.sova.local | +| `adminpanel-test` | React admin | admin.test.sova.local | +| `cabinet-test` | Symfony ЛК | cabinet.test.sova.local | +| `docs-test` | VitePress docs | docs.sova.local | +| `mocks-test` | WireMock, Mailpit | internal | +| `data-test` | PostgreSQL, MySQL, Redis | нет (БД) | +| `sova-root` | другие Application CR | нет (meta) | + +![Applications list](../screenshots/08-argocd-applications.png) + +**Sync Status `Unknown`** часто нормален для local — смотрите **Health** и pod'ы в namespace. + +## 3. Пользовательское приложение: `backend-test` + +Откройте карточку → дерево ресурсов: Deployment, Service, Ingress, CronJob, Secret. + +![backend-test detail](../screenshots/09-argocd-backend-test.png) + +### Sync вручную + +Кнопка **Sync** → **Synchronize** — подтянуть последний `main` из Gitea. + +### Terminal в pod (миграции, отладка) + +1. Deployment `backend` → Pod +2. Container **php-fpm** → иконка **Terminal** +3. Пример: `php bin/console cache:clear --env=prod` + +Exec включён в `platform/argocd/values-test.yaml` (`exec.enabled: true`). + +### CronJob в UI + +Фильтр по label `app.kubernetes.io/component: console` — видны `backend-sync-doctors`, `backend-clear-schedule-cache` и т.д. + +## 4. `sova-root` — app-of-apps + +**Не приложение с URL.** Только создаёт/обновляет другие Application из `argocd/apps/`. + +![sova-root](../screenshots/10-argocd-sova-root.png) + +«Войти» сюда нельзя — открывайте дочерние apps (`backend-test`, `docs-test`, …). + +## 5. `data-test` — слой данных + +PostgreSQL (backend + cabinet), MySQL Bitrix, Redis. **Без Ingress.** + +![data-test](../screenshots/11-argocd-data-test.png) + +Подключение из pod'ов приложений: + +``` +postgresql-test.sova-data-test.svc.cluster.local:5432 +mysql-bitrix-test.sova-data-test.svc.cluster.local:3306 +redis-test-master.sova-data-test.svc.cluster.local:6379 +``` + +Инициализация schema/seed — Job `db-init` (отдельный чарт), не через браузер. + +## 6. Типичный цикл после CI + +```mermaid +sequenceDiagram + participant Dev as Разработчик + participant Gitea as Gitea tag + participant CI as Actions + participant Deploy as sova-deploy + participant Argo as ArgoCD + participant K8s as Kubernetes + + Dev->>Gitea: release-test-tag.sh + Gitea->>CI: push tag + CI->>Deploy: bump values-test.yaml + Argo->>Deploy: poll main + Argo->>K8s: helm upgrade +``` + +1. Push тега в Gitea +2. CI обновляет `apps/backend/values-test.yaml` +3. ArgoCD auto-sync (или Sync вручную) +4. Новый pod с образом из registry + +Дальше: [Grafana, Prometheus, Loki](./monitoring). diff --git a/infrastructure/test-contour/guides/gitea-ci.md b/infrastructure/test-contour/guides/gitea-ci.md new file mode 100644 index 0000000..65cf33e --- /dev/null +++ b/infrastructure/test-contour/guides/gitea-ci.md @@ -0,0 +1,73 @@ +# Gitea: теги, CI/CD и registry + +В test-контуре каждый сервис (`backend`, `adminpanel`, `cabinet`, `docs`) — **отдельный репозиторий** в Gitea. Релиз = **git-тег** → Gitea Actions → Docker-образ → обновление `sova-deploy` → ArgoCD sync. + +Подробнее о формате тегов: [Система тегов CI/CD](../tags). + +## 1. Вход в Gitea + +Откройте http://git.sova.local и войдите под `gitea_admin` (пароль — из bootstrap или `.generated/platform-credentials.env`). + +![Страница входа Gitea](../screenshots/01-gitea-login.png) + +## 2. Репозитории организации `sova` + +Все сервисы и GitOps лежат в org **sova**: + +| Репозиторий | Назначение | +|-------------|------------| +| `backend`, `adminpanel`, `cabinet`, `docs` | код + `.gitea/workflows/build.yml` | +| `sova-deploy` | Helm values, ArgoCD manifests | +| `sova-mocks` | WireMock, Mailpit | + +![Организация sova](../screenshots/02-gitea-org-sova.png) + +## 3. Gitea Actions — pipeline на push тега + +Workflow в каждом app-репозитории: + +1. **test** — unit/build проверки +2. **build-and-push** — образ в Container Registry +3. **deploy-gitops** — commit в `sova-deploy` (`values-test.yaml`) + +![Список workflow runs](../screenshots/03-gitea-backend-actions.png) + +Откройте последний успешный run — все три job должны быть зелёными: + +![Детали pipeline](../screenshots/04-gitea-action-run.png) + +::: tip Terminal на runner +Логи runner: `kubectl logs -n gitea -l app.kubernetes.io/name=actions-runner -c runner -f` +::: + +## 4. Как выкатить тег (с Mac) + +```bash +cd k3s-test +./scripts/release-test-tag.sh backend backend-v1.0.1-test +./scripts/release-test-tag.sh adminpanel adminpanel-v1.0.1-test +./scripts/release-test-tag.sh cabinet cabinet-v1.0.1-test +./scripts/release-test-tag.sh docs docs-v1.0.1-test +``` + +Скрипт создаёт аннотированный тег и пушит в Gitea. Тег виден в репозитории: + +![Теги backend](../screenshots/05-gitea-backend-tags.png) + +Формат: `{component}-v{semver}-{env}` → например `backend-v1.0.1-test`. + +## 5. Container Registry + +После успешного `build-and-push` образ появляется в **Packages** репозитория: + +![Container packages](../screenshots/06-gitea-backend-packages.png) + +В Helm `values-test.yaml` используется pull через `git.sova.local/sova/backend:backend-v1.0.1-test` (см. `./scripts/configure-k3s-registry.sh`). + +## 6. Чеклист после релиза + +1. http://git.sova.local/sova/backend/actions — все jobs **success** +2. http://argocd.sova.local — `backend-test` **Synced / Healthy** +3. `curl http://api.test.sova.local/news/list?page=1` → **200** + +Дальше: [ArgoCD — приложения и sync](./argocd). diff --git a/infrastructure/test-contour/guides/index.md b/infrastructure/test-contour/guides/index.md new file mode 100644 index 0000000..1296179 --- /dev/null +++ b/infrastructure/test-contour/guides/index.md @@ -0,0 +1,29 @@ +# Визуальные гайды test-контура + +Пошаговые инструкции со **скриншотами** реального UI песочницы: Gitea CI, ArgoCD, Grafana, Prometheus и Loki. + +Перед просмотром добавьте в `/etc/hosts` IP VM (см. `./scripts/print-urls.sh`): + +``` +192.168.252.2 git.sova.local argocd.sova.local grafana.sova.local prometheus.sova.local docs.sova.local +``` + +## Разделы + +| Гайд | О чём | +|------|--------| +| [Gitea: теги и CI/CD](./gitea-ci) | push тега → Actions → registry → deploy-gitops | +| [ArgoCD: приложения](./argocd) | Applications, sync, backend vs sova-root vs data-test | +| [Grafana, Prometheus, Loki](./monitoring) | метрики, targets, логи в Explore | + +## Обновление скриншотов + +Скрины лежат в [`../screenshots/`](../screenshots/). Переснять после изменений UI: + +```bash +cd k3s-test +./scripts/capture-platform-screenshots/run.sh +cd sova-docs && npm run build # локальная проверка +``` + +Скрипт использует Playwright и логинится в сервисы test-контура автоматически (креды из `.generated/platform-credentials.env` и kubectl). diff --git a/infrastructure/test-contour/guides/monitoring.md b/infrastructure/test-contour/guides/monitoring.md new file mode 100644 index 0000000..d45077f --- /dev/null +++ b/infrastructure/test-contour/guides/monitoring.md @@ -0,0 +1,123 @@ +# Grafana, Prometheus и Loki + +В test-контуре мониторинг разделён: + +| Инструмент | URL | Задача | +|------------|-----|--------| +| **Prometheus** | http://prometheus.sova.local | метрики, targets, PromQL | +| **Grafana** | http://grafana.sova.local | дашборды + **логи через Loki** | +| **Loki** | только через Grafana Explore | агрегация логов pod'ов | + +Prometheus **не хранит логи** — для логов используйте Grafana → Explore → datasource **Loki**. + +Установка Loki/Promtail: `./scripts/deploy-monitoring-logs.sh` + +## Grafana + +### Вход + +http://grafana.sova.local — **admin** / пароль: + +```bash +kubectl -n monitoring get secret kube-prometheus-grafana \ + -o jsonpath='{.data.admin-password}' | base64 -d && echo +``` + +![Grafana login](../screenshots/12-grafana-login.png) + +### Главная + +Дашборды kube-prometheus (CPU, memory, pod restarts). Полезно для общего health кластера: + +![Grafana home](../screenshots/13-grafana-home.png) + +### Loki — логи приложений + +**Explore** (иконка компаса) → datasource **Loki** → LogQL: + +```logql +{namespace="sova-test"} +``` + +Уточнение по pod: + +```logql +{namespace="sova-test", pod=~"backend.*"} |= "error" +``` + +![Grafana Explore Loki](../screenshots/14-grafana-loki-explore.png) + +::: tip Нет логов? +1. `./scripts/deploy-monitoring-logs.sh` +2. Проверьте Promtail: `kubectl get pods -n monitoring -l app.kubernetes.io/name=promtail` +3. В Grafana: Configuration → Data sources → Loki должен быть **green** +::: + +### Типовые сценарии + +| Задача | Действие | +|--------|----------| +| 500 от API | Loki `{namespace="sova-test", pod=~"backend.*"}` | +| CronJob упал | `{namespace="sova-test"} \|= "backend-sync-doctors"` | +| Ingress 502 | `{namespace="ingress-nginx"}` | + +## Prometheus + +Отдельный UI без логина (test-контур). + +### Graph — PromQL запросы + +http://prometheus.sova.local/graph + +Примеры: + +```promql +up # живые targets +rate(http_requests_total[5m]) # RPS (если есть метрика) +container_memory_working_set_bytes{namespace="sova-test"} +``` + +![Prometheus Graph](../screenshots/15-prometheus-graph.png) + +### Targets — кто отдаёт метрики + +http://prometheus.sova.local/targets + +**UP** (зелёный) — scrape OK. **DOWN** — проверьте ServiceMonitor / pod. + +![Prometheus Targets](../screenshots/16-prometheus-targets.png) + +### Быстрая проверка «всё живо» + +Запрос `up` за последний час: + +![Prometheus up query](../screenshots/17-prometheus-up-query.png) + +Значение **1** — target доступен, **0** — проблема. + +## Сводка: куда смотреть + +```mermaid +flowchart LR + subgraph metrics["Метрики"] + prom["Prometheus
prometheus.sova.local"] + graf_m["Grafana dashboards"] + end + subgraph logs["Логи"] + loki["Loki"] + graf_l["Grafana Explore"] + promtail["Promtail"] + end + pods["Pod logs"] --> promtail --> loki --> graf_l + pods --> prom + prom --> graf_m +``` + +| Симптом | Куда | +|---------|------| +| Медленный API, restarts | Grafana dashboards / Prometheus `container_*` | +| Ошибка в коде, stack trace | Grafana → Loki | +| ServiceMonitor не работает | Prometheus → Targets | +| Нет datasource Loki | `./scripts/deploy-monitoring-logs.sh` | + +Назад: [Gitea CI/CD](./gitea-ci) · [ArgoCD](./argocd) diff --git a/infrastructure/test-contour/index.md b/infrastructure/test-contour/index.md index f24cb52..5fdc5ae 100644 --- a/infrastructure/test-contour/index.md +++ b/infrastructure/test-contour/index.md @@ -6,6 +6,15 @@ ## Разделы +### Визуальные гайды (скриншоты) + +- [Обзор гайдов](./guides/) — Gitea, ArgoCD, Grafana, Prometheus, Loki +- [Gitea: теги и CI/CD](./guides/gitea-ci) +- [ArgoCD: приложения](./guides/argocd) +- [Grafana / Prometheus / Loki](./guides/monitoring) + +### Текстовая документация + - [Test-контур: что сделано и перенос на сервер](./test-contour-article) — полная статья - [Система тегов CI/CD](./tags) — формат тегов и release-скрипт - [ArgoCD: sova-root и data-test](./argocd-apps) — зачем эти приложения и почему «нельзя войти» diff --git a/infrastructure/test-contour/screenshots/01-gitea-login.png b/infrastructure/test-contour/screenshots/01-gitea-login.png new file mode 100644 index 0000000..584aa22 Binary files /dev/null and b/infrastructure/test-contour/screenshots/01-gitea-login.png differ diff --git a/infrastructure/test-contour/screenshots/02-gitea-org-sova.png b/infrastructure/test-contour/screenshots/02-gitea-org-sova.png new file mode 100644 index 0000000..51a6468 Binary files /dev/null and b/infrastructure/test-contour/screenshots/02-gitea-org-sova.png differ diff --git a/infrastructure/test-contour/screenshots/03-gitea-backend-actions.png b/infrastructure/test-contour/screenshots/03-gitea-backend-actions.png new file mode 100644 index 0000000..914911d Binary files /dev/null and b/infrastructure/test-contour/screenshots/03-gitea-backend-actions.png differ diff --git a/infrastructure/test-contour/screenshots/04-gitea-action-run.png b/infrastructure/test-contour/screenshots/04-gitea-action-run.png new file mode 100644 index 0000000..6c2257c Binary files /dev/null and b/infrastructure/test-contour/screenshots/04-gitea-action-run.png differ diff --git a/infrastructure/test-contour/screenshots/05-gitea-backend-tags.png b/infrastructure/test-contour/screenshots/05-gitea-backend-tags.png new file mode 100644 index 0000000..96dd62e Binary files /dev/null and b/infrastructure/test-contour/screenshots/05-gitea-backend-tags.png differ diff --git a/infrastructure/test-contour/screenshots/06-gitea-backend-packages.png b/infrastructure/test-contour/screenshots/06-gitea-backend-packages.png new file mode 100644 index 0000000..841f66a Binary files /dev/null and b/infrastructure/test-contour/screenshots/06-gitea-backend-packages.png differ diff --git a/infrastructure/test-contour/screenshots/07-argocd-login.png b/infrastructure/test-contour/screenshots/07-argocd-login.png new file mode 100644 index 0000000..54d77d6 Binary files /dev/null and b/infrastructure/test-contour/screenshots/07-argocd-login.png differ diff --git a/infrastructure/test-contour/screenshots/08-argocd-applications.png b/infrastructure/test-contour/screenshots/08-argocd-applications.png new file mode 100644 index 0000000..f39e425 Binary files /dev/null and b/infrastructure/test-contour/screenshots/08-argocd-applications.png differ diff --git a/infrastructure/test-contour/screenshots/09-argocd-backend-test.png b/infrastructure/test-contour/screenshots/09-argocd-backend-test.png new file mode 100644 index 0000000..fe6a416 Binary files /dev/null and b/infrastructure/test-contour/screenshots/09-argocd-backend-test.png differ diff --git a/infrastructure/test-contour/screenshots/10-argocd-sova-root.png b/infrastructure/test-contour/screenshots/10-argocd-sova-root.png new file mode 100644 index 0000000..c8da2fd Binary files /dev/null and b/infrastructure/test-contour/screenshots/10-argocd-sova-root.png differ diff --git a/infrastructure/test-contour/screenshots/11-argocd-data-test.png b/infrastructure/test-contour/screenshots/11-argocd-data-test.png new file mode 100644 index 0000000..4d53421 Binary files /dev/null and b/infrastructure/test-contour/screenshots/11-argocd-data-test.png differ diff --git a/infrastructure/test-contour/screenshots/12-grafana-login.png b/infrastructure/test-contour/screenshots/12-grafana-login.png new file mode 100644 index 0000000..3c278fe Binary files /dev/null and b/infrastructure/test-contour/screenshots/12-grafana-login.png differ diff --git a/infrastructure/test-contour/screenshots/13-grafana-home.png b/infrastructure/test-contour/screenshots/13-grafana-home.png new file mode 100644 index 0000000..7a3e5bd Binary files /dev/null and b/infrastructure/test-contour/screenshots/13-grafana-home.png differ diff --git a/infrastructure/test-contour/screenshots/14-grafana-loki-explore.png b/infrastructure/test-contour/screenshots/14-grafana-loki-explore.png new file mode 100644 index 0000000..55ddfc3 Binary files /dev/null and b/infrastructure/test-contour/screenshots/14-grafana-loki-explore.png differ diff --git a/infrastructure/test-contour/screenshots/15-prometheus-graph.png b/infrastructure/test-contour/screenshots/15-prometheus-graph.png new file mode 100644 index 0000000..f31ee27 Binary files /dev/null and b/infrastructure/test-contour/screenshots/15-prometheus-graph.png differ diff --git a/infrastructure/test-contour/screenshots/16-prometheus-targets.png b/infrastructure/test-contour/screenshots/16-prometheus-targets.png new file mode 100644 index 0000000..9c24d27 Binary files /dev/null and b/infrastructure/test-contour/screenshots/16-prometheus-targets.png differ diff --git a/infrastructure/test-contour/screenshots/17-prometheus-up-query.png b/infrastructure/test-contour/screenshots/17-prometheus-up-query.png new file mode 100644 index 0000000..07ac54b Binary files /dev/null and b/infrastructure/test-contour/screenshots/17-prometheus-up-query.png differ diff --git a/infrastructure/test-contour/screenshots/README.md b/infrastructure/test-contour/screenshots/README.md new file mode 100644 index 0000000..6a2ca49 --- /dev/null +++ b/infrastructure/test-contour/screenshots/README.md @@ -0,0 +1,25 @@ +# Platform screenshots (test contour) + +Автоматически сгенерировано `./scripts/capture-platform-screenshots/run.sh`. + +| File | Title | +|------|-------| +| 01-gitea-login.png | Gitea: страница входа | +| 02-gitea-org-sova.png | Gitea: организация sova | +| 03-gitea-backend-actions.png | Gitea Actions | +| 04-gitea-action-run.png | Pipeline run | +| 05-gitea-backend-tags.png | Теги backend | +| 06-gitea-backend-packages.png | Container Registry | +| 07-argocd-login.png | ArgoCD login | +| 08-argocd-applications.png | Applications list | +| 09-argocd-backend-test.png | backend-test | +| 10-argocd-sova-root.png | sova-root | +| 11-argocd-data-test.png | data-test | +| 12-grafana-login.png | Grafana login | +| 13-grafana-home.png | Grafana home | +| 14-grafana-loki-explore.png | Loki Explore | +| 15-prometheus-graph.png | Prometheus Graph | +| 16-prometheus-targets.png | Prometheus Targets | +| 17-prometheus-up-query.png | PromQL up | + +Полный manifest: `manifest.json` diff --git a/infrastructure/test-contour/screenshots/manifest.json b/infrastructure/test-contour/screenshots/manifest.json new file mode 100644 index 0000000..44b5235 --- /dev/null +++ b/infrastructure/test-contour/screenshots/manifest.json @@ -0,0 +1,91 @@ +{ + "capturedAt": "2026-05-28T09:37:54.363Z", + "vmIp": "192.168.252.2", + "items": [ + { + "file": "01-gitea-login.png", + "title": "Gitea: страница входа", + "notes": "" + }, + { + "file": "02-gitea-org-sova.png", + "title": "Gitea: организация sova и репозитории", + "notes": "" + }, + { + "file": "03-gitea-backend-actions.png", + "title": "Gitea Actions: workflow backend", + "notes": "" + }, + { + "file": "04-gitea-action-run.png", + "title": "Gitea Actions: прогон pipeline (jobs)", + "notes": "" + }, + { + "file": "05-gitea-backend-tags.png", + "title": "Gitea: теги релиза backend-v*", + "notes": "" + }, + { + "file": "06-gitea-backend-packages.png", + "title": "Gitea: Container Registry (образы)", + "notes": "" + }, + { + "file": "07-argocd-login.png", + "title": "ArgoCD: вход", + "notes": "" + }, + { + "file": "08-argocd-applications.png", + "title": "ArgoCD: список Applications", + "notes": "" + }, + { + "file": "09-argocd-backend-test.png", + "title": "ArgoCD: backend-test (ресурсы и sync)", + "notes": "" + }, + { + "file": "10-argocd-sova-root.png", + "title": "ArgoCD: sova-root (app-of-apps, без pod URL)", + "notes": "" + }, + { + "file": "11-argocd-data-test.png", + "title": "ArgoCD: data-test (PostgreSQL/MySQL/Redis)", + "notes": "" + }, + { + "file": "12-grafana-login.png", + "title": "Grafana: вход", + "notes": "" + }, + { + "file": "13-grafana-home.png", + "title": "Grafana: главная / дашборды", + "notes": "" + }, + { + "file": "14-grafana-loki-explore.png", + "title": "Grafana Explore: логи Loki (namespace sova-test)", + "notes": "" + }, + { + "file": "15-prometheus-graph.png", + "title": "Prometheus: Graph / PromQL", + "notes": "" + }, + { + "file": "16-prometheus-targets.png", + "title": "Prometheus: Status → Targets", + "notes": "" + }, + { + "file": "17-prometheus-up-query.png", + "title": "Prometheus: запрос up (живые targets)", + "notes": "" + } + ] +}