docs: пометка ЛЕГАСИ всего старого IoT (манифесты, CRD, оператор, документы, examples, Makefile) + корневой LEGACY.md; удалений нет

2026-08-16 09:37:29 +04:00
parent f8537138dd
commit eb7d312d89
34 changed files with 428 additions and 3 deletions
@@ -0,0 +1,70 @@
+# Интеграция IoT ↔ shared-sqs: состояние и рекомендации
+
+> Составлено 2026-08-16 на основе работ по сервису shared-sqs (SQS-совместимая
+> очередь на платформе Nubes). IoT будет использовать shared-sqs так же, как
+> сам shared-sqs использует managed-сервисы платформы.
+
+## 1. Что такое shared-sqs (кратко)
+
+- SQS-совместимая очередь (AWS API), Go, multi-tenant, форк GoAWS.
+- Версия на проде: **v0.1.35**.
+- Внешний endpoint: `https://sqs.containerk8s.dev.nubes.ru` (регион `us-east-1`).
+- Внутренний endpoint (для подов в том же кластере Nubes, realm iot-naeel):
+  `http://containerk8s.f1ffb134-7d16-45bd-8bef-69f6ec8ab33c.svc.cluster.local:4100`
+- Реализовано: CreateQueue, GetQueueUrl, ListQueues, SendMessage(+Batch),
+  ReceiveMessage, DeleteMessage(+Batch), ChangeMessageVisibility(+Batch),
+  PurgeQueue, DeleteQueue, Get/SetQueueAttributes, TagQueue/Untag/List,
+  FIFO (порядок + dedup 5 мин), Dead Letter Queues (RedrivePolicy).
+- Лимиты: 50 очередей на тенанта, сообщение до 256 КБ, Receive 1–10 сообщений.
+
+## 2. Что сделано и проверено (состояние на 16.08)
+
+- Все тесты зелёные: api_test 22/22, sdk_test 15/15, FIFO/DLQ e2e PASS.
+- План проверок выполнен полностью (таймауты сервера, рестарты, long-poll,
+  CLI в нагрузке, память 2ч, граница лимита 50).
+- Нагрузка: 168 591 операция без единой сервисной ошибки.
+- Сравнение с Yandex YMQ: shared-sqs быстрее (p50 6–8мс из внутренней сети,
+  89–90мс из интернета против 60–62мс / 138–150мс у YMQ).
+
+## 3. Известные проблемы ПЛАТФОРМЫ (не сервиса)
+
+1. **Таймауты каждые 31–33с на внешнем пути** (интернет → шлюз Nubes): ~5.5%
+   запросов не получают ответ 30с. Доказано серверным tcpdump: в момент сбоя
+   запрос не доходит до пода; внутри кластера потерь нет (port-forward —
+   24977 раундов, 0 сбоев). Тикет в поддержку Nubes подготовлен.
+2. **MSS=1448** на шлюзе при MTU пода 1400/underlay 1450: тела >~1400 байт
+   могут виснуть ~51с (PMTUD сломан).
+
+## 4. Рекомендации по интеграции IoT → shared-sqs
+
+1. **Использовать AWS SDK** (aws-sdk-go или boto3) с переопределением
+   endpoint'а. Не писать свой HTTP-клиент.
+2. **Ходить по внутренней сети, если IoT на Nubes в том же кластере:**
+   внутренний URL из п.1 полностью обходит проблемный внешний шлюз —
+   таймаутов 31–33с и MTU-проблем там нет. Это главная рекомендация.
+3. **Клиентские ретраи обязательны:** retries ≥ 3, read_timeout ≥ 30с
+   (для внешнего пути). При внутреннем пути достаточно дефолтов.
+4. **Размер сообщений:** до ~1300 байт — безопасно всегда; большие тела —
+   только после фикса MSS шлюзом, либо бить на части.
+5. **Receive:** VisibilityTimeout ставьте с запасом на обработку (30с+);
+   `ChangeMessageVisibility(0)` — мгновенный возврат в очередь; long-poll
+   (WaitTimeSeconds) поддерживается.
+6. **FIFO:** обязателен `MessageGroupId`; dedup-окно 5 минут; порядок
+   гарантирован внутри группы.
+7. **DLQ:** настраивается RedrivePolicy (`deadLetterTargetArn`,
+   `maxReceiveCount`); ARN DLQ должен быть tenant-scoped (как в тестах).
+8. **Лимит:** 50 очередей на тенанта — держать список очередей под контролем.
+9. **Мониторинг:** `/health` отдаёт `{"status":"ok","version":...}`;
+   метрики платформы — Grafana (как для остальных managed-сервисов).
+
+## 5. Аутентификация
+
+- Креды тенанта детерминированы: tenantID `t-`+sha256(email)[:8],
+  AccessKey `SSAK-`+sha256(email)[:12],
+  SecretKey sha256(email+":shared-sqs:secret-key:v1").
+- IoT получит свой тенант/креды через консоль Nubes (как другие сервисы).
+
+## 6. Что осталось до полного прода
+
+- Отправить тикет Nubes (таймауты шлюза + MSS) — единственный блокер для
+  интернет-клиентов. Для внутренней интеграции IoT блокеров нет.