diff --git a/infra/k3s-migration.md b/infra/k3s-migration.md
new file mode 100644
index 0000000..1c00120
--- /dev/null
+++ b/infra/k3s-migration.md
@@ -0,0 +1,103 @@
+---
+title: K3s PostgreSQL 백엔드 이전
+updated: 2026-03-24
+tags: [k3s, migration, postgresql, supabase]
+---
+
+## 개요
+
+기존 K3s 클러스터(외부 etcd)에서 Supabase PostgreSQL 백엔드로 전환하는 프로젝트.
+
+## 기존 클러스터
+
+| 항목 | 값 |
+|------|-----|
+| 노드 | hp2(server), kr1(server), kr2(분리됨) |
+| 데이터스토어 | 외부 etcd (Incus 컨테이너 3개) |
+| etcd 엔드포인트 | http://192.168.9.214:2379, http://192.168.9.135:2379, http://192.168.9.134:2379 |
+| 네트워크 | LAN 192.168.9.x, flannel vxlan |
+| Pod CIDR | 10.42.0.0/16 |
+| Service CIDR | 10.43.0.0/16 |
+| tls-san | k3s.inouter.com |
+| 리소스 사용 | CPU ~3코어, 메모리 ~45GB |
+
+## 새 클러스터 (진행 중)
+
+| 항목 | 값 |
+|------|-----|
+| 컨트롤 플레인 | kr2 (192.168.9.135) |
+| 데이터스토어 | Supabase PostgreSQL (싱가포르) |
+| Pooler | Session mode, port 5432 |
+| DB 호스트 | aws-1-ap-southeast-1.pooler.supabase.com |
+| DB 유저 | postgres.bahmyfgldxmtgvsufmwf |
+| 시크릿 | Vault `secret/cloud/supabase` |
+| 커넥션 제한 | pool_max_conns=5&pool_min_conns=1 |
+| max_connections | 60 (무료 티어) |
+| 현재 사용 | ~18 커넥션 |
+| 네트워크 | LAN 192.168.9.x, flannel vxlan (기존과 동일) |
+| Pod CIDR | 10.42.0.0/16 |
+| Service CIDR | 10.43.0.0/16 |
+| tls-san | k3s.inouter.com, 192.168.9.135, 100.119.109.41 |
+
+## 목표 구성
+
+```
+kr2: k3s server  (컨트롤 플레인 + 워커)  192.168.9.135
+kr1: k3s server  (컨트롤 플레인 + 워커)  192.168.9.214
+hp2: k3s agent   (워커만)                192.168.9.134
+```
+
+- server 2대 → 자동 HA (한쪽 죽어도 API 서버 유지)
+- agent는 DB 커넥션 불필요 → 커넥션 절약
+- 예상 커넥션: ~36/60
+
+## 장애 시나리오
+
+| 장애 | 영향 | 복구 |
+|------|------|------|
+| server 1대 죽음 | 서비스 무중단, 나머지 server가 API 유지 | 자동 |
+| agent 죽음 | Pod 재스케줄 | 자동 |
+| server 2대 동시 | 기존 Pod 유지, 변경 불가 | 아무 노드에서 k3s server 시작 |
+| Supabase DB 장애 | 기존 Pod 유지, 변경 불가 | Supabase 복구 시 자동 |
+
+## Supabase 제약사항
+
+- **Transaction mode pooler(6543) 사용 불가** — K3s Kine이 prepared statements 사용, transaction pooler와 충돌
+- **Session mode pooler(5432) 필수** — pool_max_conns로 커넥션 수 제한
+- 무료 티어 max_connections=60, Pro($25/월)도 Micro는 동일
+- Small($65/월 총)로 올리면 90개
+- 싱가포르 리전 → 서울에서 ~70ms 레이턴시 (허용 범위)
+
+## 마이그레이션 순서
+
+### Phase 0: 새 클러스터 인프라 구성 ⬜
+1. Traefik 설치 (Helm, DaemonSet + Gateway API)
+2. APISIX 설치
+3. Longhorn 설치
+4. cert-manager 설치
+
+### Phase 1: kr1 이전 ⬜
+1. 기존 클러스터에서 kr1 drain
+2. kr1 기존 K3s 중지
+3. kr1을 새 클러스터에 server로 합류
+
+### Phase 2: 서비스 이전 ⬜
+1. ArgoCD 설치 + Git 저장소 연결
+2. 앱 순차 동기화
+3. PV 데이터 마이그레이션 (Longhorn)
+4. DNS/트래픽 전환
+
+### Phase 3: hp2 이전 ⬜
+1. 기존 클러스터 완전 종료
+2. hp2에서 기존 K3s 중지
+3. hp2를 새 클러스터에 agent로 합류
+
+### Phase 4: 정리 ⬜
+1. 기존 etcd Incus 컨테이너 폐기 (kr1, kr2, hp2)
+2. 기존 K3s server.bak 삭제
+3. 모니터링/백업 체계 재구성
+
+## 관련 문서
+
+- [[infra-hosts]] — 서버 목록
+- [[backup]] — 백업 체계 (etcd → PostgreSQL 전환 후 변경 필요)