GitOps 이전까지 쓸 배포 파이프라인과 Portal 모드 Chart를 추가한다

GitOps 저장소도 ArgoCD Application도 아직 없어, 그때까지 이 저장소가 push 방식 파이프라인(.gitea/workflows/)을 임시로 소유한다. 무엇을 포기하는지와 넘길 때 할 일은 deploy/README.md에 적었다. Chart는 portal과 bundles 두 배포 모델을 모두 렌더링한다. ADR-0013이 ADR-0007을 대체했으므로 운영은 portal이 기준이지만, bundles 경로를 언제 삭제할지는 아직 정하지 않았다. - .gitea/workflows/ci.yaml, deploy-openshift.yaml - deploy/ci/render-manifests.sh, deploy/examples/ - Chart: mode 분기, selectedDeployment/tier helper, imagePullSecrets, toolService.apiKeySecret 참조 - extension-points.md에 미결 항목 9~12 추가 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-14 11:02:36 +09:00
parent 37fc0d5ebe
commit 4f60f4f01b
19 changed files with 947 additions and 156 deletions
--- a/deploy/helm/mcp-server/Chart.yaml
+++ b/deploy/helm/mcp-server/Chart.yaml
@@ -4,6 +4,7 @@ description: AX HUB MCP Server - Agent Builder와 Tool Service 사이의 statele
 type: application

 # Chart 자체의 버전. 애플리케이션 버전과 따로 올린다.
-version: 0.1.0
+# 0.2.0에서 배포 모델이 두 가지(portal·bundles)가 되어 values 구조가 바뀌었다.
+version: 0.2.0
 # 기본 이미지 tag. 배포 시 values의 image.tag가 덮어쓴다.
 appVersion: "0.1.0"
--- a/deploy/helm/mcp-server/templates/_helpers.tpl
+++ b/deploy/helm/mcp-server/templates/_helpers.tpl
@@ -2,8 +2,27 @@
 설치 대상이 실제로 존재하는지 확인하고, 없으면 읽을 수 있는 메시지로 멈춘다.
 검사를 하지 않으면 오타가 "nil pointer" 같은 내부 오류로 나타나 원인을 찾기 어렵다.
 값을 반환하지 않으므로 각 template 파일의 첫 줄에서 한 번 부른다.
+
+required의 결과는 반드시 변수에 담는다. 그대로 두면 검사한 값이 렌더링 결과에 출력되어
+이름 앞에 host와 CIDR이 붙어 나온다. 검사는 통과 여부만 남기고 아무것도 출력하지 않아야 한다.
+
+mode에 따라 검사 대상이 다르다. portal 모드는 route 매핑을 Portal이 소유하므로(ADR-0013)
+deploymentKey가 없고 registryUrl이 필수다. bundles 모드는 그 반대다.
 */}}
 {{- define "mcp-server.validate" -}}
+{{- if not (has .Values.mode (list "portal" "bundles")) -}}
+{{- fail (printf "mode는 portal 또는 bundles여야 한다: %v" .Values.mode) -}}
+{{- end -}}
+{{- if eq .Values.mode "portal" -}}
+{{- $_ := required "mode=portal이면 portal.deployment.name을 지정해야 한다." .Values.portal.deployment.name -}}
+{{- $_ = required "mode=portal이면 portal.registryUrl에 Portal registry 주소를 지정해야 한다. 환경별 values-{env}.yaml이 소유한다." .Values.portal.registryUrl -}}
+{{- if not (index .Values.tiers .Values.portal.deployment.tier) -}}
+{{- fail (printf "values.yaml의 tiers에 '%s' 등급이 없다." .Values.portal.deployment.tier) -}}
+{{- end -}}
+{{- if .Values.deploymentKey -}}
+{{- fail "mode=portal에서는 deploymentKey를 쓰지 않는다. route는 /mcp/{routeKey} URI에서만 결정된다(ADR-0013)." -}}
+{{- end -}}
+{{- else -}}
 {{- $key := required "deploymentKey를 지정해야 한다. 예: --set deploymentKey=processing-critical" .Values.deploymentKey -}}
 {{- $deployment := index .Values.deployments $key -}}
 {{- if not $deployment -}}
@@ -12,20 +31,42 @@
 {{- if not (index .Values.tiers $deployment.tier) -}}
 {{- fail (printf "values.yaml의 tiers에 '%s' 등급이 없다. deployments의 tier와 tiers의 key가 어긋났다." $deployment.tier) -}}
 {{- end -}}
-{{- required "global.mcpHost에 환경별 공개 MCP host를 지정해야 한다." .Values.global.mcpHost -}}
-{{- required "route.sourceAllowlist에 Agent Builder의 고정 egress CIDR을 지정해야 한다." .Values.route.sourceAllowlist -}}
-{{- $publicPath := required (printf "deployments.%s.publicPath를 지정해야 한다." $key) $deployment.publicPath -}}
-{{- if not (regexMatch "^/mcp/[a-z0-9-]+$" $publicPath) -}}
-{{- fail (printf "deployments.%s.publicPath는 /mcp/<영문 소문자·숫자·하이픈> 형식이어야 한다: %s" $key $publicPath) -}}
+{{- end -}}
+{{- $_ := required "global.mcpHost에 환경별 공개 MCP host를 지정해야 한다." .Values.global.mcpHost -}}
+{{- $_ = required "route.sourceAllowlist에 Agent Builder의 고정 egress CIDR을 지정해야 한다." .Values.route.sourceAllowlist -}}
+{{- $publicPath := required "선택된 배포의 publicPath를 지정해야 한다." (include "mcp-server.selectedDeployment" . | fromYaml).publicPath -}}
+{{- if not (regexMatch "^/mcp(/[a-z0-9-]+)?$" $publicPath) -}}
+{{- fail (printf "publicPath는 /mcp 또는 /mcp/<영문 소문자·숫자·하이픈> 형식이어야 한다: %s" $publicPath) -}}
 {{- end -}}
 {{- end -}}

 {{/*
-리소스 이름. 하나의 namespace에 여러 MCP 배포가 들어가므로 배포마다 다른 이름을 쓴다.
+설치할 배포 하나를 dict로 돌려준다. mode가 그것을 어디서 읽는가의 차이만 여기서 흡수하고,
+나머지 template은 어느 모드인지 모른 채 같은 필드(name·tier·publicPath)를 쓴다.
+호출부는 `include ... | fromYaml`로 받는다. Helm helper는 문자열만 반환하기 때문이다.
+검사를 부르지 않는다. validate가 이 helper를 사용하므로 서로를 부르면 순환한다.
+*/}}
+{{- define "mcp-server.selectedDeployment" -}}
+{{- if eq .Values.mode "portal" -}}
+{{ toYaml .Values.portal.deployment }}
+{{- else -}}
+{{ toYaml (index .Values.deployments .Values.deploymentKey) }}
+{{- end -}}
+{{- end -}}
+
+{{/*
+리소스 이름. 하나의 namespace에 여러 MCP 배포가 들어갈 수 있으므로 배포마다 다른 이름을 쓴다.
 */}}
 {{- define "mcp-server.name" -}}
 {{- include "mcp-server.validate" . -}}
-{{- (index .Values.deployments .Values.deploymentKey).name -}}
+{{- (include "mcp-server.selectedDeployment" . | fromYaml).name -}}
+{{- end -}}
+
+{{/*
+선택된 배포의 가용성 등급 이름.
+*/}}
+{{- define "mcp-server.tier" -}}
+{{- (include "mcp-server.selectedDeployment" . | fromYaml).tier -}}
 {{- end -}}

 {{/*
@@ -38,12 +79,12 @@ Redis key namespace가 되는 식별자.
 {{- end -}}

 {{/*
-이 MCP가 보는 Tool Service의 host:port.
+이 MCP가 보는 Tool Service의 host:port. bundles 모드에서만 쓴다.
 MCP와 Tool Service는 같은 namespace이므로 서비스 이름만으로 FQDN이 완성된다.
 호출 대상 주소는 오직 이 설정에서만 온다(계약 v0.2 §1). 매니페스트 응답은 이 값을 바꿀 수 없다.
+portal 모드에서는 이 주소를 Portal registry가 소유하므로 이 helper를 부르지 않는다.
 */}}
 {{- define "mcp-server.toolServiceHost" -}}
-{{- include "mcp-server.validate" . -}}
 {{- $deployment := index .Values.deployments .Values.deploymentKey -}}
 {{- printf "%s.%s.svc.cluster.local:%v" $deployment.service .Release.Namespace .Values.toolService.port -}}
 {{- end -}}
@@ -54,7 +95,8 @@ app.kubernetes.io/name: {{ include "mcp-server.name" . }}
 app.kubernetes.io/instance: {{ .Release.Name }}
 app.kubernetes.io/component: mcp-server
 app.kubernetes.io/part-of: ax-hub
-ax-hub/tier: {{ (index .Values.deployments .Values.deploymentKey).tier }}
+ax-hub/mode: {{ .Values.mode }}
+ax-hub/tier: {{ include "mcp-server.tier" . }}
 {{- end -}}

 {{- define "mcp-server.selectorLabels" -}}
--- a/deploy/helm/mcp-server/templates/configmap.yaml
+++ b/deploy/helm/mcp-server/templates/configmap.yaml
@@ -1,9 +1,8 @@
 # 배포별로 달라지는 설정만 담는다.
 # 환경과 무관한 기본값(timeout, 상한, management 포트 등)은 jar 안의 application-ocp.yml이 소유하고,
-# 이 파일이 같은 이름으로 덮어써 identity와 bundle만 배포 시점에 결정한다.
+# 이 파일이 같은 이름으로 덮어써 identity와 Tool 원천만 배포 시점에 결정한다.
 {{- include "mcp-server.validate" . }}
-{{- $deployment := index .Values.deployments .Values.deploymentKey }}
-{{- $toolServiceHost := include "mcp-server.toolServiceHost" . }}
+{{- $deployment := include "mcp-server.selectedDeployment" . | fromYaml }}
 apiVersion: v1
 kind: ConfigMap
 metadata:
@@ -19,19 +18,41 @@ data:
      endpoint-path: {{ $deployment.publicPath | quote }}

      registry:
-        refreshIntervalSeconds: {{ .Values.mcp.refreshIntervalSeconds }}
-        refreshJitterSeconds: {{ .Values.mcp.refreshJitterSeconds }}
+        refresh-interval-seconds: {{ .Values.mcp.refreshIntervalSeconds }}
+        refresh-jitter-seconds: {{ .Values.mcp.refreshJitterSeconds }}

      discovery:
        # 운영 profile은 Tool Service 매니페스트만 원천으로 쓴다.
        enabled: true

+      redis:
+        # Portal 조회가 실패한 cold start에서만 읽는 fallback key다.
+        # 포털이 쓰는 key와 반드시 같아야 한다.
+        portal-registry-key: {{ .Values.portal.registryRedisKey | quote }}
+{{- if eq .Values.mode "portal" }}
+
+      # route↔Tool Service 매핑의 원천은 Portal이다(ADR-0013).
+      # 배포 하나가 N개 route를 서비스하고, route key는 /mcp/{routeKey} URI에서만 결정된다.
+      # 매핑이 바뀌어도 이 ConfigMap을 고치지 않는다. 그것이 Portal을 원천으로 둔 이유다.
+      portal:
+        enabled: true
+        registry-url: {{ .Values.portal.registryUrl | quote }}
+        refresh-interval-seconds: {{ .Values.portal.refreshIntervalSeconds }}
+
+      # Portal이 주소를 소유하므로 정적 bundle을 선언하지 않는다.
+      bundles: []
+{{- else }}
+
+      portal:
+        enabled: false
+
      # MCP 배포 하나는 Tool Service 하나만 본다(ADR-0007).
      # 이 목록은 항상 한 항목이며, 늘리려면 배포를 하나 더 만든다.
      # 주소는 여기서 조립한다. values에 URL을 적기 시작하면 오타가 라우팅 사고가 된다.
      bundles:
        - id: {{ .Values.deploymentKey | quote }}
          namePrefix: {{ $deployment.namePrefix | quote }}
-          manifestUrl: http://{{ $toolServiceHost }}{{ .Values.toolService.manifestPath }}
-          baseEndpoint: http://{{ $toolServiceHost }}{{ .Values.toolService.basePath }}
+          manifestUrl: http://{{ include "mcp-server.toolServiceHost" . }}{{ .Values.toolService.manifestPath }}
+          baseEndpoint: http://{{ include "mcp-server.toolServiceHost" . }}{{ .Values.toolService.basePath }}
          enabled: true
+{{- end }}
--- a/deploy/helm/mcp-server/templates/deployment.yaml
+++ b/deploy/helm/mcp-server/templates/deployment.yaml
@@ -1,5 +1,5 @@
 {{- include "mcp-server.validate" . }}
-{{- $tier := index .Values.tiers (index .Values.deployments .Values.deploymentKey).tier }}
+{{- $tier := index .Values.tiers (include "mcp-server.tier" .) }}
 apiVersion: apps/v1
 kind: Deployment
 metadata:
@@ -17,12 +17,17 @@ spec:
      labels:
        {{- include "mcp-server.labels" . | nindent 8 }}
      annotations:
-        # ConfigMap이 바뀌면 Pod을 다시 굴린다. 이게 없으면 bundle 설정을 고쳐도
+        # ConfigMap이 바뀌면 Pod을 다시 굴린다. 이게 없으면 설정을 고쳐도
        # 기존 Pod이 옛 설정으로 계속 돌아 배포한 줄 알고 넘어가게 된다.
        checksum/config: {{ include (print $.Template.BasePath "/configmap.yaml") . | sha256sum }}
    spec:
      # 진행 중인 tools/call이 잘려 부작용만 남는 것을 줄인다.
      terminationGracePeriodSeconds: {{ .Values.terminationGracePeriodSeconds }}
+      {{- with .Values.image.pullSecrets }}
+      # 사내 registry가 인증을 요구할 때만 지정한다. 비워 두면 렌더링되지 않는다.
+      imagePullSecrets:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
      {{- if $tier.spreadAcrossNodes }}
      affinity:
        podAntiAffinity:
@@ -57,10 +62,20 @@ spec:
              value: {{ .Values.redis.port | quote }}
            - name: MANAGEMENT_SERVER_PORT
              value: {{ .Values.ports.management | quote }}
+            {{- if .Values.toolService.apiKeySecret.name }}
+            # Tool Service 호출용 API key. 값은 Secret이 소유하고 Chart는 이름만 안다.
+            - name: TOOL_SERVER_API_KEY
+              valueFrom:
+                secretKeyRef:
+                  name: {{ .Values.toolService.apiKeySecret.name }}
+                  key: {{ .Values.toolService.apiKeySecret.key }}
+            {{- end }}
          volumeMounts:
            - name: config
              mountPath: /opt/app/config
              readOnly: true
+          # readiness는 첫 Tool 조회가 끝나고 usable snapshot이 있을 때만 UP이다.
+          # 원천이 늦게 뜨는 환경에서 Pod을 죽이지 않도록 liveness에는 그 조건이 들어가지 않는다.
          readinessProbe:
            httpGet:
              path: /actuator/health/readiness
--- a/deploy/helm/mcp-server/templates/poddisruptionbudget.yaml
+++ b/deploy/helm/mcp-server/templates/poddisruptionbudget.yaml
@@ -1,10 +1,10 @@
 {{- include "mcp-server.validate" . }}
-{{- $tier := index .Values.tiers (index .Values.deployments .Values.deploymentKey).tier }}
+{{- $tier := index .Values.tiers (include "mcp-server.tier" .) }}
 {{- if $tier.podDisruptionBudget }}
 # 중요 등급 배포가 자발적 중단(노드 drain, 클러스터 업그레이드) 중에도 최소 1개를 남기게 한다.
 #
 # replica를 2 이상으로 올려도 PDB가 없으면 노드 drain이 두 Pod을 한꺼번에 내릴 수 있다.
-# 등급을 나눈 목적이 "중요 Tool은 다운이 없어야 한다"이므로 이 둘은 함께 가야 한다(ADR-0007).
+# 등급을 나눈 목적이 "중요 Tool은 다운이 없어야 한다"이므로 이 둘은 함께 가야 한다.
 #
 # NetworkPolicy와 달리 조건이 붙는다. 저쪽은 인가의 전제라 끌 수 없지만 이것은 가용성 정책이고,
 # replica 1인 dev에서는 PDB가 오히려 노드 drain을 영구히 막는다.
--- a/deploy/helm/mcp-server/templates/route.yaml
+++ b/deploy/helm/mcp-server/templates/route.yaml
@@ -1,5 +1,7 @@
 {{- include "mcp-server.validate" . }}
-{{- $deployment := index .Values.deployments .Values.deploymentKey }}
+{{- $deployment := include "mcp-server.selectedDeployment" . | fromYaml }}
+# OpenShift Route의 path는 prefix 매칭이다. portal 모드에서 path가 "/mcp"이면
+# /mcp/{routeKey} 전체가 이 Route 하나로 들어오고, route 구분은 컨테이너가 한다(ADR-0013).
 apiVersion: route.openshift.io/v1
 kind: Route
 metadata:
--- a/deploy/helm/mcp-server/values-dev.yaml
+++ b/deploy/helm/mcp-server/values-dev.yaml
@@ -1,10 +1,10 @@
 # dev 환경. 배포마다 Pod 1개로 구성한다.
 #
 # dev에서는 중요 등급도 replica 1이다. rolling update 중 수십 초 공백이 생기지만
-# dev는 가용성 목표 대상이 아니다. 중요 등급의 replica 하한과 PDB는 prod에서만 강제하며
+# dev는 가용성 목표 대상이 아니다. 중요 등급의 replica 하한과 PDB는 test·prod에서만 강제하며
 # HelmDeploymentContractTest가 그 사실을 고정한다.
 #
-# 어느 배포를 설치할지는 이 파일이 정하지 않는다. --set deploymentKey=<key>로 고른다.
+# 이 파일은 배포 토폴로지를 소유하지 않는다. mode와 deployments는 values.yaml 한 곳에 있다.
 # TODO: namespace가 확정되면 agentBuilderNamespace를 교체한다.

 global:
@@ -12,6 +12,11 @@ global:
  agentBuilderNamespace: ax-hub-agentbuilder-dev
  mcpHost: mcp-dev.apps.example.internal

+portal:
+  # TODO: 실제 dev Portal registry 주소로 확정한다. deploy/docker-compose.yml의 mock과 같은 응답을 준다.
+  registryUrl: https://axhub.devjun.net/api/portal/registry
+  refreshIntervalSeconds: 60
+
 route:
  # TODO: Agent Builder의 실제 고정 egress CIDR로 교체한다.
  sourceAllowlist: 192.0.2.0/24
--- a/deploy/helm/mcp-server/values-prod.yaml
+++ b/deploy/helm/mcp-server/values-prod.yaml
@@ -1,16 +1,14 @@
 # prod 환경.
 #
-# replica는 배포 하나가 받는 트래픽 기준으로 잡는다. 업무 × 등급으로 나뉘어 있으므로
-# 배포 하나가 받는 몫은 전체를 하나로 묶었을 때의 일부다. 등급별 기준은 아래가 정본이다.
-#
-# 조회 부하 = replica 수 / 주기. 1:1이라 bundle 수는 항상 1이다(ADR-0007).
-#   중요 등급 3 replica / 30초 = 배포당 초당 0.1회. Tool Service 한 대가 받는 몫이 그대로 이 값이다.
+# replica는 이 배포가 받는 트래픽 기준으로 잡는다.
+# 매니페스트 조회 부하 = replica 수 × (route에 붙은 Tool Service 수) / 주기다.
+# portal 모드는 한 배포가 전 route를 서비스하므로 route가 늘면 이 값이 함께 는다(ADR-0013 전제 3).
 #
 # 중요 등급은 replica 2 이상과 PodDisruptionBudget이 필수다.
 # 1이면 rolling update 중 반드시 공백이 생기고, PDB가 없으면 노드 drain이 마지막 Pod을 내린다.
 # HelmDeploymentContractTest가 replica·PDB·노드 분산 values를 정적으로 검사한다.
 #
-# 어느 배포를 설치할지는 이 파일이 정하지 않는다. --set deploymentKey=<key>로 고른다.
+# 이 파일은 배포 토폴로지를 소유하지 않는다. mode와 deployments는 values.yaml 한 곳에 있다.
 # TODO: namespace가 확정되면 agentBuilderNamespace를 교체한다.

 global:
@@ -18,6 +16,11 @@ global:
  agentBuilderNamespace: ax-hub-agentbuilder-prod
  mcpHost: mcp.apps.example.internal

+portal:
+  # TODO: 실제 운영 Portal registry 주소로 교체한다.
+  registryUrl: https://axhub.apps.example.internal/api/portal/registry
+  refreshIntervalSeconds: 300
+
 route:
  # TODO: Agent Builder의 실제 고정 egress CIDR로 교체한다.
  sourceAllowlist: 192.0.2.0/24
--- a/deploy/helm/mcp-server/values-test.yaml
+++ b/deploy/helm/mcp-server/values-test.yaml
@@ -1,9 +1,9 @@
 # test 환경. 운영계에 앞서 중요 등급의 가용성 설정을 검증하는 단계다.
 #
-# 중요 등급을 prod와 같은 방식(replica 2 + PDB)으로 먼저 검증하는 자리다.
+# 중요 등급을 prod와 같은 방식(replica 2 + PDB + 노드 분산)으로 먼저 검증하는 자리다.
 # 여기서 확인하지 않으면 prod 배포 때 처음 겪게 된다.
 #
-# 어느 배포를 설치할지는 이 파일이 정하지 않는다. --set deploymentKey=<key>로 고른다.
+# 이 파일은 배포 토폴로지를 소유하지 않는다. mode와 deployments는 values.yaml 한 곳에 있다.
 # TODO: namespace가 확정되면 agentBuilderNamespace를 교체한다.

 global:
@@ -11,6 +11,11 @@ global:
  agentBuilderNamespace: ax-hub-agentbuilder-test
  mcpHost: mcp-test.apps.example.internal

+portal:
+  # TODO: 실제 test Portal registry 주소로 교체한다.
+  registryUrl: https://axhub-test.apps.example.internal/api/portal/registry
+  refreshIntervalSeconds: 300
+
 route:
  # TODO: Agent Builder의 실제 고정 egress CIDR로 교체한다.
  sourceAllowlist: 192.0.2.0/24
--- a/deploy/helm/mcp-server/values.yaml
+++ b/deploy/helm/mcp-server/values.yaml
@@ -6,36 +6,48 @@
 # 자세한 배경은 deploy/README.md 머리말에 있다.
 #
 # 이 Chart의 설계 원칙:
-#   1. MCP 배포 하나는 Tool Service 하나만 본다(ADR-0007).
-#      bundle 목록은 항상 한 항목이며 template이 만든다.
-#   2. 배포 대상 전체를 아래 deployments 한 곳에 적는다.
-#      설치할 때 --set deploymentKey=<key>로 하나를 고른다.
-#      배포가 10개든 20개든 파일 수가 늘지 않고, 전체 매핑을 한 화면에서 검토할 수 있다.
-#   3. 환경 축(namespace·이미지·등급별 replica)과 배포 축(어느 Tool Service를 보는가)을 섞지 않는다.
+#   1. 배포 모델이 두 가지다. mode가 그 축을 고른다.
+#      portal  — route↔Tool Service 매핑의 원천이 Portal이다(ADR-0013). 배포 하나가 N route를
+#                서비스하고 route key는 /mcp/{routeKey} URI에서만 온다. 현재 애플리케이션 코드의 경로다.
+#      bundles — 배포 하나가 Tool Service 하나만 보고 매핑을 배포 시점에 못박는다(ADR-0007).
+#                ADR-0013이 대체했지만 코드 경로가 남아 있어 1:1 검증·격리 배포에 쓸 수 있다.
+#   2. 환경 축(namespace·이미지·등급별 replica)과 배포 축(무엇을 보는가)을 섞지 않는다.
 #      values-{env}.yaml에는 deployments가 없고, deployments에는 환경 정보가 없다.
-#   4. identity는 "{배포 이름}-{global.env}"로 조립한다.
+#   3. identity는 "{배포 이름}-{global.env}"로 조립한다.
 #      Redis key namespace이므로 환경끼리 겹치면 서로 Tool snapshot을 덮어쓴다.
 #      사람이 손으로 적지 않게 해 실수를 구조적으로 막는다.
-#   5. 외부에서는 환경별 한 host 아래 publicPath로 구분한다. Route는 Service만 선택하고
-#      컨테이너가 같은 path를 직접 처리하므로 Registry의 1:1 경계는 바뀌지 않는다(ADR-0009).
+#   4. 공개 path는 Route와 컨테이너가 동일하게 사용하고 rewrite하지 않는다(ADR-0009).

-# 설치할 배포를 고르는 key. 반드시 --set으로 지정한다.
+# 배포 모델. portal | bundles
+# 기본값을 portal로 둔 이유는 현재 애플리케이션이 실제로 도는 경로이기 때문이다.
+mode: portal
+
+# ---------------------------------------------------------------------------
+# mode=portal 축
+# ---------------------------------------------------------------------------
+portal:
+  # 이 환경에 설치되는 단일 MCP 배포. route가 늘어도 배포는 늘지 않는다.
+  deployment:
+    name: axhub-mcp
+    tier: critical
+    # route key는 이 path 아래 URI segment에서 온다. 여기에 routeKey를 적지 않는다.
+    publicPath: /mcp
+  # Portal registry 조회 주소. 환경마다 다르므로 values-{env}.yaml이 소유한다.
+  # 기본값을 두지 않는 이유는, 빠뜨린 설치가 조용히 성공하는 것보다 렌더링 실패가 낫기 때문이다.
+  registryUrl: ""
+  refreshIntervalSeconds: 300
+  # Portal 조회가 실패한 cold start에서만 읽는 Redis fallback key.
+  # 포털이 registry를 써 넣는 key와 반드시 같아야 한다.
+  registryRedisKey: axhub:mcp:portal-registry
+
+# ---------------------------------------------------------------------------
+# mode=bundles 축
+# ---------------------------------------------------------------------------
+# 설치할 배포를 고르는 key. mode=bundles일 때 반드시 --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에서 유일해야 한다
@@ -44,10 +56,6 @@ global:
 #   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:
@@ -99,6 +107,20 @@ deployments:
    tier: standard
    publicPath: /mcp/hr-standard

+# ---------------------------------------------------------------------------
+# 모드 공통
+# ---------------------------------------------------------------------------
+global:
+  # 배포 환경. identity 접미사와 NetworkPolicy 판단에 쓰인다.
+  env: dev
+  # Agent Builder가 있는 namespace. Route를 우회한 Pod 직접 호출을 이 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
+
 # OpenShift Router와 MCP 컨테이너가 같은 publicPath를 사용한다. rewrite하지 않는다.
 route:
  # Agent Builder 최대 대기 시간과 맞춘 공개 HTTP 연결 timeout이다.
@@ -108,9 +130,9 @@ route:

 # 등급별 가용성 기준. 환경별 values가 덮어쓴다.
 #
-# 배포를 등급으로 나누는 목적이 여기에 있다. 나뉘어 있어야 중요 등급에만 비용을 쓸 수 있다.
 # 다만 나누는 것만으로 가용성이 생기지는 않는다. 같은 노드 배치, namespace 쿼터,
-# 공통 Redis·클러스터 장애는 분할로 막히지 않는다(ADR-0007).
+# 공통 Redis·클러스터 장애는 분할로 막히지 않는다.
+# portal 모드에서는 배포가 하나이므로 등급별 물리 분리가 성립하지 않는다(ADR-0013 전제 2).
 tiers:
  critical:
    replicas: 2
@@ -125,21 +147,28 @@ tiers:

 image:
  # TODO: 사내 컨테이너 registry 경로 확정 시 교체한다.
+  # CI가 --set image.tag=<commit sha>로 덮어쓴다.
  repository: image-registry.openshift-image-registry.svc:5000/ax-hub/ax-hub-mcp-server
  tag: "0.1.0"
  pullPolicy: IfNotPresent
+  # 사내 registry가 인증을 요구할 때만 채운다. 예: [{name: harbor-pull}]
+  pullSecrets: []

 mcp:
  # Tool Service 매니페스트 조회 주기(초).
-  # 1:1이라 bundle 수가 항상 1이므로 조회 부하는 (replica 수 / 주기)다.
  refreshIntervalSeconds: 30
  refreshJitterSeconds: 5

 toolService:
-  # MCP와 같은 namespace에 있으므로 서비스 이름 + 아래 값으로 주소가 완성된다.
+  # bundles 모드에서만 쓴다. MCP와 Tool Service가 같은 namespace라는 전제다.
  port: 8080
  manifestPath: /tool-manifest
  basePath: /mcp
+  # Tool Service 호출용 API key를 담은 Secret. name이 비어 있으면 환경변수를 주입하지 않고
+  # 애플리케이션 기본값을 쓴다. 운영에서는 반드시 채운다.
+  apiKeySecret:
+    name: ""
+    key: tool-server-api-key

 redis:
  host: redis