차트 버전 갱신 정책을 정정한다 — 트리거는 앱 버전 필요, CHART_DIRS는 교체

catalog/image-map/README.md는 "이미지 하나가 여러 버전 디렉토리에 걸리는 것이
정상"이라 서술했지만, 실측하니 근거가 반대였다. 다버전 동시 매핑은 카탈로그
전체에서 cnpg-postgresql 하나뿐이었고, 그 cnpg-cluster 1.0.0/1.1.0도 "병행 유지"
근거가 없이 같은 태그를 쓰고 있었다 — 매핑 갱신 시 옛 버전을 안 지운 결과에
가까웠다. 반대로 argocd.env는 이미 argo-cd/10.4.0 하나만 가리키고 7.8.11은
빠져 있는데, 이건 사고가 아니라 의도적 정책이었다(MEMORY.md: "직전 버전을
없애는 결정이라 PR #28에서 보류했다" — 동결 자체는 이미 관행이었다).

정정한 정책: CHART_DIRS는 기본적으로 최신 버전 하나만 가리키고, 차트를
올리면 이 값을 교체한다(추가 아님) — 옛 버전은 그 시점 태그로 동결된다.
그리고 차트를 올리는 트리거 자체도 "업스트림에 새 차트가 있다"가 아니라
"지금 쓰는 앱 버전을 유지 못 하는 구체적 이유"(CVE·EOL·필수 기능·호환성)여야
한다 — catalog-update-pipeline SKILL.md에 이 기준이 없었어서 추가했다.

keycloak.env(7.2.2→7.3.0)·cnpg-postgresql.env(1.0.0 제거)를 새 정책에 맞춰
바로잡는다 — keycloakx 7.3.0 업그레이드(#51) 때 빠뜨렸던 매핑 갱신이기도 하다.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
wbsong111
2026-08-26 13:42:22 +09:00
parent b94db8828c
commit bfb9419040
4 changed files with 36 additions and 7 deletions
+12 -5
View File
@@ -22,8 +22,15 @@ hardened-containers 가 알아야 하므로, 레포 분리 시 이 지식을 카
| `TAG_STYLE` | `imageName`(단일 필드 문자열) \| `split`(registry/repository/tag 분리) |
| `TAG_BLOCK` | `split`일 때 태그가 있는 블록의 점 구분 경로 (기본 `image`) |
카탈로그는 한 차트의 여러 버전을 동시에 보관하는 "버전 보관소"다 — **이미지 하나가
여러 버전 디렉토리에 걸리는 것이 정상**이다. 버전 디렉토리를 만들 때 이 매핑도
함께 갱신한다. 빠뜨리면 `scripts/build/patch-catalog-tag.py`가 그 파일을 검사조차
지 않아 낡은 태그가 조용히 남는다(실측: `cnpg-postgresql``cnpg-cluster/1.0.0`
매핑돼 있어 `1.1.0`이 낡은 태그로 남은 사고가 있었다).
`CHART_DIRS`는 기본적으로 **최신 버전 디렉토리 하나만** 가리킨다. 차트를
업그레이드할 때 이 값을 **교체**한다 — 추가가 아니다. 버전은 업그레이드 시점
태그로 동결된 채 카탈로그에 남는다(정적 카탈로그는 "버전 보관소"라 디렉토리 자체는
지우지 않는다 — 다만 자체 빌드 태그 자동 반영 대상에서는 빠진다). 근거:
`MEMORY.md``argo-cd/7.8.11` 동결 사례(PR #28) — 차트 버전 갱신은 결국 배포
중인 앱 버전 관리와 묶여 간다. 차트 버전을 언제 올리는지(트리거) 자체는
[catalog-update-pipeline SKILL.md](../../.claude/skills/catalog-update-pipeline/SKILL.md)
"언제 실행하나" 절 참고.
여러 버전을 **의도적으로 병행 추적**해야 하는 예외적 케이스(같은 이미지를 쓰는 두
메이저 라인을 동시에 지원해야 하는 경우 등)만 공백으로 여러 디렉토리를 나열한다 —
이 경우 왜 병행이 필요한지 `CUSTOM-README.md`나 커밋 메시지에 근거를 남긴다.