AX-HUB/dap-was-dapms
10
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
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>
This commit is contained in:
koseokmin
2026-09-14 11:02:36 +09:00
parent 37fc0d5ebe
commit 4f60f4f01b
19 changed files with 947 additions and 156 deletions
Download Patch File Download Diff File Expand all files Collapse all files

178
deploy/README.md
View File

@@ -1,7 +1,8 @@
# 배포 정의
이 디렉터리는 **배포될 대상**을 정의한다. 빌드·이미지·배포 실행 방식은 사내 표준 CI/CD가 담당하며
이 저장소가 정하지 않는다.
이 디렉터리는 **배포될 대상**과, 그것을 클러스터에 올리는 **임시 경로**를 정의한다.
빌드·배포 실행 방식의 정본은 원래 사내 표준 CI/CD이며 이 저장소가 정하지 않는다.
지금 여기 파이프라인이 있는 이유는 [아래](#gitops-저장소가-없는-동안의-우회)에 적었다.
> **내부망 운영은 이 Chart를 사용하지 않는다**([ADR-0013](../docs/decisions/ADR-0013-portal-owns-route-and-endpoint-registry.md) 결정 7).
> 여기 정의된 토폴로지는 배포 하나가 Tool Service 하나를 보는 `mcp.bundles` 구성(ADR-0007/0009)을 전제한다.
@@ -13,64 +14,67 @@
## Helm Chart
[helm/mcp-server/](helm/mcp-server/)가 유일한 배포 정의다. values는 두 축으로 나뉜다.
[helm/mcp-server/](helm/mcp-server/)가 유일한 배포 정의다.
### 배포 모델이 두 가지다
| mode | 무엇이 route↔Tool Service 매핑을 소유하는가 | 근거 |
|---|---|---|
| `portal` (기본값) | **Portal.** 배포 하나가 N개 route를 서비스하고 route key는 `/mcp/{routeKey}` URI에서만 온다 | [ADR-0013](../docs/decisions/ADR-0013-portal-owns-route-and-endpoint-registry.md) |
| `bundles` | **배포 정의.** 배포 하나가 Tool Service 하나만 보고 매핑을 배포 시점에 못박는다 | [ADR-0007](../docs/decisions/ADR-0007-one-mcp-per-tool-service.md) |
**현재 애플리케이션이 실제로 도는 경로는 `portal`이다.** `bundles`는 ADR-0013이 대체했지만 코드 경로가
남아 있어 1:1 검증과 격리 배포에 쓸 수 있다. 어느 쪽을 운영에 쓸지는 아직 확정되지 않았고
[extension-points.md](../docs/extension-points.md)에서 관리한다.
`mode`를 바꾸면 ConfigMap의 Tool 원천이 통째로 바뀐다. 값 하나로 배포 성격이 달라지므로
설치 명령에 항상 명시한다.
### values는 두 축으로 나뉜다
| 파일 | 소유하는 것 |
|---|---|
| `values.yaml` | **배포 토폴로지.** 어떤 MCP가 어떤 Tool Service를 보는가, 공개 path, 가용성 등급 |
| `values-{dev,test,prod}.yaml` | **환경 차이.** namespace, 이미지, 공개 host·허용 CIDR, 등급별 replica·PDB, 리소스 |
| `values.yaml` | **배포 토폴로지.** mode, portal 배포 정의, bundles 배포 목록, 등급 기준 |
| `values-{dev,test,prod}.yaml` | **환경 차이.** namespace, 공개 host·허용 CIDR, Portal registry 주소, 등급별 replica·PDB, 리소스 |
설치할 때 두 번째 축을 `-f`로, 첫 번째 축에서 고를 배포 하나를 `--set deploymentKey=`로 지정한다.
환경 파일은 토폴로지를 갖지 않는다. `HelmDeploymentContractTest`가 그 경계를 고정한다.
```bash
helm upgrade --install processing-critical-mcp helm/mcp-server -f helm/mcp-server/values-dev.yaml --set deploymentKey=processing-critical -n <namespace>
# portal 모드. 배포가 하나이므로 deploymentKey가 없다.
helm upgrade --install axhub-mcp helm/mcp-server -f helm/mcp-server/values-dev.yaml -n <namespace>
# bundles 모드. 설치할 배포 하나를 반드시 고른다.
helm upgrade --install processing-critical-mcp helm/mcp-server -f helm/mcp-server/values-dev.yaml \
--set mode=bundles --set deploymentKey=processing-critical -n <namespace>
```
`deploymentKey`에는 기본값이 없다. 지정을 빠뜨리면 렌더링 단계에서 멈춘다.
엉뚱한 배포가 조용히 설치되는 것보다 낫다.
`deploymentKey`에는 기본값이 없다. `bundles`에서 지정을 빠뜨리면 렌더링 단계에서 멈춘다.
엉뚱한 배포가 조용히 설치되는 것보다 낫다. 반대로 `portal`에서 `deploymentKey`를 주면 역시 멈춘다.
route를 배포 정의에 적기 시작하면 Portal을 원천으로 둔 이유가 사라지기 때문이다.
### 공유 host와 배포별 path
### 공개 host와 path
[ADR-0009](../docs/decisions/ADR-0009-container-handles-public-mcp-path.md)에 따라 한 환경은 하나의 공개 host를 사용하고,
각 Helm release는 고유 path의 OpenShift Route를 만든다. Route는 Service만 선택하고 공개 path를 그대로
전달하며, 컨테이너가 같은 path를 직접 처리한다.
한 환경은 하나의 공개 host를 사용한다([ADR-0009](../docs/decisions/ADR-0009-container-handles-public-mcp-path.md)).
Route는 Service만 선택하고 공개 path를 그대로 전달하며, 컨테이너가 같은 path를 직접 처리한다.
`portal` 모드에서 Route path는 `/mcp` 하나다. OpenShift Route의 path는 prefix 매칭이므로
`/mcp/{routeKey}` 전체가 이 Route로 들어오고, route 구분은 컨테이너가 한다.
```text
https://mcp-dev.apps.example.internal/mcp/cus -> axhub-mcp:8080/mcp/cus
https://mcp-dev.apps.example.internal/mcp/sal -> axhub-mcp:8080/mcp/sal
```
`bundles` 모드에서는 Route가 배포마다 하나씩 생기고 path가 배포별로 다르다.
```text
https://mcp-dev.apps.example.internal/mcp/processing-critical -> processing-critical-mcp:8080/mcp/processing-critical
https://mcp-dev.apps.example.internal/mcp/information-standard -> information-standard-mcp:8080/mcp/information-standard
```
공개 URL은 각각 독립된 MCP다. Agent Builder는 URL별로 등록하고 initialize하며, 한 Route나 MCP Pod의
장애가 다른 path의 Deployment로 전파되지 않는다.
### MCP 하나는 Tool Service 하나만 본다
[ADR-0007](../docs/decisions/ADR-0007-one-mcp-per-tool-service.md)의 결정이다. 대상을 늘리는 방법은
bundle 목록을 늘리는 것이 아니라 **배포를 하나 더 만드는 것**이다.
```yaml
deployments:
processing-critical:
name: processing-critical-mcp
service: processing-critical-tools # ← 이름만. 주소는 template이 만든다
namePrefix: "processing." # ← 업무 단위. 등급을 넣지 않는다
tier: critical
publicPath: /mcp/processing-critical # ← 환경 host 안에서 유일
```
배포가 10개든 20개든 **파일 수는 늘지 않는다.** 전체 매핑을 한 화면에서 검토할 수 있고,
`--set`으로 고르는 값 하나만 배포마다 달라진다.
MCP Server와 Tool Service는 같은 namespace에 배포하므로 values에는 서비스 이름만 적고
주소는 template이 조립한다. 환경마다 URL을 반복하지 않으므로 오타로 다른 대상을 호출할 수 없다.
`identity`도 `{배포 이름}-{global.env}`로 template이 조립한다. 현재 Redis cache 구현이 이 값을
사용하지만, key namespace와 공유 정책은 아직 확정되지 않았다.
두 경우 모두 공개 URL은 각각 독립된 MCP다. Agent Builder는 URL별로 등록하고 initialize한다.
### 가용성 등급
배포를 업무 × 중요도로 나누는 목적은 **중요 등급에만 비용을 쓰기 위해서**다.
```yaml
tiers:
critical: { replicas: 3, podDisruptionBudget: true, spreadAcrossNodes: true }
@@ -79,27 +83,74 @@ tiers:
test와 prod의 `critical`은 **replica 2 이상, PodDisruptionBudget, 노드 분산 설정이 필수**다. replica가
1이면 rolling update 중 반드시 공백이 생기고, PDB가 없으면 노드 drain이 마지막 Pod을 내릴 수 있다.
`HelmDeploymentContractTest`는 values와 template의 정적 규칙을 검사한다. dev는 배포마다 Pod 1개로
운영하므로 이 검사 대상이 아니다.
dev는 배포마다 Pod 1개로 운영하므로 이 검사 대상이 아니다.
정적 테스트는 Helm 렌더러를 실행하지 않는다. 실제 배포 파이프라인은 사용하는 환경과 등급별로
`helm lint`와 `helm template`을 실행해 병합된 values와 생성 YAML을 확인해야 한다.
**`portal` 모드에서 등급별 물리 분리는 성립하지 않는다.** 배포가 하나이므로 전 route가 같은
프로세스·같은 replica set을 공유한다([ADR-0013](../docs/decisions/ADR-0013-portal-owns-route-and-endpoint-registry.md) 전제 2).
`tiers`는 그 하나의 배포에 어떤 가용성 기준을 적용할지만 정한다.
### 렌더링 검증
`HelmDeploymentContractTest`는 values와 template의 **정적 규칙**만 본다. helper 오류, 조건 분기 실수,
들여쓰기는 실제로 렌더링해야 드러난다. 두 검사는 서로를 대신하지 못한다.
```bash
helm lint helm/mcp-server -f helm/mcp-server/values-prod.yaml --set deploymentKey=processing-critical
helm template processing-critical-mcp helm/mcp-server -f helm/mcp-server/values-prod.yaml --set deploymentKey=processing-critical
helm template processing-standard-mcp helm/mcp-server -f helm/mcp-server/values-prod.yaml --set deploymentKey=processing-standard
deploy/ci/render-manifests.sh # 환경 × 모드 전 조합 lint + template
```
**나누는 것만으로 가용성이 생기지는 않는다.** 같은 노드 배치, namespace 쿼터, 공통 Redis·클러스터
장애는 분할로 막히지 않는다. 남은 작업은 [extension-points.md](../docs/extension-points.md)의
"운영 적용 전 필수 보완"에서 관리한다.
CI가 매 push에서 같은 스크립트를 돌리고 결과를 `rendered-manifests` 아티팩트로 올린다.
### dev에서 MCP에 연결되지 않을 때
## GitOps 저장소가 없는 동안의 우회
Chart를 어디에 둘지, 배포를 무엇이 실행할지는 아직 확정되지 않았다. GitOps 저장소도 ArgoCD
Application도 없다. 그동안 파이프라인을 멈춰 두지 않기 위해 아래 형태로 돌린다.
| 파일 | 트리거 | 하는 일 |
|---|---|---|
| `.gitea/workflows/ci.yaml` | main push, PR | `gradlew check`, Chart lint·template, 이미지 빌드·push |
| `.gitea/workflows/deploy-openshift.yaml` | 수동 실행 | 고른 환경·모드로 `helm upgrade --install` |
| `.gitea/workflows/deploy.yaml` | main push | 기존 VM docker compose 배포 |
### 이 방식이 무엇을 포기하는가
숨기지 않고 적는다. GitOps로 넘어가는 판단의 근거가 되기 때문이다.
- **클러스터 상태가 저장소와 자동으로 맞춰지지 않는다.** 누가 `oc edit`으로 고치면 그대로 남는다.
- **배포 이력이 Helm release history에만 남는다.** `git revert`로 되돌릴 수 없고 `helm rollback`을 써야 한다.
- **파이프라인이 클러스터 자격증명을 들고 있어야 한다.** 러너를 신뢰 경계 안에 두어야 한다.
- **어떤 이미지가 어느 환경에 떠 있는지 저장소만 봐서는 모른다.** 수동 실행 이력을 봐야 한다.
이 때문에 OpenShift 배포에는 자동 트리거를 두지 않았다. 사람이 환경·모드·이미지 tag를 확인하고 실행한다.
### GitOps 저장소가 생기면
1. `deploy-openshift.yaml`을 삭제한다. 클러스터 자격증명 secret도 회수한다.
2. ArgoCD Application이 이 Chart를 참조하게 하거나, Chart 자체를 배포 저장소로 옮긴다.
3. CI의 `rendered-manifests` 아티팩트가 **인수인계 형태**다. 그 시점에 무엇이 배포되고 있었는지가
거기 그대로 있으므로, 옮긴 뒤 diff로 대조한다.
4. `deploy.yaml`의 VM compose 배포를 계속 쓸지 결정한다. 스크립트가 저장소 밖(러너의
`/home/ubuntu/apps/prd-dap-gateway/deploy.sh`)에 있어 이 저장소가 내용을 모른다.
### 아직 필요한 secret
확정 전까지 CI는 이미지 빌드까지만 하고 push를 건너뛴다. 없는 secret 때문에 파이프라인 전체가
실패로 보이지 않게 하기 위해서다.
| secret | 쓰는 곳 | 없으면 |
|---|---|---|
| `REGISTRY_HOST`·`REGISTRY_USER`·`REGISTRY_PASSWORD`·`IMAGE_REPOSITORY` | CI 이미지 push | push 건너뜀 |
| `OCP_SERVER`·`OCP_TOKEN` | OpenShift 배포 | 배포 실패 |
| `OCP_CA_CERT` | API 인증서를 사내 CA가 서명했을 때 | 러너의 신뢰 저장소를 쓴다. 사내 CA면 TLS 검증 실패 |
| `OCP_NAMESPACE_DEV`·`OCP_NAMESPACE_TEST`·`OCP_NAMESPACE_PROD` | OpenShift 배포 | 배포 실패 |
## dev에서 MCP에 연결되지 않을 때
**먼저 Tool Service가 떠 있는지 확인한다.** readiness가 usable snapshot을 요구하므로, Tool Service가
없으면 MCP Pod은 Ready가 되지 못하고 Service endpoint에서 빠진다. dev는 배포마다 Pod 1개라
그 순간 그 MCP로는 아예 연결되지 않는다. "MCP가 죽었다"가 아니라 "읽을 Tool이 없다"는 뜻이다.
없으면 MCP Pod은 Ready가 되지 못하고 Service endpoint에서 빠진다.
"MCP가 죽었다"가 아니라 "읽을 Tool이 없다"는 뜻이다.
`portal` 모드에서는 Portal registry 조회부터 확인한다. registry를 못 읽으면 route 자체가 등록되지 않아
`/mcp/{routeKey}` 호출이 route key 검증에서 거부된다.
```bash
kubectl get pod -l app=<배포 이름> # 0/1 Ready이면 이 경우다
@@ -107,14 +158,15 @@ kubectl describe pod <pod> # Readiness probe 실패 사유
kubectl port-forward <pod> 9090:9090 # /actuator/toolBundles로 bundle 상태 확인
```
Tool Service가 뜨면 다음 refresh 주기(기본 30초) 안에 스스로 Ready가 된다. 재기동할 필요가 없다.
Tool Service가 뜨면 다음 refresh 주기 안에 스스로 Ready가 된다. 재기동할 필요가 없다.
`/actuator/toolBundles`는 management 포트라 NetworkPolicy가 관제 namespace로 제한하므로,
개발자는 위처럼 `port-forward`로 본다.
## 확정 전 임시값
`values.yaml`의 Tool Service 이름·이미지 경로와 `values-{env}.yaml`의 namespace·공개 host·Route 허용 CIDR은 자리표시자다.
각 파일의 `TODO` 주석을 참고해 확정 시 교체하고, 존재하지 않는 배포는 `deployments`에서 삭제한다.
`values.yaml`의 이미지 경로와 Tool Service 이름, `values-{env}.yaml`의 namespace·공개 host·Route 허용
CIDR·Portal registry 주소는 자리표시자다. 각 파일의 `TODO` 주석을 참고해 확정 시 교체하고,
존재하지 않는 배포는 `deployments`에서 삭제한다.
## 배포 시 알아야 할 앱 제약
@@ -127,14 +179,14 @@ Tool Service가 뜨면 다음 refresh 주기(기본 30초) 안에 스스로 Read
| `terminationGracePeriodSeconds`는 Spring drain보다 길어야 한다 | [architecture.md의 요청 시간 예산](../docs/architecture.md#요청-시간-예산) |
| **NetworkPolicy는 필수다. 비활성화 스위치를 두지 않았다** | [ADR-0006](../docs/decisions/ADR-0006-no-authentication-in-mcp.md) |
| 공개 path는 Route와 컨테이너 endpoint가 동일하게 사용한다 | [ADR-0009](../docs/decisions/ADR-0009-container-handles-public-mcp-path.md) |
| route↔Tool Service 매핑의 원천은 Portal이다 | [ADR-0013](../docs/decisions/ADR-0013-portal-owns-route-and-endpoint-registry.md) |
| Portal 응답 모양과 실패 처리 | [Portal-MCP 계약 v0.1](../docs/contracts/portal-mcp/protocol-v0.1-registry.md) |
| Redis key·TTL·공유 정책은 확정 전이다 | [extension-points.md](../docs/extension-points.md#운영-적용-전-필수-보완) |
| bundle은 정확히 하나다 | [ADR-0007](../docs/decisions/ADR-0007-one-mcp-per-tool-service.md) |
Route IP allowlist와 NetworkPolicy는 특히 중요하다. 이 서버는 인증·인가를 하지 않으므로 `/mcp`에
도달할 수 있다는 것이 곧 인가다. Route는 Agent Builder 고정 egress CIDR만 받고, NetworkPolicy는 Route
backend인 ingress controller와 명시한 Agent Builder namespace만 업무 포트에 허용한다.
## 미확정 항목
배포 정의를 이 저장소가 어디까지 소유하는지, namespace·registry 명명 규칙은 아직 확정되지 않았다.
[docs/extension-points.md](../docs/extension-points.md)에서 관리한다.
`portal` 모드는 여기에 하나를 더한다. **MCP는 Portal registry가 준 주소를 그대로 호출한다.** Portal이
신뢰 경계 안에 있다는 전제가 깨지면 MCP의 outbound 대상이 통째로 바뀐다([ADR-0013](../docs/decisions/ADR-0013-portal-owns-route-and-endpoint-registry.md) 전제 4).
egress 제한은 아직 없으며 [extension-points.md](../docs/extension-points.md#운영-적용-전-필수-보완)에서 관리한다.