214 lines
15 KiB
Markdown
214 lines
15 KiB
Markdown
# Архитектура и план миграции shared-sqs → Nubes Managed
|
||
|
||
**Дата:** 2026-08-13
|
||
**Источник:** ответ Claude Sonnet на промпт по миграции
|
||
|
||
---
|
||
|
||
## 1. Код-ревью (блокеры деплоя)
|
||
|
||
| Файл | Находка | Блокер? | Что делать |
|
||
|---|---|---|---|
|
||
| `goaws.yaml` + `tenant_helpers.go` | `Host: goaws.com`, `Port: 4100` bake-in в образ. QueueUrl клиентам возвращается как `http://us-east-1.goaws.com:4100/{tenantID}/{queueName}`. Поскольку текущий k8s работает с тем же расхождением (ingress `qu.kube5s.ru` ≠ `goaws.com`), клиенты используют endpoint_url + только path из QueueUrl — **не подключаются к goaws.com напрямую**. | НЕТ (условно) | Обновить `Host` в `goaws.yaml` после выяснения нового домена, пересобрать образ. Это смена конфига, не Go-кода. |
|
||
| `redis.go` | Подключение без TLS: `redis.Options{Addr, Username, Password, DB:0}` — нет `TLSConfig`. Если Managed Redis требует TLS на internal DNS — блокер. | **ОТКРЫТЫЙ ВОПРОС** | Уточнить у Nubes: требует ли managed Redis TLS для `*.svc.cluster.local`. Если нет — не блокер. |
|
||
| `goaws.go` | Порт задаётся флагом `--port` (default 4100), не env `PORT`. ENTRYPOINT в Dockerfile не передаёт `--port` — слушает 4100. | НЕТ | nubes_http должен маршрутизировать на порт 4100 (или платформа сама определяет порт — уточнить). |
|
||
| `goaws.go` | `ReceiveMessage` с long-polling держит HTTP-соединение до 20 секунд (`WaitTimeSeconds`). В Ingress был `proxy-read-timeout: 30`. | НЕТ (в коде) | nubes_http должен иметь read-timeout ≥ 30 секунд — уточнить у платформы. |
|
||
| `admin.go` | `NUBES_ENDPOINT` default = `https://deck-api-test.ngcloud.ru/api/v1` (тестовый). Для production нужен production URL. | НЕТ (env-override) | Задать `NUBES_ENDPOINT` production URL в env vars контейнера. |
|
||
| `deployment.yaml` | `SHARED_SQS_SEED_DEMO=true` — сидирует демо-данные при каждом старте. | НЕТ | Не задавать или `=false` в production деплое. |
|
||
| `Dockerfile` | `imagePullSecrets: sless-registry-auth` (k8s). Образ `naeel/shared-sqs` на Docker Hub — нужно проверить публичность. | НЕТ (вероятно) | Если образ публичный — секрет не нужен. Уточнить, как nubes_http указывает registry. |
|
||
|
||
**Вывод: жёстких code-level блокеров нет. Код менять не нужно.** Единственное изменение при известном домене — пересборка образа с обновлённым `goaws.yaml` (поле `Host`).
|
||
|
||
---
|
||
|
||
## 2. Целевая архитектура
|
||
|
||
### Схема
|
||
|
||
```mermaid
|
||
graph TD
|
||
Client["AWS SDK/CLI<br/>boto3 / aws-sdk-go<br/>(endpoint_url = новый домен)"]
|
||
LB["Nubes HTTP Gateway<br/>TLS termination<br/>timeout ≥ 30s"]
|
||
App["nubes_http<br/>naeel/shared-sqs:v0.1.x<br/>port 4100<br/>RAM 64–256Mi / CPU 50–500m"]
|
||
Redis["Managed Redis<br/>redisk8s.4ff5678b-b683-4aef-91da-22d89dec8a25<br/>.svc.cluster.local:6379<br/>512MB / 10GB"]
|
||
PG["Managed PostgreSQL<br/>(опционально, billing)"]
|
||
NubesAPI["Nubes API<br/>deck-api-*.ngcloud.ru<br/>JWT-валидация UI-сессий"]
|
||
VM["VictoriaMetrics<br/>scrape /metrics"]
|
||
|
||
Client -->|"HTTPS :443"| LB
|
||
LB -->|"HTTP :4100<br/>internal"| App
|
||
App -->|"TCP :6379<br/>internal DNS<br/>без TLS"| Redis
|
||
App -.->|"TCP :5432<br/>BILLING_PG_HOST"| PG
|
||
App -->|"HTTPS<br/>JWT validate"| NubesAPI
|
||
VM -->|"GET /metrics"| App
|
||
```
|
||
|
||
### Компоненты
|
||
|
||
| Компонент | Ресурс Nubes | Описание |
|
||
|---|---|---|
|
||
| SQS-сервис | `nubes_http` | Образ `naeel/shared-sqs:v0.1.x`, порт 4100, stateless |
|
||
| Persistence | Managed Redis `4ff5678b-...` | Ключи `ssq:tenants`, `ssq:queues`, `ssq:msg:{key}` |
|
||
| Billing (opt.) | Managed PostgreSQL | Таблица `sqs_usage_records`, auto-migrate при старте |
|
||
| JWT auth | Nubes API (внешний) | Только для UI-консоли, не для SQS API |
|
||
|
||
### Переменные окружения для nubes_http
|
||
|
||
```
|
||
SHARED_SQS_ADMIN_TOKEN=<секрет>
|
||
REDIS_ADDR=redisk8s.4ff5678b-b683-4aef-91da-22d89dec8a25.svc.cluster.local:6379
|
||
REDIS_USER=default
|
||
REDIS_PASSWORD=ZJOke5b2bIr6YPOKrnJG
|
||
NUBES_ENDPOINT=https://deck-api.ngcloud.ru/api/v1 ← production URL (уточнить)
|
||
SHARED_SQS_SEED_DEMO=false
|
||
|
||
# Опционально — billing:
|
||
BILLING_PG_HOST=...
|
||
BILLING_PG_PORT=5432
|
||
BILLING_PG_DATABASE=...
|
||
BILLING_PG_USER=...
|
||
BILLING_PG_PASSWORD=...
|
||
BILLING_PG_SSLMODE=require
|
||
```
|
||
|
||
### Ключевые инварианты архитектуры
|
||
|
||
- **Один процесс, stateless:** всё состояние в Redis. Рестарт контейнера восстанавливает тенантов и очереди через `LoadAllTenantsRaw` + `LoadAllQueues`.
|
||
- **Фоновые горутины:** `PeriodicTasks` (visibility timeout, DLQ, dedup) и `StartGaugeUpdater` запускаются в рамках процесса — не требуют отдельных воркеров.
|
||
- **Long-polling:** до 20 секунд на соединение — платформа должна держать коннект открытым.
|
||
- **Multi-tenancy:** изоляция по ключу `{accessKey}:{queueName}` в Redis и in-memory; тенанты хранятся в `ssq:tenants` HASH.
|
||
|
||
---
|
||
|
||
## 3. План миграции
|
||
|
||
### Фаза 0 — Ответы на открытые вопросы (блокирует всё остальное)
|
||
|
||
**0.1.** Уточнить у команды Nubes: порт `nubes_http` (видит ли платформа `EXPOSE 4100` или нужно явно указывать), DNS-видимость `*.svc.cluster.local`, TLS на Redis.
|
||
*Критерий приёмки: письменный ответ по всем 4 пунктам открытых вопросов.*
|
||
|
||
**0.2.** Проверить доступность Managed Redis из realm iot-naeel.
|
||
Команда (запустить временный pod или контейнер в том же realm):
|
||
```bash
|
||
redis-cli -h redisk8s.4ff5678b-b683-4aef-91da-22d89dec8a25.svc.cluster.local \
|
||
-p 6379 -u default -a ZJOke5b2bIr6YPOKrnJG ping
|
||
```
|
||
*Критерий: ответ `PONG`.*
|
||
|
||
---
|
||
|
||
### Фаза 1 — Подготовка (без downtime, k8s работает)
|
||
|
||
**1.1.** Решить судьбу данных: мигрировать из k8s Redis или начать с чистого листа.
|
||
- **Вариант А (clean start):** нулевое состояние. Требует пересоздания тенантов через Admin API и уведомления клиентов о новых ключах. Риск: потеря очередей с сообщениями.
|
||
- **Вариант Б (миграция):** экспорт `ssq:tenants`, `ssq:queues`, `ssq:msg:*` из k8s Redis → импорт в Managed Redis. Сохраняет всё состояние, но требует краткого maintenance window.
|
||
*Критерий: явное решение согласовано.*
|
||
|
||
**1.2 (если Вариант Б).** Экспортировать ключи из k8s Redis:
|
||
```bash
|
||
# Получить все ключи ssq:*
|
||
kubectl exec -n shared-sqs deploy/shared-sqs-redis -- \
|
||
redis-cli -a <пароль> --scan --pattern "ssq:*" | \
|
||
xargs -I{} kubectl exec -n shared-sqs deploy/shared-sqs-redis -- \
|
||
redis-cli -a <пароль> DUMP {}
|
||
```
|
||
Либо через `redis-cli --rdb /tmp/dump.rdb`, затем передать в Managed Redis через `RESTORE`.
|
||
*Критерий: все ключи `ssq:tenants`, `ssq:queues`, `ssq:msg:*` присутствуют в Managed Redis (проверить `HLEN ssq:tenants`, `HLEN ssq:queues`).*
|
||
|
||
**1.3.** Обновить `goaws.yaml` с новым `Host` (финальный домен из ответа на вопрос 0.1.4), пересобрать и запушить образ:
|
||
```bash
|
||
docker build -t naeel/shared-sqs:v0.1.23 .
|
||
docker push naeel/shared-sqs:v0.1.23
|
||
```
|
||
*Критерий: образ доступен в registry.*
|
||
*Откат: не нужен — k8s ещё работает на v0.1.22.*
|
||
|
||
---
|
||
|
||
### Фаза 2 — Деплой nubes_http (параллельно с k8s)
|
||
|
||
**2.1.** Создать ресурс `nubes_http` в realm iot-naeel:
|
||
- Образ: `naeel/shared-sqs:v0.1.23`
|
||
- Порт: 4100 (или как определит платформа)
|
||
- Ресурсы: min 64Mi/50m, max 256Mi/500m
|
||
- Env vars: полный список из раздела архитектуры выше
|
||
- Health check: `GET /health` (уже в Dockerfile)
|
||
|
||
*Критерий: контейнер запустился, `/health` отвечает `200 OK`.*
|
||
*Откат: удалить ресурс nubes_http, трафик остаётся в k8s.*
|
||
|
||
**2.2.** Smoke test нового инстанса (напрямую по URL nubes_http, до переключения трафика):
|
||
```bash
|
||
# Health
|
||
curl -m 5 https://new-domain.nubes.example/health
|
||
|
||
# Создать тенанта через Admin API
|
||
curl -m 5 -X POST https://new-domain.nubes.example/admin/tenants \
|
||
-H "Authorization: Bearer <ADMIN_TOKEN>" \
|
||
-d '{"name":"smoke-test","maxQueues":5}'
|
||
|
||
# Получить AccessKey/SecretKey из ответа, создать очередь
|
||
aws sqs create-queue --queue-name test-q \
|
||
--endpoint-url https://new-domain.nubes.example \
|
||
--region us-east-1
|
||
|
||
# Отправить и получить сообщение
|
||
aws sqs send-message --queue-url ... --message-body "hello"
|
||
aws sqs receive-message --queue-url ...
|
||
```
|
||
*Критерий: все 3 операции успешны. Prometheus /metrics содержит метрики sqs_*.*
|
||
*Откат: исправить env vars, пересобрать образ.*
|
||
|
||
**2.3 (если Вариант Б — миграция данных).** Проверить восстановление:
|
||
```bash
|
||
# Запустить контейнер → смотреть логи старта
|
||
# Должны увидеть: "persistence: подключились к Redis", "Ошибка загрузки тенантов" НЕ должна быть
|
||
# Проверить тенантов через Admin API
|
||
curl https://new-domain.nubes.example/admin/tenants -H "Authorization: Bearer ..."
|
||
```
|
||
*Критерий: в ответе Admin API видны все тенанты, перенесённые из k8s Redis.*
|
||
|
||
---
|
||
|
||
### Фаза 3 — Переключение трафика
|
||
|
||
**3.1.** Договориться с клиентами о maintenance window (только для Варианта Б, чтобы не было записей во время переноса данных). Для Варианта А — без окна.
|
||
|
||
**3.2.** Обновить конфигурацию клиентов: заменить `endpoint_url` c `qu.kube5s.ru` (или текущего) на новый домен Nubes. Домен `qu.kube5s.ru` — не использовать.
|
||
|
||
**3.3.** Мониторить в течение N минут/часов:
|
||
- `/metrics` → Prometheus: `sqs_messages_sent_total`, `sqs_messages_received_total`
|
||
- Ошибки в логах контейнера (`log.Error`)
|
||
- Latency Redis (таймауты в логах `persistence: HSet`)
|
||
|
||
*Критерий: ошибок в логах нет, метрики растут, клиенты работают.*
|
||
*Откат: перевести клиентов обратно на k8s endpoint (он ещё жив на этом этапе).*
|
||
|
||
---
|
||
|
||
### Фаза 4 — Вывод k8s (только после подтверждённой стабильности)
|
||
|
||
**4.1.** После N дней стабильной работы: удалить k8s ресурсы shared-sqs (Deployment, Service, Ingress, HPA если есть).
|
||
|
||
**4.2.** Удалить k8s Redis (Deployment shared-sqs-redis, PVC shared-sqs-redis-pvc). **Необратимо — делать только после полной проверки данных в Managed Redis.**
|
||
|
||
**4.3.** Удалить k8s Secrets (shared-sqs-admin, shared-sqs-redis). Предварительно убедиться, что все значения есть в nubes_http env или Nubes Secrets.
|
||
|
||
*Критерий: namespace shared-sqs в k8s пуст или удалён. Сервис работает только через nubes_http.*
|
||
|
||
---
|
||
|
||
## 4. Открытые вопросы и риски
|
||
|
||
| # | Приоритет | Вопрос | Последствие |
|
||
|---|---|---|---|
|
||
| 1 | **КРИТИЧНО** | Какой порт принимает nubes_http? Читает ли платформа `EXPOSE 4100` или нужно явно задать в конфиге ресурса? | Если порт не 4100 — нужен флаг `--port N` в ENTRYPOINT или env `PORT` |
|
||
| 2 | **КРИТИЧНО** | Видит ли контейнер nubes_http DNS `*.svc.cluster.local` в realm iot-naeel? | Если нет — `REDIS_ADDR` с internal hostname не сработает, нужен другой адрес Redis |
|
||
| 3 | **КРИТИЧНО** | Требует ли Managed Redis TLS для internal соединений? | Если да — код `redis.Options` без TLSConfig — блокер, нужна правка (минимальная: добавить `TLSConfig: &tls.Config{}`) |
|
||
| 4 | **ВЫСОКИЙ** | Какой внешний URL/домен получит nubes_http ресурс? | Без домена нельзя обновить `goaws.yaml` → QueueUrl клиентам будет содержать `goaws.com` (косметика, но может сломать специфичные клиенты) |
|
||
| 5 | **ВЫСОКИЙ** | Docker Hub образ `naeel/shared-sqs` публичный или приватный? Как nubes_http указывает registry credentials? | Если приватный — нужна конфигурация pull secret на уровне платформы |
|
||
| 6 | **ВЫСОКИЙ** | Поддерживает ли nubes_http long-lived HTTP соединения до 20 секунд? (long-polling SQS) | Если платформа имеет timeout < 20s — клиенты с `WaitTimeSeconds>0` будут получать ошибки |
|
||
| 7 | **СРЕДНИЙ** | Мигрировать данные (тенанты, очереди, сообщения) из k8s Redis или начать чисто? | Clean start: нет риска, но потеря данных. Миграция: сложнее, требует maintenance window |
|
||
| 8 | **НИЗКИЙ** | Какой production URL для `NUBES_ENDPOINT`? Текущий default `deck-api-test.ngcloud.ru` — тестовый | UI JWT-авторизация сломается на production если endpoint не обновить |
|
||
| 9 | **НИЗКИЙ** | `SHARED_SQS_SEED_DEMO=true` в k8s — нужен ли демо-режим в production nubes_http? | Если нет — просто не задавать env. Демо-тенант создаётся при каждом старте |
|