템플릿 디버깅

템플릿 디버깅 (Debugging Templates)

이 문서는 렌더링된 템플릿을 디버깅하는 방법을 다뤄요. helm lint, helm template --debug, helm install --dry-run 같은 명령과 lookup 함수 디버깅 방법을 설명해요.

출처: 문서

렌더링된 템플릿은 Kubernetes API 서버로 전송되는데, API 서버는 포맷 외의 이유로 YAML 파일을 거부할 수 있기 때문에 템플릿 디버깅은 까다로울 수 있어요.

디버깅에 도움이 되는 몇 가지 명령이 있어요.

helm lint는 차트가 모범 사례를 따르는지 검증하는 기본 도구예요.
helm template --debug는 차트 템플릿 렌더링을 로컬에서 테스트해요.
helm install --dry-run --debug는 설치하지 않고 차트를 로컬에서 렌더링하지만, 클러스터에서 충돌하는 리소스가 이미 실행 중인지도 확인해요. --dry-run=server를 설정하면 차트의 모든 lookup도 서버 대상으로 추가 실행해요.
helm get manifest: 서버에 어떤 템플릿이 설치되어 있는지 확인하는 좋은 방법이에요.

YAML이 파싱에 실패하지만 생성된 내용을 보고 싶다면, YAML을 쉽게 검색하는 한 가지 방법은 템플릿에서 문제 섹션을 주석 처리한 다음 helm install --dry-run --debug를 다시 실행하는 거예요:

apiVersion: v2
# some: problem section
# {{ .Values.foo | quote }}

위 내용은 주석이 그대로 유지된 채 렌더링되어 반환돼요:

apiVersion: v2
# some: problem section
#  "bar"

이것은 YAML 파싱 오류가 막지 않고 생성된 콘텐츠를 빠르게 보는 방법을 제공해요.

lookup 함수는 템플릿 렌더링 중에 Kubernetes 리소스를 조회해요. lookup이 빈 결과를 반환하면 이유를 파악하기 어려울 수 있어요. 진단 메시지를 보려면 디버그 모드를 활성화하세요:

helm install --debug myrelease ./mychart

디버그 로깅이 활성화되면 Helm은 lookup이 빈 값을 반환할 때 apiVersion, kind, namespace, name을 기록해요:

"lookup: resource not found" — 특정 리소스가 클러스터에서 발견되지 않았어요 (단일 객체 조회, 예: lookup "v1" "ConfigMap" "default" "my-config")
"lookup: resource list not found" — 조회에 일치하는 리소스가 없어요 (목록 조회, 예: lookup "v1" "ConfigMap" "default" "")

lookup이 빈 값을 반환하는 일반적인 이유: