wbsong111
110 lines
6.3 KiB
Markdown
110 lines
6.3 KiB
Markdown
---
|
|
name: catalog-update-pipeline
|
|
description: 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
|
|
```
|
|
|
|
## 언제 실행하나 — 트리거는 "새 차트"가 아니라 "앱 버전을 못 지키는 이유"
|
|
|
|
`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/<image>.env`의 `CHART_DIRS`를
|
|
새 버전으로 **옮긴다**(추가 아님) — 옛 버전은 그 시점 태그로 동결된다. 상세 규칙은
|
|
[catalog/image-map/README.md](../../../catalog/image-map/README.md).
|
|
|
|
## 실행 전 반드시 확인할 것
|
|
|
|
**`CATALOG_ROOT`를 오버라이드하지 않으면 엉뚱한 경로를 본다.** 기본값이
|
|
`/Users/songwonbin/openclaw-workspace/dip-catalog`로 하드코딩돼 있다(개인 로컬 경로).
|
|
|
|
```sh
|
|
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`에 있다.
|
|
|
|
```sh
|
|
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` — 구현 현황
|