docs: полная документация v0.2.3 — архитектура, API, деплой, тестирование
Новые файлы: - doc/architecture/current-v0.2.3.md — актуальная архитектура - doc/api/endpoints-v0.2.3.md — полная документация REST API - doc/deployment-v0.2.3.md — инструкция деплоя v0.2.3 - doc/run-and-test.md — руководство по запуску и E2E тесту Обновлено: - doc/progress.md — секция документации - doc/thinking/2026-04-12.md — лог мышления
This commit is contained in:
Naeel
@@ -0,0 +1,249 @@
|
||||
# IoT — Руководство по запуску и тестированию (v0.2.3)
|
||||
|
||||
> Дата: 2026-04-12
|
||||
> Кластер: iot-naeel, namespace: sless
|
||||
> Образ: naeel/iot-operator:v0.2.3
|
||||
|
||||
---
|
||||
|
||||
## Содержание
|
||||
|
||||
1. [Предварительные требования](#предварительные-требования)
|
||||
2. [Сборка и публикация образа](#сборка-и-публикация-образа)
|
||||
3. [Деплой в кластер](#деплой-в-кластер)
|
||||
4. [E2E тест: полный путь данных](#e2e-тест-полный-путь-данных)
|
||||
5. [Проверка компонентов](#проверка-компонентов)
|
||||
6. [Отладка](#отладка)
|
||||
|
||||
---
|
||||
|
||||
## Предварительные требования
|
||||
|
||||
- kubectl с kubeconfig для кластера iot-naeel (185.247.187.149:6443)
|
||||
- Docker для сборки образа
|
||||
- mosquitto-clients для MQTT тестов (apt install mosquitto-clients)
|
||||
- curl для REST API
|
||||
|
||||
---
|
||||
|
||||
## Сборка и публикация образа
|
||||
|
||||
```bash
|
||||
cd /home/naeel/terra/IoT
|
||||
|
||||
# Сборка multi-binary Docker образа
|
||||
docker build -t naeel/iot-operator:v0.2.3 .
|
||||
|
||||
# Push на Docker Hub
|
||||
docker push naeel/iot-operator:v0.2.3
|
||||
```
|
||||
|
||||
Dockerfile собирает 3 бинарника: /iot-operator, /mqtt-bridge, /sqs-consumer.
|
||||
|
||||
---
|
||||
|
||||
## Деплой в кластер
|
||||
|
||||
```bash
|
||||
# Применить CRD
|
||||
kubectl apply -f config/crd/bases/iot.kube5s.ru_iotdevices.yaml
|
||||
|
||||
# Деплой всех компонентов
|
||||
kubectl apply -f deployments/k8s/emqx.yaml
|
||||
kubectl apply -f deployments/k8s/iot-operator.yaml
|
||||
kubectl apply -f deployments/k8s/iot-mqtt-bridge.yaml
|
||||
kubectl apply -f deployments/k8s/iot-sqs-consumer.yaml
|
||||
kubectl apply -f deployments/k8s/iot-postgres.yaml
|
||||
|
||||
# Проверка
|
||||
kubectl get pods -n sless
|
||||
# Ожидаем: emqx, iot-operator, iot-mqtt-bridge, iot-sqs-consumer — все Running
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## E2E тест: полный путь данных
|
||||
|
||||
Полный тест проверяет цепочку: REST API → CRD → Secret → MQTT → SQS → Postgres → Telemetry API.
|
||||
|
||||
### Шаг 1: Создать устройство через API
|
||||
|
||||
```bash
|
||||
curl -X POST https://iot.kube5s.ru/v1/namespaces/sless/iot/devices \
|
||||
-H "Authorization: Bearer test-token" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"name":"e2e-test-01","device_id":"e2e-test-01","enabled":true}'
|
||||
```
|
||||
|
||||
Ответ: 201 Created с данными устройства.
|
||||
|
||||
### Шаг 2: Получить MQTT credentials
|
||||
|
||||
```bash
|
||||
curl -s https://iot.kube5s.ru/v1/namespaces/sless/iot/devices/e2e-test-01 \
|
||||
-H "Authorization: Bearer test-token" \
|
||||
| jq '{mqtt_username, mqtt_password, phase}'
|
||||
```
|
||||
|
||||
Ожидаем: phase=Active, mqtt_username="sless_e2e-test-01", mqtt_password=hex(64).
|
||||
|
||||
> Если phase=Pending — подождать 1-2 секунды, контроллер ещё создаёт Secret.
|
||||
|
||||
### Шаг 3: Отправить телеметрию через MQTT
|
||||
|
||||
```bash
|
||||
# Вставить реальный пароль из Шага 2
|
||||
MQTT_USER="sless_e2e-test-01"
|
||||
MQTT_PASS="<mqtt_password из шага 2>"
|
||||
|
||||
# Через WebSocket (через Ingress)
|
||||
mosquitto_pub \
|
||||
-h iot.kube5s.ru \
|
||||
-p 443 \
|
||||
--capath /etc/ssl/certs \
|
||||
-u "$MQTT_USER" \
|
||||
-P "$MQTT_PASS" \
|
||||
-t "sless/telemetry/e2e-test-01" \
|
||||
-m '{"temperature": 22.5, "humidity": 65}' \
|
||||
--protocol-version mqttv5
|
||||
|
||||
# ИЛИ через kubectl port-forward (MQTT напрямую)
|
||||
kubectl port-forward svc/emqx -n sless 1883:1883 &
|
||||
mosquitto_pub \
|
||||
-h localhost \
|
||||
-p 1883 \
|
||||
-u "$MQTT_USER" \
|
||||
-P "$MQTT_PASS" \
|
||||
-t "sless/telemetry/e2e-test-01" \
|
||||
-m '{"temperature": 22.5, "humidity": 65}'
|
||||
```
|
||||
|
||||
### Шаг 4: Проверить что телеметрия дошла до Postgres
|
||||
|
||||
Подождать 5-10 секунд (SQS long polling + обработка).
|
||||
|
||||
```bash
|
||||
curl -s "https://iot.kube5s.ru/v1/namespaces/sless/iot/telemetry?device=e2e-test-01&limit=10" \
|
||||
-H "Authorization: Bearer test-token" \
|
||||
| jq '.'
|
||||
```
|
||||
|
||||
Ожидаем: count >= 1, items содержит запись с payload {"temperature": 22.5, "humidity": 65}.
|
||||
|
||||
### Шаг 5: Очистка
|
||||
|
||||
```bash
|
||||
curl -X DELETE https://iot.kube5s.ru/v1/namespaces/sless/iot/devices/e2e-test-01 \
|
||||
-H "Authorization: Bearer test-token"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Проверка компонентов
|
||||
|
||||
### Поды
|
||||
|
||||
```bash
|
||||
kubectl get pods -n sless -l 'app in (iot-operator,iot-mqtt-bridge,iot-sqs-consumer,emqx)'
|
||||
```
|
||||
|
||||
### Логи
|
||||
|
||||
```bash
|
||||
# Operator (controller + API)
|
||||
kubectl logs -n sless deployment/iot-operator --tail=50
|
||||
|
||||
# MQTT Bridge
|
||||
kubectl logs -n sless deployment/iot-mqtt-bridge --tail=50
|
||||
|
||||
# SQS Consumer
|
||||
kubectl logs -n sless deployment/iot-sqs-consumer --tail=50
|
||||
|
||||
# EMQX
|
||||
kubectl logs -n sless deployment/emqx --tail=50
|
||||
```
|
||||
|
||||
### CRD ресурсы
|
||||
|
||||
```bash
|
||||
# Список IoTDevice
|
||||
kubectl get iotdevices -n sless
|
||||
|
||||
# Детали
|
||||
kubectl describe iotdevice e2e-test-01 -n sless
|
||||
|
||||
# Секреты
|
||||
kubectl get secret -n sless -l app.kubernetes.io/managed-by=iot-operator
|
||||
```
|
||||
|
||||
### EMQX Dashboard (отладка)
|
||||
|
||||
```bash
|
||||
kubectl port-forward svc/emqx -n sless 18083:18083
|
||||
# Открыть http://localhost:18083
|
||||
# Default: admin / public
|
||||
```
|
||||
|
||||
### SQS очередь
|
||||
|
||||
```bash
|
||||
# Через admin stats endpoint
|
||||
curl -s https://iot.kube5s.ru/iot-admin/stats \
|
||||
-H "Authorization: Bearer <ADMIN_STATS_TOKEN>" \
|
||||
| jq '.sqs'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Отладка
|
||||
|
||||
### Устройство не подключается по MQTT
|
||||
|
||||
1. Проверить phase: `kubectl get iotdevice {name} -n {ns} -o jsonpath='{.status.phase}'`
|
||||
— Должно быть `Active`
|
||||
2. Проверить Secret: `kubectl get secret iot-{deviceId} -n {ns}`
|
||||
3. Проверить EMQX logs: `kubectl logs -n sless deployment/emqx | grep "auth"`
|
||||
4. Ручная проверка auth:
|
||||
```bash
|
||||
kubectl port-forward svc/iot-operator -n sless 9090:9090
|
||||
curl -X POST http://localhost:9090/internal/mqtt/auth \
|
||||
-d '{"username":"sless_sensor-01","password":"...","clientid":"test"}'
|
||||
```
|
||||
|
||||
### Телеметрия не появляется в API
|
||||
|
||||
1. Bridge подключён? `kubectl logs -n sless deployment/iot-mqtt-bridge | tail -20`
|
||||
2. SQS получает? `curl /iot-admin/stats` → sqs.approximate_messages
|
||||
3. Consumer обрабатывает? `kubectl logs -n sless deployment/iot-sqs-consumer | tail -20`
|
||||
4. Postgres доступен? Проверить логи consumer на ошибки подключения
|
||||
|
||||
### Bridge не подключается к MQTT
|
||||
|
||||
1. Проверить Secret iot-bridge-credentials:
|
||||
`kubectl get secret iot-bridge-credentials -n sless -o jsonpath='{.data.MQTT_USERNAME}' | base64 -d`
|
||||
2. Проверить env в Bridge pod:
|
||||
`kubectl exec -n sless deployment/iot-mqtt-bridge -- env | grep MQTT`
|
||||
|
||||
---
|
||||
|
||||
## IoT Console (Web UI)
|
||||
|
||||
Открыть `https://iot.kube5s.ru/console` в браузере.
|
||||
|
||||
Функции:
|
||||
- CRUD устройств через REST API
|
||||
- Встроенный MQTT WebSocket клиент (wss://iot.kube5s.ru/mqtt)
|
||||
- Real-time отображение входящей телеметрии
|
||||
- Просмотр истории из Postgres
|
||||
|
||||
---
|
||||
|
||||
## IoT Admin Panel
|
||||
|
||||
Открыть `https://iot.kube5s.ru/iot-admin` в браузере.
|
||||
|
||||
Функции:
|
||||
- Статистика по PostgreSQL (количество записей по тенантам)
|
||||
- SQS: approximate message count
|
||||
- Статус подов bridge и consumer
|
||||
- Автообновление каждые 30 секунд
|
||||
Reference in New Issue
Block a user