diff --git a/history/2026-05-29-termix-upgrade-release-2.3.1.md b/history/2026-05-29-termix-upgrade-release-2.3.1.md
new file mode 100644
index 0000000..3507e63
--- /dev/null
+++ b/history/2026-05-29-termix-upgrade-release-2.3.1.md
@@ -0,0 +1,46 @@
+---
+date: 2026-05-29
+topic: termix `:latest` → `release-2.3.1` 업그레이드 + image.tag 명시 고정
+areas: [services, infra/k3s]
+tags: [history, termix, k3s, argocd, helm, image-tag]
+---
+
+# 2026-05-29 / termix release-2.3.1 업그레이드
+
+## 변경 요약
+
+| 항목 | Before | After |
+|---|---|---|
+| Image tag | `:latest` (digest `577c0e`, 3d8h 전 pull) | **`release-2.3.1`** (digest `8db77c`) |
+| Chart 버전 | 0.1.2 | **0.1.4** |
+| `image.tag` 관리 | 미명시 (`:latest` 부유) | **chart values에 명시 고정** |
+| ArgoCD 상태 | Synced/Healthy (구버전) | Synced/Healthy (신버전) |
+| Pod | Running RESTARTS=0 | Running RESTARTS=0 |
+| 헬스체크 | — | https://termix.inouter.com/ HTTP 200 |
+
+배포 chart commit: `5d3b027`.
+
+## 트러블슈팅 — ImagePullBackOff (1차 실패)
+
+처음 시도 시 `image.tag: release-2.3.1-tag`로 작성 → `ImagePullBackOff`.
+
+원인: GitHub release tag 이름과 Docker registry tag 이름이 다름.
+- GitHub release: `release-2.3.1-tag`
+- Docker registry tag: `release-2.3.1` (suffix `-tag` 없음)
+
+수정: chart values의 `image.tag`에서 `-tag` suffix 제거 → 정상 pull.
+
+> **교훈**: 새 서비스의 image tag를 처음 명시 고정할 때는 release 페이지 이름이 아니라 **registry의 실제 tag**를 확인할 것 (`crane ls <repo>` 또는 registry UI).
+
+## 후속 / 영향
+
+- `:latest` 부유가 사라져서 이제 chart values 변경 없이는 이미지가 바뀌지 않음. 이전엔 노드 재시작/pod 재기동 시 무의식적으로 새 latest를 pull할 수 있었음.
+- 다음 termix 업그레이드 시 절차: GitHub release 확인 → registry tag 이름 검증 → chart `image.tag` 갱신 → chart minor bump → ArgoCD sync.
+
+## 검증
+
+- `kubectl get pod -n termix`: Running, RESTARTS=0
+- ArgoCD: Synced, Healthy
+- `curl -sI https://termix.inouter.com/`: HTTP/2 200
+
+수행: [[../ops-agents/heimdall/_index|헤임달]] (소요 ~6분)