jarca-ledger-mcp/deploy/k8s/README.md

k3s 배포

base/는 MCP와 Dashboard를 같은 SQLite PVC에 두는 단일 Deployment 구조입니다. Dashboard 인증 secret은 base manifest에 실제 값으로 저장하지 않습니다.

사전 준비

namespace와 승인된 secret manager 절차를 준비합니다.

kubectl apply -f deploy/k8s/base/namespace.yaml

jarca-ledger namespace의 Dashboard secret에는 다음 key만 둡니다.

• admin-id
• admin-password
• signing-secret (UTF-8 32 byte 이상의 독립 random value)

Registry credential은 imagePullSecrets로만 사용합니다. 실제 secret 값, token, cookie를 Git, manifest, command history 또는 문서에 기록하지 마세요.

배포

검증된 release digest를 외부 environment overlay에서 고정하고 적용합니다.

kubectl apply -k environments/production/jarca-ledger
kubectl -n jarca-ledger rollout status deployment/jarca-ledger
kubectl -n jarca-ledger get pods,svc,pvc

MCP와 Dashboard container 및 init container는 동일 digest를 사용해야 합니다. SQLite를 공유하므로 replicas는 1, update 전략은 Recreate입니다.

Dashboard 인증 운영

Frontend container에만 다음 환경변수를 Kubernetes Secret 또는 동등한 secret store에서 주입합니다.

• JARCA_DASHBOARD_ADMIN_ID
• JARCA_DASHBOARD_ADMIN_PASSWORD
• JARCA_DASHBOARD_SIGNING_SECRET

환경변수가 누락·빈 값·read error·짧은 secret이면 Dashboard는 fail-closed합니다. token subject는 고정 비민감 role dashboard-admin이며 server-only configured credential binding을 사용합니다. DB-backed session/token registry와 per-token revocation은 없습니다. Password, signing secret 또는 admin ID rotation은 기존 token을 전체 무효화합니다.

공개 Dashboard origin에는 TLS가 필수입니다. Ingress 또는 reverse proxy는 Host, Origin, Referer, X-Forwarded-Proto: https를 보존해야 하며 FORWARDED_ALLOW_IPS는 실제 ingress-controller source IP/CIDR로 제한합니다. * 또는 불특정 network를 사용하지 마세요. Login과 /api/auth/logout은 same-origin HTTPS POST이고 /api/auth/cleanup GET은 same-origin HTTPS Referer를 검증합니다. Invalid cookie는 cleanup route의 matching Max-Age=0 deletion 뒤 unauthenticated page로 이동하고, explicit logout도 같은 deletion을 수행합니다. 인증 실패 지연은 rate limiting을 대체하지 않으므로 TLS ingress 경계에 별도 rate limit을 적용합니다.

Base는 인증 계층이 없는 MCP port 8000을 Service로 공개하지 않고 NetworkPolicy로 ingress를 제한합니다. NetworkPolicy enforcement는 운영 cluster에서 확인해야 합니다.

SQLite와 PVC

• PVC 전체를 /data에 mount하여 SQLite journal/WAL/SHM을 함께 보존합니다.
• replicas: 1과 Recreate를 유지하여 두 Pod가 같은 SQLite를 동시에 열지 않게 합니다.
• 별도 저장소로 backup을 내보내며 PVC만 재해 복구로 간주하지 않습니다.