sova/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: visual guides with platform screenshots (Gitea, ArgoCD, Grafana, Prometheus)

Browse Source
This commit is contained in:
sova-bootstrap
2026-05-28 12:40:41 +03:00
parent e3e438df68
commit 41918487ff
26 changed files with 477 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
infrastructure/test-contour/guides/argocd.md
+105
View File
@@ -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).
infrastructure/test-contour/guides/gitea-ci.md
+73
View File
@@ -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).
infrastructure/test-contour/guides/index.md
+29
View File
@@ -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).
infrastructure/test-contour/guides/monitoring.md
+123
View File
@@ -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<br/>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)