From bfb941904077333880606777a5bc5a3bc743e6c2 Mon Sep 17 00:00:00 2001 From: wbsong111 Date: Wed, 26 Aug 2026 13:42:22 +0900 Subject: [PATCH] =?UTF-8?q?=EC=B0=A8=ED=8A=B8=20=EB=B2=84=EC=A0=84=20?= =?UTF-8?q?=EA=B0=B1=EC=8B=A0=20=EC=A0=95=EC=B1=85=EC=9D=84=20=EC=A0=95?= =?UTF-8?q?=EC=A0=95=ED=95=9C=EB=8B=A4=20=E2=80=94=20=ED=8A=B8=EB=A6=AC?= =?UTF-8?q?=EA=B1=B0=EB=8A=94=20=EC=95=B1=20=EB=B2=84=EC=A0=84=20=ED=95=84?= =?UTF-8?q?=EC=9A=94,=20CHART=5FDIRS=EB=8A=94=20=EA=B5=90=EC=B2=B4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- .../skills/catalog-update-pipeline/SKILL.md | 22 +++++++++++++++++++ catalog/image-map/README.md | 17 +++++++++----- catalog/image-map/cnpg-postgresql.env | 2 +- catalog/image-map/keycloak.env | 2 +- 4 files changed, 36 insertions(+), 7 deletions(-) diff --git a/.claude/skills/catalog-update-pipeline/SKILL.md b/.claude/skills/catalog-update-pipeline/SKILL.md index fe2ba0a..bb5d54c 100644 --- a/.claude/skills/catalog-update-pipeline/SKILL.md +++ b/.claude/skills/catalog-update-pipeline/SKILL.md @@ -13,6 +13,28 @@ chart_version_detector → chart_updater → helm_diff → breaking_change_check → generate_upgrade_doc → update_docs_file → create_pr ``` +## 언제 실행하나 — 트리거는 "새 차트"가 아니라 "앱 버전을 못 지키는 이유" + +`chart_version_detector`가 "업스트림에 새 버전이 있다"고 알려주는 건 **버전을 올릴지 +말지의 판단 근거가 아니다** — 올리기로 이미 정해진 뒤 diff·breaking 판정을 자동화하는 +도구일 뿐이다. + +차트 버전을 올리는 진짜 트리거는 **지금 쓰는 앱 버전을 유지할 수 없는 구체적 이유**다: +보안 패치·CVE 대응, 소비 앱이 요구하는 신규 기능, 벤더 EOL, 클러스터·생태계 호환성 +(예: argo-cd가 k8s 1.35를 지원 못 해 업그레이드로 이어진 PR #28 사례). **이유가 없으면 +업스트림에 새 차트가 나와 있어도 기존 버전을 그대로 쓴다** — "최신 추종" 자체는 +목표가 아니다. + +**이미지가 자체 빌드(`docker.io/paasup/*`)로 고정된 차트는 특히 주의한다.** +`custom-values.yaml`이 이미지 태그를 명시 고정하므로 차트의 `appVersion`이 올라가도 +실제 배포 버전은 안 바뀐다 — 이 경우 트리거는 `appVersion`이 아니라 **그 자체 빌드 +이미지**가 CVE 게이트를 못 넘기거나 EOL이 되는 시점이다(keycloakx 7.3.0 사례: 차트 +`appVersion`은 26.7.2로 올랐지만 실제 배포는 여전히 자체 빌드 26.7.1). + +트리거가 있어 실제로 버전을 올리면, `catalog/image-map/.env`의 `CHART_DIRS`를 +새 버전으로 **옮긴다**(추가 아님) — 옛 버전은 그 시점 태그로 동결된다. 상세 규칙은 +[catalog/image-map/README.md](../../../catalog/image-map/README.md). + ## 실행 전 반드시 확인할 것 **`CATALOG_ROOT`를 오버라이드하지 않으면 엉뚱한 경로를 본다.** 기본값이 diff --git a/catalog/image-map/README.md b/catalog/image-map/README.md index 9af7f4c..e1056d7 100644 --- a/catalog/image-map/README.md +++ b/catalog/image-map/README.md @@ -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`나 커밋 메시지에 근거를 남긴다. diff --git a/catalog/image-map/cnpg-postgresql.env b/catalog/image-map/cnpg-postgresql.env index 639f691..2d711ad 100644 --- a/catalog/image-map/cnpg-postgresql.env +++ b/catalog/image-map/cnpg-postgresql.env @@ -1,2 +1,2 @@ -CHART_DIRS="manifests/helm/cnpg-cluster/1.0.0 manifests/helm/cnpg-cluster/1.1.0" +CHART_DIRS="manifests/helm/cnpg-cluster/1.1.0" TAG_STYLE=imageName diff --git a/catalog/image-map/keycloak.env b/catalog/image-map/keycloak.env index b32a845..a33252d 100644 --- a/catalog/image-map/keycloak.env +++ b/catalog/image-map/keycloak.env @@ -1,3 +1,3 @@ -CHART_DIRS="manifests/helm/keycloakx/7.2.2" +CHART_DIRS="manifests/helm/keycloakx/7.3.0" TAG_STYLE=split TAG_BLOCK=image