Initial commit

deploy/helm/mcp-server/templates/_helpers.tpl

@@ -0,0 +1,62 @@
+{{/*
+설치 대상이 실제로 존재하는지 확인하고, 없으면 읽을 수 있는 메시지로 멈춘다.
+검사를 하지 않으면 오타가 "nil pointer" 같은 내부 오류로 나타나 원인을 찾기 어렵다.
+값을 반환하지 않으므로 각 template 파일의 첫 줄에서 한 번 부른다.
+*/}}
+{{- define "mcp-server.validate" -}}
+{{- $key := required "deploymentKey를 지정해야 한다. 예: --set deploymentKey=processing-critical" .Values.deploymentKey -}}
+{{- $deployment := index .Values.deployments $key -}}
+{{- if not $deployment -}}
+{{- fail (printf "values.yaml의 deployments에 '%s'가 없다. 오타이거나 아직 토폴로지에 추가하지 않은 배포다." $key) -}}
+{{- end -}}
+{{- 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 -}}
+{{- end -}}
+
+{{/*
+리소스 이름. 하나의 namespace에 여러 MCP 배포가 들어가므로 배포마다 다른 이름을 쓴다.
+*/}}
+{{- define "mcp-server.name" -}}
+{{- include "mcp-server.validate" . -}}
+{{- (index .Values.deployments .Values.deploymentKey).name -}}
+{{- end -}}
+
+{{/*
+Redis key namespace가 되는 식별자.
+환경 접미사를 여기서 자동으로 붙인다. 사람이 values에 직접 적으면 dev/test/prod가
+같은 값을 갖는 실수가 나고, 그 순간 서로의 Tool snapshot을 덮어쓴다.
+*/}}
+{{- define "mcp-server.identity" -}}
+{{- printf "%s-%s" (include "mcp-server.name" .) .Values.global.env -}}
+{{- end -}}
+
+{{/*
+이 MCP가 보는 Tool Service의 host:port.
+MCP와 Tool Service는 같은 namespace이므로 서비스 이름만으로 FQDN이 완성된다.
+호출 대상 주소는 오직 이 설정에서만 온다(계약 v0.2 §1). 매니페스트 응답은 이 값을 바꿀 수 없다.
+*/}}
+{{- 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 -}}
+
+{{- define "mcp-server.labels" -}}
+app: {{ include "mcp-server.name" . }}
+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 }}
+{{- end -}}
+
+{{- define "mcp-server.selectorLabels" -}}
+app: {{ include "mcp-server.name" . }}
+{{- end -}}

deploy/helm/mcp-server/templates/configmap.yaml

@@ -0,0 +1,37 @@
+# 배포별로 달라지는 설정만 담는다.
+# 환경과 무관한 기본값(timeout, 상한, management 포트 등)은 jar 안의 application-ocp.yml이 소유하고,
+# 이 파일이 같은 이름으로 덮어써 identity와 bundle만 배포 시점에 결정한다.
+{{- include "mcp-server.validate" . }}
+{{- $deployment := index .Values.deployments .Values.deploymentKey }}
+{{- $toolServiceHost := include "mcp-server.toolServiceHost" . }}
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: {{ include "mcp-server.name" . }}-config
+  labels:
+    {{- include "mcp-server.labels" . | nindent 4 }}
+data:
+  application-ocp.yml: |
+    mcp:
+      # "{배포 이름}-{global.env}"로 조립된다. 환경끼리 Redis key가 겹치지 않는다.
+      identity: {{ include "mcp-server.identity" . }}
+      # Agent Builder에 등록한 공개 path를 컨테이너가 그대로 처리한다. Route rewrite는 사용하지 않는다.
+      endpoint-path: {{ $deployment.publicPath | quote }}
+
+      registry:
+        refreshIntervalSeconds: {{ .Values.mcp.refreshIntervalSeconds }}
+        refreshJitterSeconds: {{ .Values.mcp.refreshJitterSeconds }}
+
+      discovery:
+        # 운영 profile은 Tool Service 매니페스트만 원천으로 쓴다.
+        enabled: true
+
+      # 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 }}
+          enabled: true

deploy/helm/mcp-server/templates/deployment.yaml

@@ -0,0 +1,88 @@
+{{- include "mcp-server.validate" . }}
+{{- $tier := index .Values.tiers (index .Values.deployments .Values.deploymentKey).tier }}
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: {{ include "mcp-server.name" . }}
+  labels:
+    {{- include "mcp-server.labels" . | nindent 4 }}
+spec:
+  # replica 수는 배포가 아니라 가용성 등급이 정한다. 환경별 values의 tiers가 정본이다.
+  replicas: {{ $tier.replicas }}
+  selector:
+    matchLabels:
+      {{- include "mcp-server.selectorLabels" . | nindent 6 }}
+  template:
+    metadata:
+      labels:
+        {{- include "mcp-server.labels" . | nindent 8 }}
+      annotations:
+        # ConfigMap이 바뀌면 Pod을 다시 굴린다. 이게 없으면 bundle 설정을 고쳐도
+        # 기존 Pod이 옛 설정으로 계속 돌아 배포한 줄 알고 넘어가게 된다.
+        checksum/config: {{ include (print $.Template.BasePath "/configmap.yaml") . | sha256sum }}
+    spec:
+      # 진행 중인 tools/call이 잘려 부작용만 남는 것을 줄인다.
+      terminationGracePeriodSeconds: {{ .Values.terminationGracePeriodSeconds }}
+      {{- if $tier.spreadAcrossNodes }}
+      affinity:
+        podAntiAffinity:
+          # replica를 서로 다른 노드에 두려고 시도한다. required가 아니라 preferred인 이유는
+          # 노드가 부족할 때 Pod이 아예 뜨지 못하는 편이 같은 노드에 뜨는 것보다 나쁘기 때문이다.
+          preferredDuringSchedulingIgnoredDuringExecution:
+            - weight: 100
+              podAffinityTerm:
+                topologyKey: kubernetes.io/hostname
+                labelSelector:
+                  matchLabels:
+                    {{- include "mcp-server.selectorLabels" . | nindent 20 }}
+      {{- end }}
+      containers:
+        - name: mcp-server
+          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
+          imagePullPolicy: {{ .Values.image.pullPolicy }}
+          ports:
+            - name: http
+              containerPort: {{ .Values.ports.http }}
+            - name: management
+              containerPort: {{ .Values.ports.management }}
+          env:
+            - name: SPRING_PROFILES_ACTIVE
+              value: ocp
+            # ConfigMap을 jar 안의 설정보다 우선 적용한다.
+            - name: SPRING_CONFIG_ADDITIONAL_LOCATION
+              value: file:/opt/app/config/
+            - name: REDIS_HOST
+              value: {{ .Values.redis.host | quote }}
+            - name: REDIS_PORT
+              value: {{ .Values.redis.port | quote }}
+            - name: MANAGEMENT_SERVER_PORT
+              value: {{ .Values.ports.management | quote }}
+          volumeMounts:
+            - name: config
+              mountPath: /opt/app/config
+              readOnly: true
+          readinessProbe:
+            httpGet:
+              path: /actuator/health/readiness
+              port: management
+            initialDelaySeconds: 10
+            periodSeconds: 10
+          livenessProbe:
+            httpGet:
+              path: /actuator/health/liveness
+              port: management
+            initialDelaySeconds: 20
+            periodSeconds: 20
+          resources:
+            {{- toYaml .Values.resources | nindent 12 }}
+          securityContext:
+            allowPrivilegeEscalation: false
+            capabilities:
+              drop: ["ALL"]
+            runAsNonRoot: true
+            seccompProfile:
+              type: RuntimeDefault
+      volumes:
+        - name: config
+          configMap:
+            name: {{ include "mcp-server.name" . }}-config

deploy/helm/mcp-server/templates/networkpolicy.yaml

@@ -0,0 +1,42 @@
+# 이 서버는 인증·인가를 하지 않는다(ADR-0006). 호출자를 제한하는 것은 이 정책이며,
+# 이것이 빠지면 클러스터 안의 어떤 Pod이든 /mcp로 Tool을 실행할 수 있다.
+# 선택적 강화가 아니라 ADR-0006의 성립 조건이므로 비활성화 스위치를 두지 않는다.
+apiVersion: networking.k8s.io/v1
+kind: NetworkPolicy
+metadata:
+  name: {{ include "mcp-server.name" . }}-ingress
+  labels:
+    {{- include "mcp-server.labels" . | nindent 4 }}
+spec:
+  podSelector:
+    matchLabels:
+      {{- include "mcp-server.selectorLabels" . | nindent 6 }}
+  policyTypes:
+    - Ingress
+  ingress:
+    # 공개 Route를 거친 요청은 OpenShift Ingress Controller에서 들어온다.
+    - from:
+        - namespaceSelector:
+            matchLabels:
+              policy-group.network.openshift.io/ingress: ""
+      ports:
+        - protocol: TCP
+          port: {{ .Values.ports.http }}
+    # 업무 포트는 Agent Builder namespace에서만 받는다.
+    # namespaceSelector가 참조하는 label은 대상 namespace에 실제로 붙어 있어야 한다.
+    # OpenShift가 자동으로 넣어 주는 kubernetes.io/metadata.name을 사용한다.
+    - from:
+        - namespaceSelector:
+            matchLabels:
+              kubernetes.io/metadata.name: {{ .Values.global.agentBuilderNamespace }}
+      ports:
+        - protocol: TCP
+          port: {{ .Values.ports.http }}
+    # management 포트는 관제만 접근한다. 외부로 노출하지 않는다.
+    - from:
+        - namespaceSelector:
+            matchLabels:
+              kubernetes.io/metadata.name: {{ .Values.global.monitoringNamespace }}
+      ports:
+        - protocol: TCP
+          port: {{ .Values.ports.management }}

deploy/helm/mcp-server/templates/poddisruptionbudget.yaml

@@ -0,0 +1,24 @@
+{{- include "mcp-server.validate" . }}
+{{- $tier := index .Values.tiers (index .Values.deployments .Values.deploymentKey).tier }}
+{{- if $tier.podDisruptionBudget }}
+# 중요 등급 배포가 자발적 중단(노드 drain, 클러스터 업그레이드) 중에도 최소 1개를 남기게 한다.
+#
+# replica를 2 이상으로 올려도 PDB가 없으면 노드 drain이 두 Pod을 한꺼번에 내릴 수 있다.
+# 등급을 나눈 목적이 "중요 Tool은 다운이 없어야 한다"이므로 이 둘은 함께 가야 한다(ADR-0007).
+#
+# NetworkPolicy와 달리 조건이 붙는다. 저쪽은 인가의 전제라 끌 수 없지만 이것은 가용성 정책이고,
+# replica 1인 dev에서는 PDB가 오히려 노드 drain을 영구히 막는다.
+# 조건이 거짓이면 이 파일은 주석까지 포함해 아무것도 렌더링하지 않는다.
+apiVersion: policy/v1
+kind: PodDisruptionBudget
+metadata:
+  name: {{ include "mcp-server.name" . }}
+  labels:
+    {{- include "mcp-server.labels" . | nindent 4 }}
+spec:
+  # minAvailable을 replica 수와 같게 두면 drain이 영원히 막힌다. 1을 남기는 것으로 충분하다.
+  minAvailable: 1
+  selector:
+    matchLabels:
+      {{- include "mcp-server.selectorLabels" . | nindent 6 }}
+{{- end }}

deploy/helm/mcp-server/templates/route.yaml

@@ -0,0 +1,24 @@
+{{- include "mcp-server.validate" . }}
+{{- $deployment := index .Values.deployments .Values.deploymentKey }}
+apiVersion: route.openshift.io/v1
+kind: Route
+metadata:
+  name: {{ include "mcp-server.name" . }}
+  labels:
+    {{- include "mcp-server.labels" . | nindent 4 }}
+  annotations:
+    haproxy.router.openshift.io/timeout: {{ .Values.route.timeout }}
+    haproxy.router.openshift.io/ip_allowlist: {{ .Values.route.sourceAllowlist | quote }}
+spec:
+  host: {{ .Values.global.mcpHost | quote }}
+  path: {{ $deployment.publicPath | quote }}
+  to:
+    kind: Service
+    name: {{ include "mcp-server.name" . }}
+    weight: 100
+  port:
+    targetPort: http
+  tls:
+    termination: edge
+    insecureEdgeTerminationPolicy: Redirect
+  wildcardPolicy: None

deploy/helm/mcp-server/templates/service.yaml

@@ -0,0 +1,13 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: {{ include "mcp-server.name" . }}
+  labels:
+    {{- include "mcp-server.labels" . | nindent 4 }}
+spec:
+  selector:
+    {{- include "mcp-server.selectorLabels" . | nindent 4 }}
+  ports:
+    - name: http
+      port: {{ .Values.ports.http }}
+      targetPort: http