Files
dap-was-dapms/deploy/helm/mcp-server/values.yaml
koseokmin 1e6fa8f22f Portal을 endpoint 원천으로 확정하고 route 단위 실패 격리를 적용한다
내부망 운영은 route↔Tool Service 매핑을 Portal이 소유하고, MCP 배포 하나가 N개
route를 서비스하며, route 하나에 N개 Tool Service가 붙을 수 있다. 이 판단을
ADR-0010으로 남기고 ADR-0007 전체와 ADR-0009 결정 4를 대체한다.

계약
- Portal-MCP registry 조회 계약 v0.1과 예제 JSON을 docs/contracts/portal-mcp/에
  신설한다. 지금까지 이 경로에는 정본이 없었다.
- 예제를 PortalToolRegistryClient의 실제 파싱 경로에 태우는 계약 테스트를 추가해
  문서와 구현이 따로 표류하지 않게 한다.

실패 격리
- fetchAllTools()의 실패 전파를 route 단위로 격리한다. 계약 v0.2의 "aggregate는
  전부 아니면 전무"는 카탈로그 하나를 전제한 규칙인데, route가 N개가 되면서 전
  route로 확대돼 있었다. Tool Service 하나의 장애가 cold start에서 Pod 전체를
  내리고 steady state에서 모든 route의 갱신을 멈추던 동작을 없앤다.
- 제거 판단의 원천을 ToolRegistryClient.knownRoutes()로 분리한다. 조회 결과를
  기준으로 지우면 이번 주기에 실패한 route의 정상 snapshot까지 사라져 "어떤
  실패도 목록을 비우지 않는다" 불변식이 깨진다.
- readiness는 최소 1개 route로 UP을 유지한다. 모든 route를 요구하면 정상 route까지
  트래픽에서 빠져 위 격리를 되돌리기 때문이다. 대신 routesWithoutSnapshot을
  health detail로 노출해 관제가 부분 상태를 감지하게 한다.

설정과 기동
- warm start가 route별 Redis key를 읽도록 확장하고, 읽을 key를 알기 위해 기동
  preload 순서를 registry 조회 → warm start → manifest 조회로 바꾼다.
- 어떤 코드도 읽지 않던 mcp.portal.route-key를 제거한다. route key는 요청 URI에서만
  결정되며, 설정으로 보정하면 잘못된 단일 진입점 호출이 조용히 성공한다.

정리
- ToolRegistryService.java의 이중 인코딩으로 깨져 있던 한글 Javadoc 33줄을 코드
  동작에 맞춰 다시 쓰고, replaceSnapshot 위에 겹쳐 있던 고아 Javadoc 블록을 지운다.
- Helm chart는 mcp.bundles 구성에서 계속 유효하므로 삭제하지 않고, 내부망 운영
  대상이 아니라는 사실을 deploy/README.md와 values.yaml에 명시한다.

검증: 이 환경은 loopback이 막혀 gradlew check를 실행하지 못했다. CodeStyleContract가
보는 항목(줄바꿈, 탭, 행말 공백, 파일 끝 개행, 미사용 import, import 순서)은 변경된
Java 13개 파일에 대해 따로 재현해 확인했다. 컴파일과 테스트 실행은 미확인이다.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-17 18:10:34 +09:00

163 lines
6.8 KiB
YAML

# 환경 공통 기본값과 배포 토폴로지. 환경별 차이는 values-{env}.yaml이 덮어쓴다.
#
# 내부망 운영은 이 Chart를 사용하지 않는다(ADR-0010 결정 7). 아래 원칙과 deployments 목록은
# 배포 하나가 Tool Service 하나를 보는 mcp.bundles 구성(ADR-0007/0009)을 전제한다.
# Portal이 endpoint 원천인 구성에서는 배포 하나가 N개 route를 서비스하므로 이 토폴로지가 성립하지 않는다.
# 자세한 배경은 deploy/README.md 머리말에 있다.
#
# 이 Chart의 설계 원칙:
# 1. MCP 배포 하나는 Tool Service 하나만 본다(ADR-0007).
# bundle 목록은 항상 한 항목이며 template이 만든다.
# 2. 배포 대상 전체를 아래 deployments 한 곳에 적는다.
# 설치할 때 --set deploymentKey=<key>로 하나를 고른다.
# 배포가 10개든 20개든 파일 수가 늘지 않고, 전체 매핑을 한 화면에서 검토할 수 있다.
# 3. 환경 축(namespace·이미지·등급별 replica)과 배포 축(어느 Tool Service를 보는가)을 섞지 않는다.
# values-{env}.yaml에는 deployments가 없고, deployments에는 환경 정보가 없다.
# 4. identity는 "{배포 이름}-{global.env}"로 조립한다.
# Redis key namespace이므로 환경끼리 겹치면 서로 Tool snapshot을 덮어쓴다.
# 사람이 손으로 적지 않게 해 실수를 구조적으로 막는다.
# 5. 외부에서는 환경별 한 host 아래 publicPath로 구분한다. Route는 Service만 선택하고
# 컨테이너가 같은 path를 직접 처리하므로 Registry의 1:1 경계는 바뀌지 않는다(ADR-0009).
# 설치할 배포를 고르는 key. 반드시 --set으로 지정한다.
# 기본값을 두지 않는 이유는, 지정을 빠뜨렸을 때 엉뚱한 배포가 조용히 설치되는 것보다
# 렌더링 실패가 낫기 때문이다.
deploymentKey: ""
global:
# 배포 환경. identity 접미사와 NetworkPolicy 판단에 쓰인다.
env: dev
# Agent Builder가 있는 namespace. Route를 우회한 Pod 직접 호출을 이 namespace로 제한한다.
# MCP와 Tool Service는 같은 namespace이므로 여기 적지 않는다.
# TODO: 실제 namespace 확정 시 교체한다.
agentBuilderNamespace: ax-hub-agentbuilder-dev
# Actuator management 포트에 접근할 관제 namespace.
monitoringNamespace: openshift-monitoring
# 환경별 공개 MCP host. 실제 OpenShift apps domain으로 교체한다.
mcpHost: mcp-dev.apps.example.internal
# 배포 대상 전체. map의 key가 곧 bundle id가 된다.
#
# name Deployment/Service/ConfigMap/NetworkPolicy 이름. 같은 namespace에서 유일해야 한다
# service 이 MCP가 보는 Tool Service의 Kubernetes Service 이름. 주소는 template이 조립한다
# namePrefix 이 Tool Service가 쓰는 Tool 이름 접두사. 업무 단위이며 등급을 넣지 않는다
# tier 가용성 등급. 아래 tiers의 key여야 한다
# publicPath Agent Builder가 등록할 외부 MCP path. 전체 topology에서 유일해야 한다
#
# 같은 업무의 두 등급이 같은 namePrefix를 공유하는 것은 의도된 구성이다(ADR-0007).
# 등급을 이름에 넣으면 Tool 재분류가 Tool name 변경이 되어 Agent Builder 재등록을 부른다.
# 그 안에서 Tool 이름이 겹치지 않게 하는 것은 Tool Service 책임이다.
#
# TODO: Tool 목록이 확정되면 실제 Tool Service 이름으로 교체하고, 없는 배포는 삭제한다.
deployments:
processing-critical:
name: processing-critical-mcp
service: processing-critical-tools
namePrefix: "processing."
tier: critical
publicPath: /mcp/processing-critical
processing-standard:
name: processing-standard-mcp
service: processing-standard-tools
namePrefix: "processing."
tier: standard
publicPath: /mcp/processing-standard
swring-critical:
name: swring-critical-mcp
service: swring-critical-tools
namePrefix: "swring."
tier: critical
publicPath: /mcp/swring-critical
swring-standard:
name: swring-standard-mcp
service: swring-standard-tools
namePrefix: "swring."
tier: standard
publicPath: /mcp/swring-standard
information-critical:
name: information-critical-mcp
service: information-critical-tools
namePrefix: "information."
tier: critical
publicPath: /mcp/information-critical
information-standard:
name: information-standard-mcp
service: information-standard-tools
namePrefix: "information."
tier: standard
publicPath: /mcp/information-standard
hr-critical:
name: hr-critical-mcp
service: hr-critical-tools
namePrefix: "hr."
tier: critical
publicPath: /mcp/hr-critical
hr-standard:
name: hr-standard-mcp
service: hr-standard-tools
namePrefix: "hr."
tier: standard
publicPath: /mcp/hr-standard
# OpenShift Router와 MCP 컨테이너가 같은 publicPath를 사용한다. rewrite하지 않는다.
route:
# Agent Builder 최대 대기 시간과 맞춘 공개 HTTP 연결 timeout이다.
timeout: 300s
# 문서용 TEST-NET이다. 실제 환경에서는 Agent Builder의 고정 egress CIDR로 교체한다.
sourceAllowlist: 192.0.2.0/24
# 등급별 가용성 기준. 환경별 values가 덮어쓴다.
#
# 배포를 등급으로 나누는 목적이 여기에 있다. 나뉘어 있어야 중요 등급에만 비용을 쓸 수 있다.
# 다만 나누는 것만으로 가용성이 생기지는 않는다. 같은 노드 배치, namespace 쿼터,
# 공통 Redis·클러스터 장애는 분할로 막히지 않는다(ADR-0007).
tiers:
critical:
replicas: 2
# 배포·노드 drain 중에도 최소 1개를 남긴다.
podDisruptionBudget: true
# replica를 서로 다른 노드에 두려고 시도한다. 노드가 부족하면 그대로 배치한다.
spreadAcrossNodes: true
standard:
replicas: 1
podDisruptionBudget: false
spreadAcrossNodes: false
image:
# TODO: 사내 컨테이너 registry 경로 확정 시 교체한다.
repository: image-registry.openshift-image-registry.svc:5000/ax-hub/ax-hub-mcp-server
tag: "0.1.0"
pullPolicy: IfNotPresent
mcp:
# Tool Service 매니페스트 조회 주기(초).
# 1:1이라 bundle 수가 항상 1이므로 조회 부하는 (replica 수 / 주기)다.
refreshIntervalSeconds: 30
refreshJitterSeconds: 5
toolService:
# MCP와 같은 namespace에 있으므로 서비스 이름 + 아래 값으로 주소가 완성된다.
port: 8080
manifestPath: /tool-manifest
basePath: /mcp
redis:
host: redis
port: 6379
ports:
http: 8080
management: 9090
resources:
requests:
cpu: 250m
memory: 512Mi
limits:
cpu: "1"
memory: 1Gi
# 진행 중인 tools/call은 Tool timeout 상한(30초) + 응답 쓰기만큼 걸릴 수 있다.
# Spring drain(40초)보다 길어야 drain이 끝나기 전에 Pod이 죽지 않는다.
terminationGracePeriodSeconds: 45