architecture tailscale mesh

아키텍처 — Tailscale Mesh VPN

Tailscale은 Hub EKS와 Factory Spoke K3s API를 연결하는 제어 플레인 전용망이다. MQTT telemetry와 Dashboard 사용자 접근 경로와 분리한다.

---

역할

Hub ArgoCD (Control / Management VPC, EKS)
  -> Tailscale Operator / Connector
  -> Tailnet
  -> factory-a K3s API
  -> factory-b K3s API
  -> factory-c K3s API

Tailscale을 사용하는 작업은 아래로 제한한다.

사용	설명
Spoke 등록	Hub에서 factory K3s API에 접근할 cluster Secret 생성
GitOps sync	Hub ArgoCD가 factory별 Application을 sync
운영 진단	제한된 운영자가 K3s API 또는 SSH reachability 확인
Hub rebuild 복구	Tailscale egress Service와 ArgoCD cluster Secret 재생성

Dashboard Web/API 사용자는 Tailscale을 사용하지 않는다. Dashboard는 Data / Dashboard VPC의 CloudFront, Cognito, ALB, ECS Backend를 통해 접근한다.

---

MQTT mTLS 경로와 분리

데이터 수집은 Tailscale과 무관하다.

factory-a/b/c edge-iot-publisher
  -> MQTT mTLS over Public Internet
  -> AWS IoT Core ATS endpoint
  -> IoT Rule / Lambda data processor
  -> DynamoDB / S3

이 경로는 X.509 인증서와 IoT Policy로 보호한다. Tailscale ACL이나 Tailnet IP는 telemetry 수집 권한의 기준이 아니다.

---

연결 구조

Control / Management VPC
  EKS Hub
    tailscale namespace
      - tailscale-operator
      - Connector / proxy resources
    argocd namespace
      - ArgoCD cluster Secret
      - ApplicationSet

Tailnet
  - factory-a master device (tag:aegis-spoke-prod, tag:factory-a)
  - factory-b VM device (tag:aegis-spoke-testbed, tag:factory-b)
  - factory-c VM device (tag:aegis-spoke-testbed, tag:factory-c)

ArgoCD cluster Secret에는 Spoke K3s API endpoint와 credential이 들어간다. Endpoint는 재등록 시점의 Tailnet address나 Tailscale egress Service를 통해 구성되므로, 위키에는 고정 Tailnet IP를 운영 기준으로 박아두지 않는다.

---

Spoke 등록

Hub 인프라와 Hub 내부 플랫폼을 올린 뒤 factory별 등록 스크립트를 실행한다.

scripts/build/register-spoke-factory-a.sh [MFA_OTP]
scripts/build/register-spoke-factory-b.sh [MFA_OTP]
scripts/build/register-spoke-factory-c.sh [MFA_OTP]

등록 스크립트의 책임은 아래와 같다.

1. 대상 factory Tailnet reachability 확인
2. Hub Tailscale egress Service 복구
3. ArgoCD cluster Secret 생성/갱신
4. factory별 ApplicationSet 연결 확인
5. IoT Thing/Policy/Secret은 건드리지 않음

Spoke MQTT 인증서와 IoT Secret은 데이터 플레인 자격 증명이다. Spoke 등록 스크립트가 이를 재발급하거나 변경하지 않는다.

---

Hub rebuild 후 복구

Hub EKS를 destroy/rebuild하면 EKS 내부 Tailscale Operator, egress Service, ArgoCD cluster Secret이 사라진다. Factory K3s runtime과 MQTT 데이터 송신은 계속 동작할 수 있지만, Hub ArgoCD의 sync는 복구 전까지 중단된다.

복구 순서:

1. build-hub.sh
   -> Control / Management VPC
   -> EKS Hub
   -> ArgoCD / Grafana / LBC / Tailscale Operator

2. register-spoke-factory-a/b/c.sh
   -> Tailscale egress
   -> ArgoCD cluster Secret
   -> ApplicationSet sync 확인

3. 필요 시 connect-hub-tailscale-ui.sh
   -> ArgoCD/Grafana Tailscale UI Service
   -> 선택 기능. Admin UI HTTPS를 쓰면 필수 아님

---

Tailnet IP 공개 기준

Tailnet IPv4는 device 재생성, operator 재설치, tagged device 교체에 따라 바뀔 수 있다. 따라서 위키의 아키텍처 문서에는 특정 100.x.x.x 값을 운영 기준으로 공개하지 않는다.

문서화 기준:

항목	공개 여부	이유
factory 이름	공개	구조 이해에 필요
Tailnet tag	공개	ACL 의도와 역할 설명에 필요
고정 Tailnet IP	일반화	변동 가능하고 운영 절차는 스크립트가 조회/갱신
OAuth client secret / auth key	비공개	재발급 가능한 secret
kubeconfig credential	비공개	cluster 접근 권한

Tailnet IP가 필요한 운영 절차에서는 Tailscale Admin Console, tailscale status, 또는 등록 스크립트의 출력으로 그 시점의 값을 확인한다.

---

Dashboard 접근 비의존

Dashboard 사용자 흐름은 아래 경로다.

Browser
  -> Route 53
  -> CloudFront (+ WAF/IP 제한은 선택·계획 구성)
  -> Cognito Hosted UI
  -> ALB HTTPS api.<도메인>
  -> ECS Fargate Backend
  -> DynamoDB / S3 / RDS / Redis

이 경로에는 Tailnet, K3s API, Hub ArgoCD가 없다. Dashboard Backend가 필요한 factory 상태는 data processor와 collectors가 만든 read model에서 읽는다.

---

Active / Optional / Retired

상태	구성
Active	Tailscale Operator, factory-a/b/c tagged device, factory별 egress/cluster Secret 등록, Hub ArgoCD sync
Optional	ArgoCD/Grafana Tailscale UI Service, 운영자 SSH 진단
Not used for	MQTT telemetry, Dashboard user access, Cognito auth, WebSocket push

---

관련 문서

• 시스템 아키텍처
• 제어 플레인 & 데이터 플레인
• Hub EKS 네임스페이스
• 하드웨어 배치 & 인프라 구성
• 운영 — Hub 재시작