adr persistent mqtt

ADR - IoT Fleet 연결성: Persistent MQTT

메타데이터	값
상태	accepted
결정일	2026-06-09
현재 유효 여부	유효
구현 근거	apps/edge-iot-publisher(paho-mqtt persistent connection), charts/aegis-spoke
검증 근거	factory-a/b/c publisher rollout Healthy, IoT Fleet Indexing connected=true

---

결정

edge-iot-publisher를 publish할 때마다 연결을 열고 닫던 short-lived 방식에서 프로세스 생명주기 동안 MQTT 연결을 유지하는 persistent 방식으로 변경한다.

• paho-mqtt 사용, publisher 생명주기 동안 연결 유지
• QoS 1 publish ack가 완료된 경우에만 outbox JSON 파일 삭제
• publish 실패·ack timeout·reconnect 실패 시 outbox 파일은 유지(유실 방지)
• loop 중 연결이 끊기면 reconnect/backoff 후 재시도
• SIGTERM/SIGINT 시 graceful disconnect
• client ID는 chart 기본값 AEGIS-IoTThing-<factory-id>를 유지

이유

AWS IoT Fleet Indexing의 connected는 데이터 유입 여부가 아니라 현재 MQTT 세션 유지 여부를 나타낸다. short-lived publish 방식에서는 데이터가 정상 유입돼도 조회 시점에는 disconnected로 표시되는 것이 정상이었다.

운영·발표에서 AWS IoT 콘솔의 connectivity status를 공장 연결 상태 지표로 직접 보여주려면, Thing 이름과 같은 client ID로 MQTT 세션을 유지하는 방식이 더 적합하다.

영향

• AWS IoT 콘솔/CLI에서 factory-a/b/c Thing connectivity를 운영 지표로 사용할 수 있다.
• Hub-only rebuild 중 Hub를 내려도 Spoke publisher가 살아 있으면 IoT 연결과 데이터 유입이 유지된다.
• Pod failover/rollout 시 짧은 disconnect/connect 이벤트가 발생할 수 있다.

운영 제약

• 같은 client ID를 쓰는 Pod가 동시에 뜨면 연결 churn이 발생하므로 publisher Deployment는 replicaCount=1, strategy=Recreate를 유지한다.
• legacy local dummy publisher와 K3s edge-iot-publisher를 동시에 실행하면 같은 client ID 충돌이 생긴다(동시 실행 금지).
• Spoke K3s의 ECR pull secret 만료 시 새 image rollout이 403 Forbidden으로 실패할 수 있으므로 pull secret 갱신 절차를 운영에 포함한다.

검증

항목	결과
publisher unit test	12 tests OK
factory-a/b/c ArgoCD	Synced / Healthy
publisher Deployment	replicas=1, strategy=Recreate, running pod=1
IoT Fleet Indexing	factory-a/b/c connected=true, disconnectReason=NONE

인증서 재발급, IoT Thing/Certificate/Policy 변경은 하지 않았다.

관련 문서

• Edge IoT Publisher
• factory-b/c 테스트베드
• Hub 재시작
• ADR 인덱스