Test Overlay vs Release Package 배포 축 분리

“Prod”를 런타임 클러스터와 동일시하면 스코프가 꼬인다. 테스트 오버레이와 릴리스 패키지 퍼블리시를 축으로 분리한다.

두 축

축의미전형 산출
Test공유 클러스터 NS + kustomize/helm overlayIngress host, in-cluster health/ready, QA e2e
Prod packageRelease assets + GHCR 이미지/바이너리 publishpublish-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 TestKaniko tip + tip_roll + in-cluster smoketip을 Prod package로 취급
QA / AAquality.yaml e2e·security(또는 skip+scoped)cluster ingress E2E 발명
Doneqa+aa 통과 후 PM closeDeploying 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 ~12mARC 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.

🔗 관련 문서