Test Overlay vs Release Package 배포 축 분리
“Prod”를 런타임 클러스터와 동일시하면 스코프가 꼬인다. 테스트 오버레이와 릴리스 패키지 퍼블리시를 축으로 분리한다.
두 축
| 축 | 의미 | 전형 산출 |
|---|---|---|
| Test | 공유 클러스터 NS + kustomize/helm overlay | Ingress host, in-cluster health/ready, QA e2e |
| Prod package | Release assets + GHCR 이미지/바이너리 publish | publish-releases workflow, 패키지 레포 — 반드시 클러스터 apply는 아님 |
테넌트 레지스트리(tenant_cd)가 비어 있으면 workflow_dispatch CD 경로가 없다 → 해당 티켓의 *prod_ = N/A**가 정상이다.
레지스트리가 deploy.yml 등을 가리키는데 제품 default branch에 파일이 없으면 tip 경로로 대체하지 않는다 — Tenant-CD-Registry-Missing-Workflow.md. 인간이 tip-path(Kaniko/build-ghcr + tip_roll)를 registry 옵션으로 고른 뒤에는 그 축만 Deploying Test 증거로 쓴다.
prod.mode=package_manual
제품이 공유 클러스터 Prod apply 없이 패키지/semver GHCR만 내는 모드면:
| 단계 | TA/QA/AA | 금지 |
|---|---|---|
| Deploying Test | Kaniko tip + tip_roll + in-cluster smoke | tip을 Prod package로 취급 |
| QA / AA | quality.yaml e2e·security(또는 skip+scoped) | cluster ingress E2E 발명 |
| Done | qa+aa 통과 후 PM close | Deploying Prod / TA prod apply 없음 — prod_* = N/A (package_manual) |
팩토리 플러그인-only 테스트 배포는 tenant_cd가 아니라 install 스크립트(예: ConfigMap + initContainer + rollout restart deploy/…)일 수 있다. 재설치 시 live bridge.json(에이전트 user id)을 샘플로 덮지 말고 기존 CM에서 보존한다. 스모크는 in-cluster Service FQDN(예: favicon.ico 200)을 쓰고, 외부 Host 302와 혼동하지 않는다.
GHCR private → releases 바이너리
익명 docker pull ghcr.io/...가 401이면:
- 런타임 이미지를 공개 base(예:
ubuntu:24.04) + Release 바이너리 initContainer로 구성 - 구형 base(bookworm 등)는 GLIBC 부족으로 바이너리 실행 실패 가능 → OS 매트릭스를 맞춘다
에이전트 SA RBAC 갭
SA가 NS/CM/Deploy만 만들고 Service / PVC / Ingress / Secret create 불가면 Pod가 Pending(볼륨·엔드포인트 없음)으로 남는다. Overlay 적용 전 SA verb 표를 점검한다.
# 개념 프로브
kubectl auth can-i create pvc -n <ns> --as=system:serviceaccount:<ns>:<sa>
kubectl auth can-i create secret -n <ns> --as=system:serviceaccount:<ns>:<sa>
kubectl auth can-i create ingress -n <ns> --as=system:serviceaccount:<ns>:<sa>Overlay 재적용 함정 (공유 Secret)
apply.sh가 Secret을 재생성하면 기존 MCP_SHARED_TOKEN(또는 동등 shared secret)이 바뀌어 backend↔mcp가 깨질 수 있다. 토큰이 이미 있으면 보존하고 idempotent -k apply만 한다. Service 스모크 포트는 문서의 containerPort(예: 8080/8800)를 쓴다 — 80 가정 금지.
레지스트리 …/healthz 호스트가 DNS에 없으면 in-cluster Service FQDN(예: backend.ns.svc.cluster.local:8080의 /api/health·/api/ready)으로 검증한다. backend-only 델타면 mcp deploy·MDL PVC reseed를 생략할 수 있다.
Self-hosted 플랫폼 라벨 러너 게이트
publish-releases의 플랫폼 전용 잡(예: build-mcp-macos → artifact *-macos-arm64)은 runs-on: [self-hosted, macOS]처럼 OS 라벨이 필수다. Linux ARC만 온라인이면 잡은 queued·runner_name 빈 채로 수 시간 대기한다 — Linux 러너로 macOS 바이너리를 대체할 수 없다.
| 신호 | 해석 | 조치 |
|---|---|---|
잡 queued + empty runner_name | 라벨 매칭 self-hosted 없음 | 플랫폼 러너 온라인 확인 전 cancel/재디스패치 금지 |
Linux ARC meta가 1s 스크립트 후 Complete job ~12m | ARC teardown wall time | “러너 죽음”과 혼동하지 않음 |
| 수 시간 queued 후 cancel | 동일 라벨 갭 재발 | 인간 Approval 게이트로 러너 준비 후 재실행 |
# 개념: 라벨 매칭 러너 존재 여부만 선확인 (잡 디스패치 전)
gh api repos/<owner>/<repo>/actions/runners --jq '.runners[] | {name,status,labels:[.labels[].name]}'
# macOS 잡에 필요한 라벨이 online 러너에 없으면 publish를 올리지 않는다GHCR publish ACL
Actions packages: write만으로 부족할 수 있다 — GHCR-Actions-Package-Write-ACL.md.
Cross-Repo Release Token & README Sync
publish-releases가 다른 레포(예: nl2sql-releases)로 README나 릴리스 메타를 동기화 푸시할 때, PAT(RELEASES_REPO_TOKEN)의 유효기간이 만료되거나 Contents write 권한이 누락되면 Invalid username or token 오류로 실패한다.
- 릴리스 워크플로우 실행 전 cross-repo 토큰의 유효기간 및 권한 상태를 선제 점검한다.
- 긴급 릴리스 시 out-of-band(수동 업로드) 후 토큰을 갱신하고 워크플로우를 redispatch하여 green 상태와 README 정합성을 맞춘다.
Tip 이미지 공급 (Kaniko)
빈번한 test-<sha> tip은 in-cluster Kaniko → GHCR을 1차로 두고, build-ghcr-images는 Prod/semver·opt-in multi-arch fallback으로 둔다. tip 태그를 publish-releases에 넣지 않는다 — In-Cluster-Kaniko-Tip-GHCR.md. initContainer 바이너리 URL을 test-*로 바꾸면 404 — Tip-Roll-Keep-Published-Binary.md. RWO 메타데이터 PVC는 Recreate — RWO-PVC-Recreate-Deploy-Strategy.md.
Doc smoke
배포 문서 마커 + kubectl client dry-run을 스크립트로 고정한다 (예: verify-deploy-docs.sh).
Live pin ↔ Git overlay sha drift
수동 upload 후 publish-releases가 같은 tag asset을 덮어쓰면 live initContainer sha와 overlay patch-*-binary.yaml pin이 어긋난다. Live Host-200이어도 git↔live 정합용 re-pin PR이 필요할 수 있다 — 라이브 블로커와 혼동하지 않는다.
MCP Host allowlist 롤아웃 순서는 MCP-Host-Allowlist-DNS-Rebinding.md.