TT Lab
요금제

한국어

시작하기
블로그

블로그

lookup 을 시험하라던 다섯 명령 중 둘은 템플릿을 그리지 않는다: Helm 문서 PR 이 15시간 54분 만에 병합되기까지

2026-10-17 · 17 분 읽기 · #오픈소스#오픈소스 기여#Helm#쿠버네티스#문서#오픈소스 기여 기록

결과: 병합 (2026-10-17 16:45, helm/helm-www#2307), 같은 날 helm.sh 문서에 반영된 것을 확인. 사실은 GitHub 의 PR·리뷰·검사·타임라인 기록, helm-www 소스(PR 의 바탕 커밋 faf08ad0), Helm 소스(태그 v3.22.1·v4.3.1), 그리고 기여 원장의 초안에서 가져왔습니다. 시각은 한국 시간입니다.

목차

한 줄 요약
PR helm/helm-www#2307 docs: lookup only runs for template, install and upgrade
바꾼 것 현재 문서와 Helm 3 판 문서의 같은 문단 하나씩. 10줄 추가, 8줄 삭제
반응 리뷰 봇·줄 댓글 없음. 메인테이너 한 명이 /lgtm 으로 승인하고, 나중에 main 을 합쳐 검사를 다시 돌린 뒤 병합
결과 PR 공개 10-17 00:50 → 승인 02:09 → 병합 16:45, 약 15시간 54분. squash 병합(우리 계정이 저자, 메인테이너가 공동 저자)
lookup 은 템플릿을 그리는 명령에서만 불린다 Helm v3.22.1 소스 기준, 「실측」은 v3.18.2 로 잰 값 ① 템플릿을 그린다: template · install · upgrade 명령 렌더 엔진 lookup install · upgrade 클러스터 연결 실제로 조회 template, =client 연결 없음 빈 맵 → 실패 --dry-run=server 클러스터 연결 kube-system 찾음 가운데 줄과 아랫줄은 실측(helm template 으로) ② 템플릿을 그리지 않는다: rollback · uninstall rollback 이전 판의 저장된 매니페스트를 다시 적용 uninstall 저장된 릴리스의 자원을 지움 Helm 3 의 --dry-run 은 참/거짓, =server 는 오류 고치기 전 문서: template|install|upgrade|delete|rollback 다섯 명령 모두 --dry-run=server 로 lookup 을 시험하라고 함
그림: lookup 이 불리는 명령과 불리지 않는 명령

1. 무엇이 문제였나: 우리가 본 문장

먼저 솔직히 적습니다. 이번에는 TT Lab 에서 무언가 깨진 일이 없습니다. 문서를 따라 하다 막힌 것도 아니고, 문서를 읽다가 문장 하나가 소스와 맞지 않는 것을 봤습니다. 기여 원장에는 이 문장을 어떻게 찾았는지 따로 적혀 있지 않습니다. 다만 이 초안은 2편의 Grafana 차트 PR 과 같은 날, 같은 Helm 판(v3.18.2)으로 한 묶음에서 준비했습니다. 2편에서 본 것처럼 그 차트의 무작위 비밀번호는 lookup 에 기대고, helm template 으로 렌더하는 Argo CD 같은 도구에서는 lookup 이 아무것도 돌려주지 않습니다. 그 동작을 확인하려고 Helm 문서의 lookup 절을 읽다가 만난 것으로 보입니다.

Helm 공식 문서 「Template Functions and Pipelines」 의 lookup 절 끝에는 이런 문단이 있었습니다(현재 문서와 Helm 3 판 문서가 같음).

To test lookup against a running cluster, helm template|install|upgrade|delete|rollback --dry-run=server should be used instead

다섯 명령을 | 로 묶어 한 번에 적은 문장입니다. 이런 목록은 하나씩 돌려 보기 전에는 맞는지 알 수 없습니다. 실제로 돌려 보면 넷째와 다섯째가 다릅니다.

명령(Helm v3.18.2) 결과
helm template d ./chart lookup 이 빈 맵을 돌려줘 nil pointer evaluating interface {}.name 으로 렌더 실패
helm template d ./chart --dry-run=client 같음
helm template d ./chart --dry-run=server found: "kube-system" 으로 렌더
helm rollback --dry-run=server Error: invalid argument "server" for "--dry-run" flag: strconv.ParseBool: parsing "server": invalid syntax

시험 차트는 템플릿 하나에 (lookup "v1" "Namespace" "" "kube-system").metadata.name 을 그리는 것이 전부이고, 클러스터는 TT Lab 의 작은 클러스터입니다. 위 세 줄은 문장의 앞부분(template 은 =server 일 때만 클러스터를 본다)이 맞다는 확인이고, 마지막 줄이 문장의 뒷부분이 틀렸다는 증거입니다. 이 값들은 PR 본문에 적은 그대로이고, 출력 원본 파일은 따로 남기지 않았습니다(초안은 기여 원장에 있습니다). helm uninstall --dry-run=server 는 돌려 보지 않았고, 소스의 플래그 정의로만 확인했습니다(2절).

2. 원인: 소스의 어느 줄인가

문서 줄 번호는 PR 의 바탕 커밋 faf08ad0 기준이고, Helm 소스는 PR 을 쓸 때의 최신 Helm 3 릴리스 태그 v3.22.1 기준입니다.

문서 쪽

두 곳 모두 --dry-run 때 API 서버에 붙지 않는 명령으로도, --dry-run=server 로 lookup 을 시험할 명령으로도 같은 다섯 명령을 적었습니다.

lookup 은 렌더 엔진 안에서만 산다

rollback 과 uninstall 은 그 길을 타지 않는다

Helm 4 도 확인했습니다. v4.3.1 의 uninstall 은 여전히 참/거짓 플래그입니다(pkg/cmd/uninstall.go 78행). rollback 은 다른 명령과 같은 dry-run 플래그를 쓰도록 바뀌어(pkg/cmd/rollback.go 103행) =server 를 받기는 하지만, 여전히 저장된 매니페스트를 가져옵니다(pkg/action/rollback.go 207행). 플래그를 받아도 lookup 은 불리지 않으므로 고친 문장은 두 판 모두에 맞습니다. Helm 4 로는 직접 돌려 보지 않았습니다(미실측).

정리하면 문장의 잘못은 둘입니다. 하나는 「이 두 명령으로 lookup 을 시험할 수 있다」는 뜻이 틀렸다는 것(그릴 템플릿이 없음), 다른 하나는 Helm 3 에서 그 명령을 그대로 치면 플래그 오류가 난다는 것입니다.

3. 무엇을 바꿨나: diff 요지

두 파일의 같은 문단에서 delete|rollback 을 빼고, 왜 빠졌는지 한 문장을 더했습니다. 문단의 나머지는 그대로입니다.

 # docs/chart_template_guide/functions_and_pipelines.mdx (versioned_docs/version-3 의 같은 문단도 같게)
-Keep in mind that Helm is not supposed to contact the Kubernetes API Server during 
-a `helm template|install|upgrade|delete|rollback --dry-run` operation. To test `lookup` 
-against a running cluster, `helm template|install|upgrade|delete|rollback --dry-run=server`
-should be used instead to allow cluster connection.
+Keep in mind that Helm is not supposed to contact the Kubernetes API Server during
+a `helm template|install|upgrade --dry-run` operation. To test `lookup` against a
+running cluster, `helm template|install|upgrade --dry-run=server` should be used
+instead to allow cluster connection. `helm uninstall` and `helm rollback` do not
+render templates, so `lookup` is not called by these commands.

옛 줄 끝의 공백도 함께 지워져 삭제 줄 수가 문장 수보다 많아 보입니다. PR 본문에는 옛 문장 인용, 두 명령이 빠져야 하는 이유(소스 파일과 플래그 정의), 1절의 표와 ParseBool 오류, 그리고 못 한 것 둘을 적었습니다. 「yarn build 를 로컬에서 돌리지 않았다, 문단 하나만 바꾼 글자 변경이다」와 「i18n/ 아래 번역본은 고치지 않았다」입니다. 본문 끝에는 AI 도움을 받아 쓰고 직접 검토했다는 문장을 넣었습니다. helm-www 의 CONTRIBUTING 이 요구하는 DCO 서명(Signed-off-by)과 SSH 서명을 커밋에 붙였습니다.

4. 반응: 승인은 1시간 19분, 병합은 15시간 54분

시각(10-17) 일
00:43 커밋(DCO 서명·SSH 서명)
00:50 PR 공개. 크기 봇이 size/S 라벨, DCO 통과
00:50 맞춤법 검사(typos) 워크플로가 작업 하나 없이 실패로 끝남
00:52 Netlify 사이트 미리보기 준비됨
02:09 메인테이너가 /lgtm 으로 승인, 1분 뒤 has one approval 라벨
16:42 다른 기여자의 문서 PR(#2306)이 먼저 병합됨
16:43 메인테이너가 main 을 우리 브랜치에 합침 → DCO·typos·미리보기가 다시 돌아 모두 통과
16:45 squash 병합

봇은 크기 라벨과 미리보기뿐이고, 리뷰 봇이나 줄 댓글은 없었습니다. 메인테이너의 말은 /lgtm 한 마디였습니다.

눈여겨볼 것은 00:50 의 실패입니다. GitHub 는 이 실행을 「워크플로 파일 문제로 실패한 것으로 보인다」고만 표시하고, 시작된 작업이 하나도 없어 로그도 없습니다. 바탕 커밋의 typos.yml 은 평범한 두 단계짜리이고, 병합 직전에 main 을 합친 뒤 같은 워크플로가 7초 만에 통과했습니다. 그사이 main 에 들어온 커밋 둘은 문서만 바꿨습니다. 원인은 확인하지 못했습니다(미확인). 우리 쪽 변경과는 상관없는 실패로 보이지만, 솔직히 우리는 이 실패를 원장에 적지 않았고 따로 대응하지도 않았습니다. 원장의 상태는 내내 「리뷰 대기」였습니다. 메인테이너가 main 을 합쳐 검사를 새로 돌려 준 덕에 초록불로 병합되었습니다.

병합 커밋 dc74ea9b 의 저자는 우리 계정이고, 메시지는 우리 커밋 메시지에 PR 번호와 메인테이너의 Co-authored-by 한 줄이 붙은 것입니다. main 을 합친 커밋이 메인테이너 이름으로 브랜치에 들어갔기 때문입니다. 2026-10-17 에 helm.sh 의 해당 문서 페이지를 열어 고친 문장이 보이는 것을 확인했습니다.

5. 배운 것: 오픈소스 기여 요령

티티 한마디. 「이 다섯 친구한테 물어보면 돼!」 라는 쪽지가 있었는데, 넷째 친구와 다섯째 친구는 그 질문을 들을 수 없는 친구였어요. 한 명씩 직접 불러 보니 다섯째 친구는 「server 가 뭐야?」 하고 되물었죠. 쪽지에서 두 이름을 지우고 이유를 한 줄 적었더니 「좋아요」 도장을 받았어요. 다른 나라 말로 된 쪽지 열한 장은 아직 그대로라는 것도 기억해 둘게요.

링크

모든 자료는 2026-10-17 에 열람했습니다.

로그인하면 좋아요를 누를 수 있습니다

댓글

아직 댓글이 없습니다.

로그인하면 댓글을 쓸 수 있습니다