docs/infrastructure/test-contour/cloud-site-test-01.md

# CLOUD-SITE-TEST-01: удалённый test-контур SOVA

Полное описание развёртывания test-песочницы на сервере **CLOUD-SITE-TEST-01**: сеть, домены, TLS, basic auth, платформа, приложения, CI/CD и мониторинг.

## Сводка

| Параметр | Значение |
|----------|----------|
| Сервер | `CLOUD-SITE-TEST-01` |
| ОС / k3s | Linux, k3s v1.30+ (single-node) |
| RAM | 12 GB (+ swap 8 GB) |
| VPN / SSH / kubectl | `10.0.186.3` |
| Публичный IP (DNS) | `46.243.172.227` |
| Базовый домен | `dev.sovamed.ru` |
| TLS | Let's Encrypt (cert-manager, HTTP-01) |
| GitOps | ArgoCD → Gitea `sova/sova-deploy` branch `test` |
| CI | Gitea Actions + runner in-cluster |
| Защита периметра | nginx ingress basic auth (все публичные URL) |

## Схема

```mermaid
flowchart TB
  Internet["Internet / VPN"]
  DNS["DNS *.dev.sovamed.ru → 46.243.172.227"]
  LB["ingress-nginx LoadBalancer :80/:443"]
  Auth["Basic Auth + TLS"]
  Apps["Apps: api, adm, cabinet, docs"]
  Plat["Platform: git, argocd, grafana"]
  Data["PostgreSQL, MySQL, Redis"]
  CI["Gitea Actions → registry → GitOps"]

  Internet --> DNS --> LB --> Auth
  Auth --> Apps
  Auth --> Plat
  Apps --> Data
  CI --> Plat
  Plat --> Apps
```

## Сеть и доступ

### Два «мира» адресации

- **Из VPN / офисной сети:** SSH и `kubectl` на `10.0.186.3` (см. `k3s/remote.env`).
- **Из интернета:** браузер и DNS на `46.243.172.227` — A-записи `*.dev.sovamed.ru`.

Kubeconfig локально: `~/.kube/config-sova-remote-test`.

### /etc/hosts (опционально)

Если DNS ещё не резолвится, добавьте на рабочую машину:

```
46.243.172.227 git.dev.sovamed.ru argocd.dev.sovamed.ru grafana.dev.sovamed.ru
46.243.172.227 api.dev.sovamed.ru adm.dev.sovamed.ru cabinet.dev.sovamed.ru docs.dev.sovamed.ru
```

На ноде k3s для pull образов: `10.0.186.3 git.dev.sovamed.ru git.sova.local` → registry mirror.

## Домены и сервисы

| URL | Назначение | Namespace |
|-----|------------|-----------|
| https://git.dev.sovamed.ru | Gitea + Container Registry + Actions | `gitea` |
| https://argocd.dev.sovamed.ru | ArgoCD UI | `argocd` |
| https://grafana.dev.sovamed.ru | Grafana (метрики + Loki) | `monitoring` |
| https://api.dev.sovamed.ru | Backend API | `sova-test` |
| https://adm.dev.sovamed.ru | Admin Panel | `sova-test` |
| https://cabinet.dev.sovamed.ru | Cabinet (ЛК) | `sova-test` |
| https://docs.dev.sovamed.ru | Документация (VitePress) | `sova-test` |

Redmine на этом контуре **отключён** (`SKIP_REDMINE=1`).

## TLS (Let's Encrypt)

1. **cert-manager** в namespace `cert-manager`.
2. **ClusterIssuer** `letsencrypt-prod` — HTTP-01 через ingress-nginx.
3. На каждом Ingress: annotation `cert-manager.io/cluster-issuer: letsencrypt-prod` + блок `tls`.
4. **Требование:** порт **80** с интернета до `46.243.172.227` (ACME challenge).

Подробнее: `k3s/TLS.md`.

Проверка сертификатов:

```bash
kubectl get certificate -A
curl -vI https://api.dev.sovamed.ru 2>&1 | grep subject
```

## Basic Auth на ingress (периметр)

Все публичные URL закрыты **HTTP Basic Auth** на уровне **ingress-nginx** (LoadBalancer 80/443).

| Параметр | Значение |
|----------|----------|
| Логин | `sova-contour` |
| Пароль | см. `k8s/.generated/platform-credentials.env` → `BASIC_AUTH_PASS` |
| Secret в кластере | `contour-basic-auth` (ключ `auth`, формат htpasswd) |
| Namespaces | `argocd`, `gitea`, `monitoring`, `sova-test` |

### Поведение

1. Браузер запрашивает **basic auth** (периметр).
2. Затем — логин приложения (Gitea, ArgoCD, Grafana, API и т.д.).

Чтобы CI/CD и `git push` работали без Basic в заголовке `Authorization`, для **git.dev.sovamed.ru** используются **два Ingress**:

| Ingress | Пути | Basic auth |
|---------|------|------------|
| `gitea-api` | `/api`, `/v2`, `/sova`, `/.well-known/acme-challenge` | нет |
| `gitea` | `/` (веб-UI) | да |

### Управление

```bash
# Создать/обновить секреты (пароль из platform-credentials.env)
./scripts/bootstrap-ingress-basic-auth.sh

# Применить аннотации на platform ingress
ENABLE_TLS=1 GITEA_DOMAIN=git.dev.sovamed.ru \
  ARGOCD_DOMAIN=argocd.dev.sovamed.ru \
  GRAFANA_DOMAIN=grafana.dev.sovamed.ru \
  ./scripts/deploy-platform-ingress.sh
```

Приложения (api, adm, cabinet, docs): GitOps через `values-test.yaml` → `ingress.basicAuth.enabled: true`.

## Платформенный стек

Устанавливается `k8s/scripts/deploy-platform-remote.sh`:

| Компонент | Helm chart | Namespace |
|-----------|------------|-----------|
| ingress-nginx | ingress-nginx | `ingress` |
| cert-manager | cert-manager | `cert-manager` |
| sealed-secrets | sealed-secrets | `kube-system` |
| ArgoCD | argo-cd | `argocd` |
| Prometheus + Grafana | kube-prometheus-stack | `monitoring` |
| Loki + Promtail | loki-stack | `monitoring` |
| Gitea + Registry + Actions | gitea | `gitea` |

Lite-профиль для 12 GB: `sova-deploy/platform/monitoring/values-lite-12gb.yaml`.

**Grafana + Loki:** datasource Loki подключается через `grafana.additionalDataSources` в Helm (не отдельный ConfigMap — иначе Grafana 13 падает). Explore → Loki → `{namespace="sova-test"}`.

## Приложения и данные

ArgoCD ApplicationSet `test-contour` (`sova-deploy/argocd/apps/test-contour.yaml`):

| App | Helm path | Namespace |
|-----|-----------|-----------|
| backend-test | `apps/backend` | `sova-test` |
| adminpanel-test | `apps/adminpanel` | `sova-test` |
| cabinet-test | `apps/cabinet` | `sova-test` |
| docs-test | `apps/docs` | `sova-test` |
| data-test | `data/test` | `sova-data-test` |
| mocks-test | `apps/mocks` | `sova-mocks` |

Базы: PostgreSQL (backend + cabinet), MySQL (Bitrix stub), Redis. Пароли — в `platform-credentials.env` и `sova-deploy/data/test/values.yaml` (GitOps).

### Тестовые пользователи приложений

| Сервис | Логин | Пароль (test seed) |
|--------|-------|---------------------|
| Admin Panel | `local.backend@example.test` | см. `APP_ADMIN_PASS` |
| Cabinet | `local.cabinet@example.test` | см. `APP_CABINET_PASS` |

Admin Panel ходит в API `https://api.dev.sovamed.ru` (runtime `env.js` + `runtimeEnv.API_BASE_URL` в Helm).

## CI/CD и теги

### Git-flow

- Ветки: `prod`, `test`, `stage`, `issues/27-*`
- Test-контур деплоится с ветки **`test`** репозиториев и `sova-deploy`.

### Формат тега

```
{component}-v{semver}-{env}
```

Примеры: `backend-v1.0.13-test`, `docs-v1.0.14-test`.

### Pipeline (Gitea Actions)

1. Push тега `*-test` → workflow `build.yml`
2. Docker build → push в Gitea Registry (`git.sova.local/sova/{repo}`)
3. Job `deploy-gitops` обновляет `apps/{repo}/values-test.yaml` в `sova-deploy`
4. ArgoCD sync → rollout pods

Релиз с локальной машины:

```bash
export KUBECONFIG=~/.kube/config-sova-remote-test
export VM_IP=10.0.186.3 GITEA_SCHEME=https GITEA_HTTP_PORT=443 GITEA_INSECURE_TLS=1
export GITEA_HOST=git.dev.sovamed.ru

./scripts/release-tag.sh docs docs-v1.0.14-test
```

## Bootstrap с нуля

Оркестратор: `k3s/scripts/bootstrap-remote-test.sh` (читает `k3s/remote.env`).

```bash
cd k3s
cp remote.env.example remote.env   # заполнить SSH, домены
./scripts/bootstrap-remote-test.sh
```

Основные шаги:

1. k3s на сервере, swap, kubeconfig
2. Platform (ingress, cert-manager, Gitea, ArgoCD, monitoring)
3. **basic auth** + platform ingress
4. Gitea org/repos, CI runner, registry mirror
5. ArgoCD apps, TLS issuers, sync test-contour
6. (опционально) push тегов приложений

Повторный bootstrap с середины: `BOOTSTRAP_FROM_STEP=4` в `remote.env`.

## Креды и секреты

Файл **`k8s/.generated/platform-credentials.env`** (не в git):

| Переменная | Назначение |
|------------|------------|
| `GITEA_ADMIN` / `GITEA_ADMIN_PASS` | Gitea admin |
| `ARGOCD_PASS` | ArgoCD admin |
| `GRAFANA_PASS` | Grafana admin |
| `BASIC_AUTH_USER` / `BASIC_AUTH_PASS` | Периметр ingress |
| `PG_PASS`, `MYSQL_*`, `REDIS_PASS` | Базы данных |
| `APP_ADMIN_PASS`, `APP_CABINET_PASS` | Seed-пользователи |

Печать: `./scripts/print-credentials.sh`

## Мониторинг и логи

- **Grafana:** https://grafana.dev.sovamed.ru — дашборды kube-prometheus
- **Loki:** Explore → `{namespace="sova-test"}` | `{namespace="gitea"}`
- **Prometheus:** in-cluster `kube-prometheus-kube-prome-prometheus.monitoring:9090` (публичный ingress не настроен)

## Типовые операции

```bash
# Kubeconfig
export KUBECONFIG=~/.kube/config-sova-remote-test

# Статус ArgoCD apps
kubectl get applications -n argocd

# Sync вручную
kubectl annotate application backend-test -n argocd argocd.argoproj.io/refresh=hard --overwrite

# Логи backend
kubectl logs -n sova-test deploy/backend -c php-fpm --tail=50

# Обновить basic auth пароль
# 1) правка BASIC_AUTH_PASS в platform-credentials.env
# 2) ./scripts/bootstrap-ingress-basic-auth.sh
```

## Отличия от локальной Multipass-фермы

| | Локально (Multipass) | CLOUD-SITE-TEST-01 |
|--|----------------------|---------------------|
| Домены | `*.sova.local`, NodePort | `*.dev.sovamed.ru`, LB 443 |
| TLS | часто self-signed / off | Let's Encrypt |
| Basic auth | нет | да (ingress) |
| Redmine | опционально | выключен |
| IP | VM Multipass | 46.243.172.227 / VPN 10.0.186.3 |

## Связанные документы

- [Git-flow и теги](./git-flow.md)
- [Система тегов CI/CD](./tags.md)
- [Gitea CI](./guides/gitea-ci.md)
- [ArgoCD apps](./guides/argocd.md)
- [Grafana / Loki](./guides/monitoring.md)
- [k3s/TLS.md](https://github.com/sova/k3s/TLS.md) — в репозитории `k3s/TLS.md`

---

*Документ актуален для контура CLOUD-SITE-TEST-01 (июнь 2026). Обновление docs: тег `docs-v*-test` → CI → https://docs.dev.sovamed.ru*