Nail/IoT
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: старые артефакты IoT перенесены в legacy/ (git mv, история сохранена); активное дерево очищено, go build OK

Browse Source
This commit is contained in:
“Naeel”
2026-08-16 09:48:34 +04:00
parent bf32394def
commit f0c36a11ee
30 changed files with 31 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files
legacy/doc/architecture/current-v0.2.3.md
+258
View File
@@ -0,0 +1,258 @@
> ⛔⛔⛔ ЛЕГАСИ (2026-08-16) — СТАРЫЙ IoT (k8s-деплой). НЕ ПРИНИМАТЬ ВО ВНИМАНИЕ. Актуальное: HISTORY/2026-08-16-session-log.md
# IoT Managed Service — Актуальная архитектура (v0.2.3)
> Дата: 2026-04-12
> Образ: naeel/iot-operator:v0.2.3
> Кластер: iot-naeel, namespace: sless
---
## Путь данных (data flow)
```
IoT Device (MQTT CONNECT)
| username="{ns}_{deviceId}", password=hex(64)
v
EMQX 5.5.1 (Pod emqx, namespace sless)
| 1. POST /internal/mqtt/auth -> iot-operator:9090
| - Bridge auth: username=iot-bridge-internal -> allow
| - Device auth: username={ns}_{deviceId} -> Secret -> compare
| 2. POST /internal/mqtt/acl -> iot-operator:9090
| - Device: pub/sub только {ns}/telemetry/{deviceId}
| - Bridge: sub на +/telemetry/+ (wildcard)
v
| MQTT PUBLISH -> topic: "{ns}/telemetry/{deviceId}"
v
iot-mqtt-bridge (Pod, namespace sless)
| paho.mqtt.golang, подписка на "+/telemetry/+"
| Парсит topic -> namespace (segment 0), deviceId (segment 2)
| AWS SDK SQS SendMessage -> shared-SQS
v
shared-SQS (namespace shared-sqs)
| Endpoint: https://qu.kube5s.ru
| Tenant: iot-service (ID: t-96afe7e9f781f6ca)
| Queue: iot-telemetry
v
iot-sqs-consumer (Pod, namespace sless)
| ReceiveMessage (WaitTimeSeconds=20, long polling)
| Парсит envelope -> namespace, device_id, payload
| EnsureTenantDB(namespace) -> CREATE DATABASE tenant_{ns}
| INSERT INTO iot_telemetry
| DeleteMessage (at-least-once)
v
Managed PostgreSQL 17
| Host: postgresqlk8s-master.dc5db45d-....svc.cluster.local
| Per-tenant: DATABASE tenant_{namespace}
| Таблица: iot_telemetry (id, device_id, payload JSONB, received_at, created_at)
v
REST API (iot-operator:9090)
| GET /v1/namespaces/{ns}/iot/telemetry?device=X&limit=N
v
Пользователь
| IoT Console: https://iot.kube5s.ru/console
| WebSocket MQTT: wss://iot.kube5s.ru/mqtt
| Terraform: sless_iot_device resource
```
---
## Компоненты
### iot-operator (cmd/iot-operator)
Единый бинарник: controller-manager + REST API сервер.
| Функция | Описание |
|---------|----------|
| IoTDevice Controller | Reconcile: создание Secret с MQTT credentials, OwnerReference |
| REST API :9090 | CRUD устройств, телеметрия, MQTT auth/acl, admin stats, UI |
| Health :8081 | /healthz, /readyz для k8s probes |
### iot-mqtt-bridge (cmd/mqtt-bridge)
MQTT subscriber -> SQS producer. Stateless.
| Параметр | Значение |
|----------|----------|
| MQTT broker | tcp://emqx.sless.svc:1883 |
| MQTT username | iot-bridge-internal (Secret iot-bridge-credentials) |
| MQTT subscription | +/telemetry/+ |
| SQS endpoint | https://qu.kube5s.ru |
| SQS queue | iot-telemetry |
Bridge auth (v0.2.3): operator проверяет BridgeUsername/BridgePassword ДО парсинга namespace_deviceId.
### iot-sqs-consumer (cmd/sqs-consumer)
SQS consumer -> Postgres writer. Stateless.
| Параметр | Значение |
|----------|----------|
| SQS endpoint | https://qu.kube5s.ru |
| SQS queue | iot-telemetry |
| Long polling | WaitTimeSeconds=20 |
| Postgres | IOT_PG_DSN из Secret |
| Семантика | at-least-once (DeleteMessage после INSERT) |
### EMQX 5.5.1
MQTT-брокер с HTTP auth backend.
| Параметр | Значение |
|----------|----------|
| Образ | emqx/emqx:5.5.1 |
| Порты | 1883 (MQTT), 8083 (WebSocket), 18083 (Dashboard) |
| Auth | HTTP POST -> iot-operator:9090/internal/mqtt/auth |
| ACL | HTTP POST -> iot-operator:9090/internal/mqtt/acl |
| Конфиг | HOCON emqx.conf через ConfigMap |
---
## CRD: IoTDevice (iot.kube5s.ru/v1alpha1)
### Spec
| Поле | Тип | Обязательное | Описание |
|------|-----|-------------|----------|
| deviceId | string | да | Pattern: ^[a-z0-9][a-z0-9-]*[a-z0-9]$ |
| enabled | bool | нет | default: true |
| metadata | map[string]string | нет | Произвольные метаданные |
### Status
| Поле | Описание |
|------|----------|
| phase | Active / Disabled / Pending / Error |
| mqttUsername | {namespace}_{deviceId} |
| secretName | iot-{deviceId} |
| topicPrefix | {namespace}/ |
| message | Сообщение об ошибке |
### Reconcile logic
1. Добавить finalizer iot.kube5s.ru/device-cleanup
2. Если Secret iot-{deviceId} не существует:
- crypto/rand 32 bytes -> hex (64 символа) = пароль
- Создать Secret с OwnerReference -> каскадное удаление
- Keys: mqtt-username, mqtt-password, device-id
3. Status: phase=Active, mqttUsername={ns}_{deviceId}
4. Если enabled=false -> phase=Disabled (Secret НЕ удаляется)
5. DELETE: finalizer cleanup -> Secret удаляется каскадно
---
## Аутентификация
### REST API (/v1/)
- Middleware: Bearer JWT token
- authTestMode = true (текущий): любой непустой Bearer token принимается
- authTestMode = false (prod): JWT decode -> sub -> SHA256 -> namespace mapping
### MQTT Auth (/internal/mqtt/auth)
1. Если username == BridgeUsername -> проверить BridgePassword -> allow/deny
2. Иначе: парсить username по первому "_" -> namespace + deviceId
3. Найти Secret iot-{deviceId} в namespace
4. crypto/subtle.ConstantTimeCompare(password, secret.mqtt-password)
5. Всегда HTTP 200, body: {"result": "allow"} или {"result": "deny"}
### MQTT ACL (/internal/mqtt/acl)
- Bridge (clientid=sless-iot-bridge): allow subscribe +/telemetry/+
- Device: allow pub/sub только {namespace}/telemetry/{deviceId}
- Всё остальное: deny
---
## Хранение данных
### PostgreSQL (managed)
| Параметр | Значение |
|----------|----------|
| Версия | PG 17 |
| Host | postgresqlk8s-master.dc5db45d-f8b4-4fd0-ad33-ec4dd017f2d5.svc.cluster.local |
| User | super |
| Master DB | sqsdb |
Per-tenant изоляция: отдельная DATABASE tenant_{namespace}.
Таблица iot_telemetry:
- id SERIAL PRIMARY KEY
- device_id TEXT NOT NULL
- payload JSONB NOT NULL
- received_at TIMESTAMPTZ
- created_at TIMESTAMPTZ DEFAULT NOW()
### shared-SQS
| Параметр | Значение |
|----------|----------|
| Endpoint | https://qu.kube5s.ru |
| Tenant | iot-service (t-96afe7e9f781f6ca) |
| Queue | iot-telemetry |
| Протокол | AWS SQS API compatible |
---
## Docker образ
- Registry: Docker Hub naeel/iot-operator
- Базовый: gcr.io/distroless/static:nonroot
- Содержит 3 бинарника: /iot-operator, /mqtt-bridge, /sqs-consumer
- Выбор бинарника через command в Deployment YAML
---
## Сетевая схема
```
Internet
|
v
nginx-ingress (namespace ingress)
| iot.kube5s.ru/mqtt -> emqx-ws:8083 (WebSocket)
| iot.kube5s.ru/console -> iot-operator:9090 (UI)
| iot.kube5s.ru/iot-admin -> iot-operator:9090 (Admin UI)
v
namespace sless:
emqx:1883 <-> iot-mqtt-bridge (MQTT)
emqx:1883 <- IoT devices (MQTT)
iot-operator:9090 <- emqx (auth/acl HTTP)
iot-operator:9090 <- users (REST API)
iot-mqtt-bridge -> shared-sqs (HTTPS, SQS API)
iot-sqs-consumer <- shared-sqs (HTTPS, SQS API)
iot-sqs-consumer -> managed-postgres (TCP 5432)
iot-operator -> managed-postgres (TCP 5432, telemetry GET)
iot-operator -> k8s API (CRD watch, Secret CRUD)
namespace shared-sqs:
shared-sqs:9324 (SQS API)
Ingress: qu.kube5s.ru -> shared-sqs
namespace dc5db45d-...:
postgresqlk8s-0 (PG 17 managed)
```
---
## Секреты (namespace sless)
| Secret | Ключи | Используется |
|--------|-------|-------------|
| iot-bridge-credentials | MQTT_USERNAME, MQTT_PASSWORD | iot-operator, iot-mqtt-bridge |
| iot-sqs-credentials | SQS_ENDPOINT, SQS_ACCESS_KEY, SQS_SECRET_KEY | iot-mqtt-bridge, iot-sqs-consumer |
| iot-postgres-secret | IOT_PG_DSN | iot-sqs-consumer |
---
## Эволюция архитектуры
| Версия | Дата | Message bus | Postgres | Кластер |
|--------|------|------------|----------|---------|
| v0.1.50 | 2026-04-04 | RabbitMQ (AMQP) | emptyDir PVC | sless (общий) |
| v0.1.68 | 2026-04-06 | Kafka (segmentio/kafka-go) | emptyDir PVC | sless (общий) |
| v0.2.0 | 2026-04-12 | shared-SQS (AWS SDK) | Managed PG 17 | iot-naeel (новый) |
| v0.2.3 | 2026-04-12 | shared-SQS (AWS SDK) | Managed PG 17 | iot-naeel |
legacy/doc/architecture/overview.md
+236
View File
@@ -0,0 +1,236 @@
> ⛔⛔⛔ ЛЕГАСИ (2026-08-16) — СТАРЫЙ IoT (k8s-деплой). НЕ ПРИНИМАТЬ ВО ВНИМАНИЕ. Актуальное: HISTORY/2026-08-16-session-log.md
# IoT Managed Service — Архитектура
## Общая схема
```
IoT Device (MQTT CONNECT)
│ username="{ns}_{deviceId}", password=hex
▼
EMQX 5.5.1 (sless/emqx)
│ POST /internal/mqtt/auth → iot-operator:9090
│ POST /internal/mqtt/acl → iot-operator:9090
▼
│ MQTT PUBLISH → topic: "{ns}/telemetry/{deviceId}"
▼
iot-mqtt-bridge (cmd/mqtt-bridge)
│ подписка на "+/telemetry/+"
│ → Kafka topic "iot.telemetry"
▼
Kafka
▼
iot-kafka-consumer (cmd/kafka-consumer)
│ consumer group "iot-pg-consumer"
│ → per-tenant Postgres DB
▼
IoT Postgres (iot-postgres.sless.svc)
│ DB: tenant_{namespace}
│ Table: iot_telemetry
▼
REST API (iot-operator:9090)
│ GET /v1/namespaces/{ns}/iot/telemetry
▼
Пользователь (Terraform / UI Console)
```
## Компоненты
| Компонент | Бинарник | Порт | Назначение |
|-----------|----------|------|------------|
| iot-operator | cmd/iot-operator | :9090 (API), :8081 (health) | Controller-manager + REST API |
| mqtt-bridge | cmd/mqtt-bridge | — | MQTT→Kafka bridge |
| kafka-consumer | cmd/kafka-consumer | — | Kafka→Postgres pipeline |
## CRD
- **IoTDevice** (`iot.kube5s.ru/v1alpha1`)
- Создание: пользователь через API / Terraform
- Controller генерирует MQTT credentials → k8s Secret
- Secret удаляется каскадно через OwnerReference
## Хранение
- **IoT Postgres** — отдельный от sless PG
- Management DB: `iot_platform` (таблица `tenant_credentials`)
- Per-tenant DB: `tenant_{namespace}` (таблица `iot_telemetry`)
## Аутентификация
- REST API (/v1/): Bearer JWT (middleware.Auth)
- MQTT Auth (/internal/): вызывается EMQX, без JWT
- Admin (/iot-admin/stats): ADMIN_STATS_TOKEN
## Docker образ
- `naeel/iot-operator` (Docker Hub)
- Все 3 бинарника в одном образе
- `command: ["/iot-operator"]` или `["/mqtt-bridge"]` или `["/kafka-consumer"]`
---
## Актуальная архитектура (2026-04-12)
> Kafka заменён на shared-SQS. Postgres заменён на managed. Новый кластер iot-naeel.
### Текущая схема
```
IoT Device (MQTT CONNECT)
│ username="{ns}_{deviceId}", password=hex
▼
EMQX 5.5.1 (sless/emqx)
│ POST /internal/mqtt/auth → iot-operator:9090
│ POST /internal/mqtt/acl → iot-operator:9090
▼
│ MQTT PUBLISH → topic: "{ns}/telemetry/{deviceId}"
▼
iot-mqtt-bridge (cmd/mqtt-bridge)
│ подписка на "+/telemetry/+"
│ → AWS SDK SQS SendMessage → shared-SQS (https://qu.kube5s.ru)
│ очередь: "iot-telemetry" (tenant: iot-service, id: t-96afe7e9f781f6ca)
▼
shared-SQS (namespace shared-sqs)
│ AWS SQS-совместимый, multi-tenant
▼
iot-sqs-consumer (cmd/sqs-consumer)
│ ReceiveMessage (WaitTimeSeconds=20, long polling)
│ DeleteMessage после успешной записи (at-least-once)
│ → per-tenant Postgres DB
▼
Managed PostgreSQL 17 (namespace dc5db45d-f8b4-4fd0-ad33-ec4dd017f2d5)
│ Host: postgresqlk8s-master.dc5db45d-....svc.cluster.local
│ User: super, DB: sqsdb
│ Per-tenant DB: tenant_{namespace}, Table: iot_telemetry
▼
REST API (iot-operator:9090)
│ GET /v1/namespaces/{ns}/iot/telemetry
▼
Пользователь (Terraform / UI Console)
│ wss://iot.kube5s.ru/mqtt (WebSocket через Ingress)
│ https://iot.kube5s.ru/console (UI)
```
### Компоненты (актуальные)
| Компонент | Бинарник | Порт | Назначение |
|-----------|----------|------|------------|
| iot-operator | cmd/iot-operator | :9090 (API), :8080 (metrics), :8081 (health) | Controller-manager + REST API |
| mqtt-bridge | cmd/mqtt-bridge | — | MQTT → shared-SQS bridge |
| sqs-consumer | cmd/sqs-consumer | — | shared-SQS → Postgres pipeline |
### Инфраструктура
| Сервис | Тип | Namespace | Описание |
|--------|-----|-----------|----------|
| EMQX 5.5.1 | В кластере | sless | MQTT-брокер, HTTP auth/acl → iot-operator |
| shared-SQS | В кластере | shared-sqs | AWS SQS-совместимая очередь, endpoint https://qu.kube5s.ru |
| PostgreSQL 17 | Managed (оператор) | dc5db45d-... | per-tenant DB, тот же инстанс что и SQS billing |
| cert-manager | В кластере | cert-manager | TLS сертификаты для iot.kube5s.ru |
| nginx-ingress | В кластере | ingress | WSS/HTTPS проксирование |
### Секреты в namespace sless
| Secret | Ключи | Источник |
|--------|-------|----------|
| iot-sqs-credentials | SQS_ENDPOINT, SQS_ACCESS_KEY, SQS_SECRET_KEY | shared-SQS tenant iot-service |
| iot-postgres-secret | POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB, IOT_PG_DSN | Managed PG |
| iot-bridge-credentials | MQTT_USERNAME, MQTT_PASSWORD | Для mqtt-bridge → EMQX |
### Docker образ (актуальный)
- `naeel/iot-operator:v0.2.0` (Docker Hub)
- Все 3 бинарника в одном образе
- `command: ["/iot-operator"]` или `["/mqtt-bridge"]` или `["/sqs-consumer"]`
- Базовый: `gcr.io/distroless/static:nonroot`
### Кластер
- Имя: `iot-naeel`
- API: `https://185.247.187.149:6443`
- Ingress IP: `185.247.187.151`
- DNS: `iot.kube5s.ru → 185.247.187.147`
---
## Актуальная архитектура (2026-04-12)
> Kafka заменён на shared-SQS. Postgres заменён на managed. Новый кластер iot-naeel.
### Текущая схема
```
IoT Device (MQTT CONNECT)
│ username="{ns}_{deviceId}", password=hex
▼
EMQX 5.5.1 (sless/emqx)
│ POST /internal/mqtt/auth → iot-operator:9090
│ POST /internal/mqtt/acl → iot-operator:9090
▼
│ MQTT PUBLISH → topic: "{ns}/telemetry/{deviceId}"
▼
iot-mqtt-bridge (cmd/mqtt-bridge)
│ подписка на "+/telemetry/+"
│ → AWS SDK SQS SendMessage → shared-SQS (https://qu.kube5s.ru)
│ очередь: "iot-telemetry" (tenant: iot-service, id: t-96afe7e9f781f6ca)
▼
shared-SQS (namespace shared-sqs)
│ AWS SQS-совместимый, multi-tenant
▼
iot-sqs-consumer (cmd/sqs-consumer)
│ ReceiveMessage (WaitTimeSeconds=20, long polling)
│ DeleteMessage после успешной записи (at-least-once)
│ → per-tenant Postgres DB
▼
Managed PostgreSQL 17 (namespace dc5db45d-f8b4-4fd0-ad33-ec4dd017f2d5)
│ Host: postgresqlk8s-master.dc5db45d-....svc.cluster.local
│ User: super, DB: sqsdb
│ Per-tenant DB: tenant_{namespace}, Table: iot_telemetry
▼
REST API (iot-operator:9090)
│ GET /v1/namespaces/{ns}/iot/telemetry
▼
Пользователь (Terraform / UI Console)
│ wss://iot.kube5s.ru/mqtt (WebSocket через Ingress)
│ https://iot.kube5s.ru/console (UI)
```
### Компоненты (актуальные)
| Компонент | Бинарник | Порт | Назначение |
|-----------|----------|------|------------|
| iot-operator | cmd/iot-operator | :9090 (API), :8080 (metrics), :8081 (health) | Controller-manager + REST API |
| mqtt-bridge | cmd/mqtt-bridge | — | MQTT → shared-SQS bridge |
| sqs-consumer | cmd/sqs-consumer | — | shared-SQS → Postgres pipeline |
### Инфраструктура
| Сервис | Тип | Namespace | Описание |
|--------|-----|-----------|----------|
| EMQX 5.5.1 | В кластере | sless | MQTT-брокер, HTTP auth/acl → iot-operator |
| shared-SQS | В кластере | shared-sqs | AWS SQS-совместимая очередь, endpoint https://qu.kube5s.ru |
| PostgreSQL 17 | Managed (оператор) | dc5db45d-... | per-tenant DB, тот же инстанс что и SQS billing |
| cert-manager | В кластере | cert-manager | TLS сертификаты для iot.kube5s.ru |
| nginx-ingress | В кластере | ingress | WSS/HTTPS проксирование |
### Секреты в namespace sless
| Secret | Ключи | Источник |
|--------|-------|----------|
| iot-sqs-credentials | SQS_ENDPOINT, SQS_ACCESS_KEY, SQS_SECRET_KEY | shared-SQS tenant iot-service |
| iot-postgres-secret | POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB, IOT_PG_DSN | Managed PG |
| iot-bridge-credentials | MQTT_USERNAME, MQTT_PASSWORD | Для mqtt-bridge → EMQX |
### Docker образ (актуальный)
- `naeel/iot-operator:v0.2.0` (Docker Hub)
- Все 3 бинарника в одном образе
- `command: ["/iot-operator"]` или `["/mqtt-bridge"]` или `["/sqs-consumer"]`
- Базовый: `gcr.io/distroless/static:nonroot`
### Кластер
- Имя: `iot-naeel`
- API: `https://185.247.187.149:6443`
- Ingress IP: `185.247.187.151`
- DNS: `iot.kube5s.ru → 185.247.187.147`