wbsong111
2417655987
apisix에 얹는 keycloak-authz 커스텀 플러그인 오버레이는 hardened-containers 표준 파이프라인 밖에서 별도로 빌드돼 같은 리포지토리에 -keycloak-authz 접미사를 붙여 추가로 push된다. published.json에는 이 접미사 태그가 절대 안 잡혀서, apply-published-tags.py가 무필터로 ref를 그대로 적용하는 지금 방식으로는 카탈로그가 순정(keycloak-authz 없는) 태그를 가리키게 되는 실질적 회귀가 있었다 (manifests/helm/apisix/2.17.0/custom-values.yaml이 실제로 이 상태였다). scripts/build/resolve-apisix-keycloak-authz-tag.py를 새로 만들어 apply-published-tags.py가 읽기 전에 published.json 사본의 apisix 항목을 제자리에서 고쳐 쓴다 — base 태그에 -keycloak-authz 버전이 실제로 있으면 그걸로 교체하고, 없으면 apisix 항목 자체를 지워 표준 "없다" 분기가 자연히 건너뛰게 한다(순정 태그로 되돌리는 일은 없다). apply-published-tags.py는 한 줄도 안 건드렸다. catalog-tag-update.yml에 이 전처리를 한 스텝만 끼워 넣고, 즉시 1회 실행해 2.17.0의 회귀를 이 커밋에서 바로 고쳤다(3.18.0-security-hardened-20260826 → ...-keycloak-authz). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
54 lines
3.6 KiB
Markdown
54 lines
3.6 KiB
Markdown
# 이미지 → 차트 매핑
|
|
|
|
hardened-containers 레포가 발행하는 자체 빌드 이미지가 이 카탈로그의 어느 차트·어느 필드를
|
|
가리키는지 선언한다. **이 디렉토리에 파일이 있는 이미지 이름 = 이 카탈로그가 추적하는
|
|
자체 빌드 이미지 목록**이다(`.github/workflows/catalog-tag-update.yml`이 이 목록을 기준으로
|
|
동작한다).
|
|
|
|
이관 배경: 이 정보는 원래 hardened-containers(당시 `images/<image>/catalog.env`)에 있었다.
|
|
"어느 이미지를 쓰는가"는 카탈로그가 알아야 하고 "그 이미지를 어떻게 만드는가"는
|
|
hardened-containers 가 알아야 하므로, 레포 분리 시 이 지식을 카탈로그 쪽으로 옮겼다 —
|
|
[doc/migrations/self-build-images-to-hardened-containers.md](../../doc/migrations/self-build-images-to-hardened-containers.md)
|
|
참고.
|
|
|
|
## 파일 형식 — `<image>.env`
|
|
|
|
`<image>`는 hardened-containers 레포의 `images/<image>/` 디렉토리명과 정확히 같아야 한다
|
|
(`published.json`의 키도 같다).
|
|
|
|
| 키 | 의미 |
|
|
| --- | --- |
|
|
| `CHART_DIRS` | 이 이미지의 태그를 참조하는 차트 버전 디렉토리 (공백 구분, 여러 개 가능) |
|
|
| `TAG_STYLE` | `imageName`(단일 필드 문자열) \| `split`(registry/repository/tag 분리) |
|
|
| `TAG_BLOCK` | `split`일 때 태그가 있는 블록의 점 구분 경로 (기본 `image`) |
|
|
|
|
`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`나 커밋 메시지에 근거를 남긴다.
|
|
|
|
## 발행 경로가 published.json 하나로 안 끝나는 이미지
|
|
|
|
원칙은 "`published.json`의 `ref`를 그대로 믿고 반영한다"지만, 일부 이미지는
|
|
hardened-containers의 표준 파이프라인 밖에서 만들어져 `published.json`에 안
|
|
잡힌다. 현재 유일한 사례: **apisix의 keycloak-authz 커스텀 플러그인 오버레이**
|
|
— 표준 빌드 뒤에 별도 프로세스가 같은 리포지토리에 `-keycloak-authz` 접미사를
|
|
붙여 추가로 push한다.
|
|
|
|
이런 이미지는 `published.json`을 그대로 신뢰하지 않고, `catalog-tag-update.yml`이
|
|
그 이미지 전용 전처리 스크립트로 published.json 사본을 먼저 고쳐 쓴 뒤에야 표준
|
|
반영 로직(`apply-published-tags.py`)이 돈다 — apisix의 경우
|
|
`scripts/build/resolve-apisix-keycloak-authz-tag.py`. **원하는 태그가 실제로
|
|
존재할 때만 대체하고, 없으면 그 이미지를 이번 실행에서 건너뛴다** — 접미사 없는
|
|
순정 태그로 되돌리는 일은 없다(순정으로 돌아가면 그 이미지가 실제로 요구하는
|
|
커스텀 기능이 빠지는 회귀가 된다). 다음에 비슷한 예외가 생기면 이 패턴을
|
|
참고한다.
|