vault-mcp-server 실 아키텍처 정정 (중복 아님, jp1 단일 인스턴스)
- 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 + 활성 트래픽)
This commit is contained in:
kappa
88
history/2026-04-15-vault-mcp-duplicate-investigation.md
Normal file
88
history/2026-04-15-vault-mcp-duplicate-investigation.md
Normal file
@@ -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 <ns>` 로 실 리소스 타입 확인 필수. 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 서버 섹션
|
||||
@@ -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`
|
||||
|
||||
## 관련 서비스
|
||||
|
||||
|
||||
Reference in New Issue
Block a user