From b24d10d156dc9128832fbac16bdb26a5d1c832a7 Mon Sep 17 00:00:00 2001 From: kappa Date: Wed, 15 Apr 2026 13:29:18 +0900 Subject: [PATCH] =?UTF-8?q?vault-mcp-server=20=EC=8B=A4=20=EC=95=84?= =?UTF-8?q?=ED=82=A4=ED=85=8D=EC=B2=98=20=EC=A0=95=EC=A0=95=20(=EC=A4=91?= =?UTF-8?q?=EB=B3=B5=20=EC=95=84=EB=8B=98,=20jp1=20=EB=8B=A8=EC=9D=BC=20?= =?UTF-8?q?=EC=9D=B8=EC=8A=A4=ED=84=B4=EC=8A=A4)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - infra/vault.md MCP 서버 섹션 전체 재작성: K3s Deployment 아니라 Pod 없는 리버스 프록시 파사드, 세 접근 경로 모두 jp1 Incus vault 컨테이너(10.253.101.58)로 수렴 - 과거 오류 정정 callout 추가: vault-active.vault.svc.cluster.local 경로 실존 안 함, hcv/mcp URL은 Vault UI로 307 (올바른 MCP 경로는 vault-mcp.inouter.com/mcp) - history/2026-04-15-vault-mcp-duplicate-investigation.md 인시던트 기록 근거: Heimdall 조사 (Outline 5b6ddffa) + kappa 로컬 확인 (jp1 systemd active + 활성 트래픽) --- ...04-15-vault-mcp-duplicate-investigation.md | 88 +++++++++++++++++++ infra/vault.md | 30 ++++++- 2 files changed, 117 insertions(+), 1 deletion(-) create mode 100644 history/2026-04-15-vault-mcp-duplicate-investigation.md diff --git a/history/2026-04-15-vault-mcp-duplicate-investigation.md b/history/2026-04-15-vault-mcp-duplicate-investigation.md new file mode 100644 index 0000000..078b351 --- /dev/null +++ b/history/2026-04-15-vault-mcp-duplicate-investigation.md @@ -0,0 +1,88 @@ +--- +title: vault-mcp-server 중복 배포 의혹 조사 — 실제 단일 인스턴스 +date: 2026-04-15 +tags: [history, investigation, vault, mcp, k3s, incus] +--- + +## 사건 발단 + +Graphify 초기 빌드(2026-04-15) 결과에서 `semantically_similar_to` 엣지로 아래 두 노드가 연결됨: + +- `MCP vault (10.253.101.58:8080)` — `dev/claude-code-setup.md` 출처 +- `vault-mcp-server v0.2.0 (Go, port 8080)` — `infra/vault.md` 출처 + +graphify는 "놀라운 연결(Surprising Connections)"로 제시했고, 두 판이 실제로 다른 시스템인지 같은 시스템의 두 기록인지 정합성 확인이 필요했음. + +## 조사 결과 — 중복 없음 + +실제 vault-mcp-server 프로세스는 **jp1 Incus `vault` 컨테이너 (10.253.101.58)** 단일 인스턴스만 존재. 접근 경로가 3개라서 문서상 두 시스템으로 보였을 뿐. + +### 실 아키텍처 + +``` + ┌──── hcv.inouter.com (Host) ──────────────> Traefik@K3s:443 ──> 10.253.101.58:8200 (Vault UI/API) + │ + 사용자 ───┼──── vault-mcp.inouter.com ────────────────> Traefik@K3s:443 ──> 10.253.101.58:8080 (Vault MCP) + │ + kappa ────┴──── http://10.253.101.58:8080/mcp ─────────────────────────────> 같은 프로세스 (Tailscale 직결) + + 10.253.101.58 = jp1 Incus `vault` 컨테이너 (Vault 본체 + vault-mcp-server + systemd) +``` + +### K3s `tools/vault-mcp` 의 정체 + +- ArgoCD 앱 `argocd/vault-mcp` Synced/Healthy 상태지만 +- 렌더링 리소스는 **Service 1개 + IngressRoute 2개** 뿐 (Deployment/Pod/StatefulSet/HPA 전무) +- Service selector 비어 있고 수동 EndpointSlice 가 10.253.101.58 로 고정 +- 즉 K3s는 **Pod 없는 리버스 프록시 파사드**. 실 처리는 Tailscale로 jp1 컨테이너까지 직접 전달 +- Helm chart: `gitea.inouter.com/kaffa/helm-charts charts/app` + `values/vault-mcp.yaml` (deployment 블록 없는 ingress-only 렌더링) + +### K3s에 Vault ns 자체가 없음 + +- `kubectl get ns | grep vault` → 없음 +- `vault-active.vault.svc.cluster.local:8200` 경로는 **존재하지 않는 경로** (이전 문서에 이 DNS 이름이 적혀 있었으나 오류) +- Vault 본체도 jp1 컨테이너 단일 운영 (`hcv.inouter.com/v1/sys/health` 200 active 확인) + +### 실 트래픽 + +24h Traefik 액세스 로그 집계: + +| Host | 총 요청 | 비고 | +|---|---|---| +| `vault-mcp.inouter.com` | 4 | 전부 조사 중 kappa가 쏜 curl | +| `hcv.inouter.com` (`/mcp*` 경로) | 1 | 내부 LAN HEAD 307 (UI 리다이렉트) | + +**실 운영 트래픽 0건.** kappa의 Claude Code는 `http://10.253.101.58:8080/mcp` (Tailscale)로 직접 호출 → Traefik 거치지 않음 → K3s 로그에 흔적 없음. + +- BunnyCDN / Cloudflare 비경유 (응답 헤더에 `cf-ray`, `server: cloudflare`, BunnyCDN 시그니처 없음) +- Traefik wildcard cert `wildcard-inouter-tls` 로 직접 TLS 종단 +- K3s MetalLB 192.168.9.53 (내부 LAN/Tailscale 전용) + +## 확정된 사실 + +1. **중복 인스턴스 아님.** 하나의 vault-mcp-server 프로세스 + 세 접근 경로 +2. **`hcv.inouter.com/mcp` 는 MCP 엔드포인트가 아님.** Vault가 `/mcp` → `/ui/` 307 리다이렉트. MCP 외부 접근은 `vault-mcp.inouter.com/mcp` +3. **kappa 현행 사용 경로**: `http://10.253.101.58:8080/mcp` (Tailscale 직결, 평문 HTTP) +4. **외부 공개 경로는 현재 실 사용 0건** — CDN 비경유, LAN 전용 + +## 조치 + +- Obsidian `infra/vault.md` MCP 서버 섹션 전체 재작성 — 실 아키텍처 반영, 잘못된 문서화 정정 callout 추가 +- Graphify 그래프는 다음 `graphify update` 시 정정된 Obsidian 원문 기반으로 재추출 예정 (노드 관계 정리) + +## 선택적 후속 과제 + +- **kappa MCP URL 전환 검토**: `http://10.253.101.58:8080/mcp` → `https://vault-mcp.inouter.com/mcp`. Traefik TLS + wildcard cert 혜택. 단, Tailscale 종속성 유지라 큰 이득 아님 +- **K3s 파사드 유지 여부**: 24h 트래픽 0건 + CDN 비경유인데 K3s 파사드를 유지할 실용 이유가 크지 않음. 외부 공개 의도가 없다면 ArgoCD 앱 제거 검토. 외부 공개할 거면 Cloudflare Zone + DNAT 추가 +- **jp1 systemd 로그 접근 권한**: Heimdall 컨테이너에서 jp1 호스트 SSH 거부됨 (공개키 미등록). heimdall 라인에서 vault-mcp 상태를 직접 확인하려면 키 등록 필요 + +## 교훈 + +- **Graphify `semantically_similar_to` 는 "같은 실체"가 아니라 "비슷한 것"만 뜻함.** 동일 프로세스에 대한 서로 다른 관점(접근 경로별 명명)이 두 노드로 분리되어 기록되어 있었음. 향후 정본 작성 시 접근 경로가 여러 개면 같은 노드 하위에 묶는 서술이 그래프 정합성에 유리 +- **ArgoCD Healthy 상태만 보고 "Deployment 돌아가는 중"이라 추정하지 말 것.** `kubectl get all -n ` 로 실 리소스 타입 확인 필수. Pod 없는 파사드를 Deployment로 문서화한 게 이번 오류의 원인 +- **문서에 DNS/FQDN 적을 때 실제 존재하는지 검증하는 습관.** `vault-active.vault.svc.cluster.local:8200`은 실존하지 않는 경로였으나 문서에 들어가 있었음 + +## 참조 + +- Outline 조사 리포트: `vault-mcp-server 중복 배포 조사 — 2026-04-15` (id `5b6ddffa-de07-401e-8a3b-3edfcd68a1a9`) +- 정정된 정본: `infra/vault.md` MCP 서버 섹션 diff --git a/infra/vault.md b/infra/vault.md index 7af29b2..03c41ef 100644 --- a/infra/vault.md +++ b/infra/vault.md @@ -76,7 +76,35 @@ CA 등록 완료 서버: ## MCP 서버 -vault-mcp-server v0.2.0 (hashicorp/vault-mcp-server:0.2.0 Docker 이미지). K3s vault namespace에 Deployment로 배포. streamable-http 모드, 엔드포인트: https://hcv.inouter.com/mcp. 내부 통신: vault-active.vault.svc.cluster.local:8200. token은 Secret vault-mcp-token에 저장. Claude Code MCP 설정: type http, url https://hcv.inouter.com/mcp. K3s Ingress vault-mcp가 /mcp 경로를 vault-mcp-server Service(8080)로 라우팅. 로컬 바이너리도 /usr/local/bin/vault-mcp-server에 설치됨. +### 실 배포 (2026-04-15 정정) + +vault-mcp-server v0.2.0 은 **jp1 Incus `vault` 컨테이너 (10.253.101.58) 단일 인스턴스**. systemd 유닛 `vault-mcp-server.service`로 streamable-http 모드 가동 (`--transport-host=0.0.0.0 --transport-port=8080 --mcp-endpoint=/mcp`). 같은 컨테이너에 HashiCorp Vault 본체(포트 8200)도 동일 프로세스 공간에 존재 → vault 백엔드는 `http://127.0.0.1:8200`. + +> [!warning] 과거 문서 오류 정정 (2026-04-15) +> 이전 기록에 "K3s vault namespace Deployment 배포", "vault-active.vault.svc.cluster.local:8200" 이라 적혀 있었으나 실제와 다름. K3s 안에는 vault 파드/Deployment 없음. 상세: `history/2026-04-15-vault-mcp-duplicate-investigation.md` + +### 접근 경로 (3가지, 모두 같은 jp1 프로세스로 수렴) + +``` +hcv.inouter.com → Traefik@K3s:443 → 10.253.101.58:8200 (Vault UI/API) +vault-mcp.inouter.com → Traefik@K3s:443 → 10.253.101.58:8080 (MCP) +http://10.253.101.58:8080/mcp (Tailscale 직결, kappa Claude 현행) +``` + +K3s `tools` 네임스페이스의 `vault-mcp` 는 **Pod 없는 리버스 프록시 파사드**: Service(selector 비움) + 수동 EndpointSlice가 10.253.101.58 로 고정 + IngressRoute 2개(hcv, vault-mcp). ArgoCD 앱 `argocd/vault-mcp`, Helm chart `kaffa/helm-charts charts/app` + `values/vault-mcp.yaml` (deployment 없는 ingress-only 렌더링). + +### 주의 + +- **`hcv.inouter.com/mcp` 는 MCP 엔드포인트 아님** — Vault가 /mcp 경로를 UI(/ui/)로 307 리다이렉트. 외부 MCP hostname 필요하면 `vault-mcp.inouter.com/mcp` 사용. +- 외부 공개 경로는 BunnyCDN/Cloudflare 비경유 (Traefik wildcard cert 직접 TLS 종단). 내부 LAN/Tailscale 전용. +- kappa Claude MCP는 현재 `http://10.253.101.58:8080/mcp` (Tailscale 암호화 의존). 장기적으로 `https://vault-mcp.inouter.com/mcp` 로 이전 검토 가능 (Traefik TLS + wildcard cert 혜택). + +### 재배포 자료 + +- Helm chart: `gitea.inouter.com/kaffa/helm-charts.git charts/app` +- values: `kaffa/helm-charts values/vault-mcp.yaml` +- jp1 컨테이너 내부 바이너리: `/usr/local/bin/vault-mcp-server` +- systemd: `/etc/systemd/system/vault-mcp-server.service` ## 관련 서비스