wbsong111
3d3d508d04
hardened-containers가 apisix 3.17 라인 EOL로 3.18.0을 게이트 PASS로 새로 발행했다
(hardened-containers 커밋 3518f98: "3.17 line went EOL"). 이게 이 카탈로그의
차트 버전 갱신 트리거다 — appVersion을 3.18로 맞추려면 차트도 2.17.0(appVersion
3.18.0)으로 올려야 한다.
breaking_change_check: breaking=false. 다만 자동 diff가 못 잡는 실제 변경을
수동으로 하나 찾았다 — ingress-controller.enabled=true로 켜서 쓰는
apisix-ingress-controller 서브차트(1.2.0→1.3.0)에 새 CRD
l4routepolicies.apisix.apache.org가 추가됐다. helm_diff는 이 서브차트를 기본값
(off)으로만 렌더링해 애초에 스캔 대상에서 빠뜨린다 — CUSTOM-README.md에 수동
적용 안내를 남기고, 이 사각지대 자체를 catalog-update-pipeline SKILL.md에
기록해 다음 리뷰 때 놓치지 않게 했다.
catalog/image-map/{apisix,apisix-ingress-controller,adc}.env의 CHART_DIRS를
2.17.0으로 교체(2.16.0은 동결)하고, apply-published-tags.py로 발행된 실제 태그
(apisix 3.18.0-20260826, ingress-controller/adc는 최근 재스캔 리빌드분)를 반영했다.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
4.7 KiB
name, description
| name | description |
|---|---|
| catalog-update-pipeline | Helm 차트 신규 버전 감지 → diff → breaking change 판정 → 업그레이드 문서 생성 파이프라인(agent/update_catalog)을 실행할 때 사용한다. "차트 새 버전 확인해줘", "업그레이드 문서 생성", "run_flow.sh 돌려줘", "helm diff 내줘", "breaking change 확인" 같은 요청이 해당한다. 개별 Skill(chart_version_detector, helm_diff, breaking_change_check 등) 단독 실행에도 적용된다. |
카탈로그 업데이트 파이프라인 실행
agent/update_catalog/의 결정론적 Python Skill 7개를 run_flow.sh가 순서대로 체이닝한다.
각 Skill은 stdout으로 JSON을 내고 다음 Skill의 입력이 된다.
chart_version_detector → chart_updater → helm_diff → breaking_change_check
→ generate_upgrade_doc → update_docs_file → create_pr
실행 전 반드시 확인할 것
CATALOG_ROOT를 오버라이드하지 않으면 엉뚱한 경로를 본다. 기본값이
/Users/songwonbin/openclaw-workspace/dip-catalog로 하드코딩돼 있다(개인 로컬 경로).
CATALOG_ROOT=/path/to/dip-catalog CHART=airflow \
bash agent/update_catalog/scripts/run_flow.sh
| 환경변수 | 의미 | 기본값 |
|---|---|---|
CATALOG_ROOT |
dip-catalog 절대 경로 | 하드코딩된 개인 경로 — 반드시 오버라이드 |
CHART |
대상 차트명 | airflow |
OUT_DIR |
중간 JSON 산출물 | $(pwd)/update_catalog (차트별 하위 디렉토리로 격리) |
DEFAULT_BRANCH |
분기 기준 브랜치 | main |
USE_CLAUDE_CLI=1 |
breaking=true 시 LLM 상세 가이드 생성 |
미설정 시 템플릿 기반 |
알려진 미완 상태
create_pr(6단계)은 run_flow.sh에서 통째로 주석 처리돼 있다 — 파이프라인이 끝까지
돌아도 브랜치·커밋·PR이 생성되지 않는다. 문서 생성까지가 실제 동작 범위다.
PR이 필요하면 결과물을 보고 직접 만들거나, 주석을 해제하기 전에 create_pr Skill의
동작을 먼저 검증한다(CLAUDE.md 기준 "실제 GitHub 연동 테스트 미완료").
deploy_validate는 SKILL.md만 있고 구현이 없다(Phase 2 예정).
개별 Skill 단독 실행
파이프라인 전체가 아니라 한 단계만 필요할 때가 많다. 입출력 스키마는
agent/update_catalog/skills/<skill>/SKILL.md에 있다.
python3 agent/update_catalog/skills/helm_diff/scripts/run.py \
--chart airflow --repo bitnami \
--chart-path /path/to/dip-catalog/manifests/helm/airflow/1.15.0 \
--from-version 1.15.0 --to-version 1.16.0
지켜야 할 설계 원칙
CLAUDE.md "설계 원칙"이 이 파이프라인을 직접 구속한다. 특히:
- helm 실행은 Python Skill이 전담한다 — LLM이 helm CLI를 직접 돌려 diff를 만들지 않는다.
- LLM 입력은 Structured JSON만 — raw helm output이나 자유 텍스트를 넘기지 않는다.
- Breaking change는 Rule Engine이 먼저 판단한다(
custom-values.yaml의 실제 사용 키 기준). LLM은breaking=true일 때 Markdown 설명 생성만 담당한다.
helm_diff 사각지대 — off-by-default 서브차트
helm_diff skill은 helm template을 커스텀 값 없이 순수 기본값으로만 렌더링한다
(-f custom-values.yaml을 쓰지 않는다). 그래서 서브차트가 기본값으로 꺼져 있고
custom-values.yaml에서만 enabled: true로 켜서 쓰는 경우, 그 서브차트의 리소스는
diff에 아예 안 잡힌다 — breaking=false가 "그 서브차트도 안전하다"는 뜻이 아니다.
실측 사례: apisix 2.16.0→2.17.0 업그레이드에서 ingress-controller.enabled: true로
켜서 쓰는 apisix-ingress-controller 서브차트(1.2.0→1.3.0)에 새 CRD
(l4routepolicies.apisix.apache.org)가 추가됐는데, helm_diff.json은 이걸 전혀
보고하지 않았다(breaking=false, warnings=0). 서브차트 자체를 로컬에서 직접
helm pull 해 비교하고서야 발견했다.
대응: custom-values.yaml이 enabled: true로 켜는 서브차트가 있으면, 그 서브차트를
helm pull <repo>/<subchart> --version <old>/<new>로 따로 받아 values.yaml·
templates/·crds/를 직접 diff한다(특히 CRD 이름 목록 — grep '^ name:' crds/*.yaml).
CRD가 추가됐다면 Helm은 helm upgrade에서 기존 설치의 CRD를 자동 갱신하지 않으므로
CUSTOM-README.md에 수동 적용 안내를 남긴다.
참고
- CLAUDE.md "자동화 Skills 작업" — 파이프라인 개요·환경변수
agent/update_catalog/docs/design/— 컴포넌트별 상세 설계(00~05)agent/update_catalog/docs/status.md— 구현 현황