Naeel
907aaad100
Новые файлы: - 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 — лог мышления
250 lines
7.4 KiB
Markdown
250 lines
7.4 KiB
Markdown
# 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 секунд
|