service-catalog/.claude/skills/chart-to-cnpg/SKILL.md

name, description

name	description
chart-to-cnpg	카탈로그 차트가 내장한 bitnami postgresql 서브차트를 전용 cnpg-cluster 인스턴스로 전환할 때 사용한다. "postgresql 서브차트를 cnpg로 바꿔줘", "이 차트도 cnpg-cluster 쓰게 해줘", "bitnami postgresql 제거" 같은 요청, 또는 manifests/helm/<chart>/의 custom-values.yaml에서 postgresql 서브차트를 끄고 외부 DB로 돌리는 작업에 해당한다. 남은 대상은 langflow-ide, langfuse, litellm, nemo, infisical-standalone다(flowise는 2026-08 전환 완료).

카탈로그 앱 → cnpg-cluster 전환

내장 bitnami postgresql 서브차트를 끄고, 앱 전용 cnpg-cluster 인스턴스를 외부 DB로 쓰도록 바꾼다. airflow/lakekeeper/mlflow/superset 4개에서 실측 검증된 절차다(GitHub 이슈 #14).

helm/kubectl을 직접 실행하지 않는다 — 배포·검증은 scripts/deploy-test/*.sh가 전담한다 (CLAUDE.md 설계 원칙 #1). 이 skill은 파일 편집과 판단만 담당한다.

1. 대상 확인

manifests/helm/<chart>/<ver>/custom-values.yaml에 postgresql: 서브차트 설정이 있는지 본다. Chart.yaml의 dependencies에 postgresql이 있는지도 확인한다.

범위 밖: gitea·keycloak·dnsup는 서브차트가 아니라 공유 postgresql-ha를 외부 참조하며 paasup/dipup 레포 관리 대상이다 — 건드리지 않는다(doc/migrations/dipup-postgresql-ha-cnpg-handoff.md).

2. 외부 DB 연결 키 찾기

차트마다 키 구조가 다르다. values.yaml에서 externalDatabase / external* / postgresql.enabled 주변을 grep 한다. 이미 해결된 4개 사례:

차트	외부 DB 키
airflow/1.16.0	data.metadataConnection.{host,user,pass,db,port,sslmode}
lakekeeper/0.11.0	externalDatabase.{host_read,host_write,port,database,user,password}
mlflow/2.1.0	externalDatabase.{dialectDriver,host,port,user,password,database}
superset/0.13.5	supersetNode.connections.db_{host,port,user,pass,name}

서비스명 규칙: 쓰기는 <릴리스>-rw, 읽기는 <릴리스>-r. 읽기에 -ro를 쓰면 안 된다 — -ro는 replica 전용이라 권장 기준인 instances: 1에서 엔드포인트가 0개가 되어 앱이 영구 재시도에 빠진다(lakekeeper에서 실측).

3. 파일 작업 (6종)

내용은 여기 복붙하지 말고 기존 4개 사례를 열어 그대로 따른다. 문서 중복은 유지보수 부담만 는다.

파일	작업	레퍼런스
manifests/helm/<chart>/<ver>/custom-values.yaml	postgresql.enabled: false + 위 외부 DB 키. 기존 postgresql.auth.*/image.* 등 서브차트 전용 설정은 제거	4개 앱
manifests/helm/<chart>/<ver>/CUSTOM-README.md	전환 사실·사전조건(operator)·배포 순서	〃
manifests/applicationset/<app>/<ver>/applicationset.yaml	신규 — DB(syncWave 0) → 앱(syncWave 1)	manifests/applicationset/airflow/1.16.0/
manifests/applicationset/<app>/<ver>/<app>-db-values.yaml <app>-values.yaml	신규 — 비밀번호는 $INFISICAL_SECRET 플레이스홀더	〃
manifests/applicationset/<app>/<ver>/README.md	신규 — 짧게. 배포 테스트 절차는 복제하지 말고 참조만	〃
scripts/deploy-test/fixtures/<app>-deploy-test-overrides.yaml	신규 — 아래 4절 참고	scripts/deploy-test/fixtures/ 4개
doc/define-chart-resources.md	해당 차트 섹션의 postgres 리소스/볼륨 티어를 cnpg-cluster 참조로 교체	기존 4개 섹션

4. 배포 테스트 fixture

custom-values.yaml(카탈로그 권장값)은 절대 바꾸지 않고, 배포 테스트에서만 얹는 오버레이다. 격리된 테스트 네임스페이스에서 DB 연결과 무관하게 막히는 의존성만 끈다.

• ingress host 오버라이드는 필수다 — 카탈로그 기본 host가 이 클러스터의 다른 실제 배포와 겹치면 apisix에 동일 host 라우트가 2개 등록되어 운영 트래픽과 충돌한다(lakekeeper에서 실측). <app>-access-test.example.org 같은 별도 host를 쓴다.
• 외부 SSO/저장소 등 이 환경에 없는 의존성을 끈다(사례: airflow dags.gitSync.enabled: false, lakekeeper auth.oauth2 비우기, superset configOverrides.enable_oauth).
• 왜 끄는지는 fixture 파일 주석에 남긴다 — README에 중복 기술하지 않는다.

5. 배포 테스트

.claude/deploy-test-procedure.md의 "카탈로그 앱 → cnpg-cluster 전환 배포 테스트" 절을 따른다. 절차를 여기 복제하지 않는다.

APP_POD_SELECTOR는 DB에 실제로 연결하는 파드를 가리켜야 한다(미지정 시 무관한 파드가 Running이라는 이유로 통과 오판). 4개 사례: airflow component=webserver, lakekeeper app.kubernetes.io/component=catalog, mlflow app.kubernetes.io/component=tracking, superset app=superset.

6. 마무리 체크리스트

• helm template으로 postgresql 서브차트 리소스가 더 이상 렌더링되지 않는지 확인
• 읽기 엔드포인트가 -ro가 아니라 -r인지 확인(해당 차트에 읽기/쓰기 분리가 있을 때)
• fixture에 ingress host 오버라이드가 있는지 확인
• 배포 테스트 PASS + 테스트 네임스페이스/PVC/PV/Longhorn 볼륨 잔여 없음
• 운영 중인 네임스페이스(platform, defense-llm, cnpg-system)에 영향 없음
• 환경 함정은 .claude/pitfalls.md 참고 (Longhorn 볼륨 잔여, ingress host 충돌, ingressClassName 누락, 선언적 리소스 status 신뢰 금지)