결과: 병합 (2026-10-17 01:16, grafana-community/helm-charts#896), 차트 grafana 14.0.1 로 릴리스. 사실은 GitHub 의 PR·검사·릴리스 기록, 차트 소스(PR 의 바탕 커밋
71c86de1), Grafana 공식 문서, TT Lab 저장소의 커밋 기록에서 가져왔습니다. 시각은 한국 시간입니다.
목차
- 한 줄 요약
- 1. 무엇이 문제였나: 우리가 겪은 증상
- 2. 원인: 문서와 템플릿의 어느 줄인가
- 3. 무엇을 바꿨나: diff 요지
- 4. 반응: 26분
- 5. 배운 것: 오픈소스 기여 요령
- 링크
한 줄 요약
| PR | grafana-community/helm-charts#896 [grafana] Document that the admin password is only applied on first start |
| 바꾼 것 | 차트 README 에 「Admin user and password」 절 33줄, 차트 버전 14.0.0 → 14.0.1 |
| 반응 | 봇 리뷰 없음. 검사 14개 통과, 메인테이너가 「Thanks!」 와 승인 |
| 결과 | PR 공개 10-17 00:50 → 병합 01:16(26분), 28초 뒤 grafana-14.0.1 릴리스 |
1. 무엇이 문제였나: 우리가 겪은 증상
TT Lab 클러스터의 Grafana 는 kube-prometheus-stack 차트에 딸려 들어온 Grafana 차트로 돕니다. 2026-09-24, 관리자 비밀번호를 값 파일에서
빼고 admin.existingSecret 으로 Secret 을 참조하게 바꾸면서 비밀번호를 바꾸는 절차를 적어야 했습니다.
여기서 걸렸습니다. Secret 만 새 값으로 바꾸면 Grafana 는 다시 뜨지만 로그인은 옛 비밀번호로만 됩니다. 그리고 대시보드·데이터
소스를 다시 읽게 하는 사이드카는 Secret 의 새 값으로 Grafana 를 부르므로 인증에 실패하게 됩니다(차트 템플릿 기준). 그래서 절차에 「Grafana 안의 비밀번호를
grafana cli 로 먼저 바꾼다」는 단계를 넣었습니다.
같은 일을 겪은 사람이 많았습니다. 차트가 옮겨 오기 전의 옛 저장소에 같은 보고가 여러 번 있었고(grafana/helm-charts#152, #3568, #3790), 새 저장소의 README 에는 여전히 이 이야기가 없었습니다.
2. 원인: 문서와 템플릿의 어느 줄인가
차트 줄 번호는 PR 의 바탕 커밋 71c86de1 기준입니다.
- Grafana 는 관리자 비밀번호를 한 번만 읽습니다. 설정 문서의
admin_password항목은 이 값을 「Set once on first-run」 이라고 적습니다. 차트는 이 값을GF_SECURITY_ADMIN_PASSWORD환경 변수로 넘기고, DB 가 재시작을 넘어 살아남으면(영속 볼륨이나 외부 DB) 두 번째 기동부터 이 변수는 쓰이지 않습니다. - 사이드카는 Secret 의 값으로 인증합니다.
templates/_pod.tpl은 사이드카마다REQ_USERNAME·REQ_PASSWORD를 같은 Secret 에서 꺼내 넣습니다. Secret 과 DB 가 어긋나는 순간 사이드카의 reload 호출이401을 받습니다. - 값을 비우면 차트가 만든 무작위 값은
lookup에 기댑니다.templates/_helpers.tpl131–138행 의grafana.password는 클러스터에 있는 Secret 을lookup으로 읽어 그 값을 쓰고, 없으면 40자 무작위 값을 만듭니다.helm template으로 렌더하는 도구(Argo CD 등)에서는lookup이 아무것도 돌려주지 않으므로 렌더할 때마다 새 값이 나옵니다.
직접 잰 것
PR 을 쓰기 전에 문서 문장만 믿지 않고 쟀습니다. TT Lab 클러스터에 이미 받아 둔 Grafana 13.2.0 이미지로 임시 파드 하나를 띄우고,
재시작해도 남는 sqlite 데이터 디렉터리 위에서 GET /api/user 의 응답 코드를 봤습니다.
| 단계 | pw-one |
pw-two |
|---|---|---|
첫 기동, 환경 변수 pw-one |
200 | 401 |
같은 데이터로 재시작, 환경 변수 pw-two |
200 | 401 |
README 에 넣을 grafana cli … reset-admin-password --password-from-stdin 으로 pw-two |
401 | 200 |
helm template(Helm v3.18.2)을adminPassword없이 두 번 돌리면admin-password값이 두 번 다르게 나왔고,--set adminPassword=x를 주면 같았습니다.- 차트 기본 이미지(13.2.4-distroless)에는 셸이 없지만
/usr/share/grafana/bin이PATH에 있어kubectl exec로grafana cli를 바로 부를 수 있고, 차트가GF_PATHS_DATA를 넣어 두어 CLI 가 서버와 같은 DB 를 엽니다. 이것도 확인해 PR 본문에 적었습니다. - 사이드카의
401은 템플릿과 위 실측에서 따라 나오는 결론이고, 사이드카 로그로 직접 본 것은 아닙니다(미실측).
3. 무엇을 바꿨나: diff 요지
차트 README 의 기존 절 사이에 「Admin user and password」 절을 넣고, 저장소 규칙대로 문서만 바뀌어도 차트 버전을 올렸습니다.
-version: 14.0.0
+version: 14.0.1
+## Admin user and password
+...
+Grafana reads these variables only when it creates the admin user, that is on the first
+start with an empty database. When the database survives pod restarts ...
+- Changing `adminPassword`, or the password in `admin.existingSecret`, and running
+ `helm upgrade` restarts the pod but does not change the password stored in the database.
+- The sidecars ... call the Grafana reload API with the user and password from the same
+ Secret. Once the Secret and the database disagree, these calls fail with `401 Unauthorized`.
+- When neither `adminPassword` nor `admin.existingSecret` is set, ... `lookup` ...
+To rotate the password of a running installation, change it in Grafana first and then
+update the Secret (or `adminPassword`) to the same value:
비밀번호를 바꾸는 명령은 값이 셸 기록이나 프로세스 인자에 남지 않도록 표준 입력으로 넘기는 형태(--password-from-stdin)로 적었습니다.
PR 본문에는 무엇을 왜 바꾸는지, 위 실측 결과, 옛 저장소의 이슈 링크, 「문서만 바꿔 helm-unittest 는 더하지 않았다」는 설명을 적고
템플릿의 체크리스트(DCO 서명, 차트 버전 올림, 제목의 [grafana] 접두사)를 모두 채웠습니다. 본문 끝에는 AI 도움을 받아 쓰고 직접
검토했다는 문장을 넣었습니다.
4. 반응: 26분
| 시각(10-17) | 일 |
|---|---|
| 00:35 | 커밋(DCO 서명·SSH 서명) |
| 00:50 | PR 공개 |
| 00:50 ~ | 검사: 차트 시험, 생성 파일, 제목, DCO, 통합 시험 9개, Super Linter — 14개 통과 |
| 01:14 | 메인테이너 댓글 「Thanks!」 |
| 01:16 | 승인, 5초 뒤 병합 |
| 01:16 | 병합 28초 뒤 grafana-14.0.1 릴리스 |
SeaweedFS 때와 달리 리뷰 봇이 없었고, 메인테이너의 말도 한 단어였습니다. 고칠 것이 없었다는 뜻입니다. 우리가 따로 대응할 일은 없었습니다.
5. 배운 것: 오픈소스 기여 요령
- 이사한 저장소에는 옛 이슈가 남아 있습니다. 차트가 새 조직으로 옮겨 오면서 옛 저장소의 보고가 새 README 에 반영되지 않았습니다. 옛 이슈 번호를 본문에 걸면 「한 사람의 불평」이 아니라 「오래된 알려진 문제」임을 메인테이너가 바로 압니다.
- 문서 문장 한 줄과 응답 코드 표 하나를 같이 둡니다. 「Set once on first-run」 은 맞지만 짧습니다. 200/401 표는 그 문장이 실제 운영에서 무엇을 뜻하는지 보여 줍니다.
- README 에 넣는 명령은 그대로 돌려 봅니다. distroless 이미지에서
grafana cli가PATH에 있는지, 같은 DB 를 여는지까지 확인한 뒤 적었습니다. 독자가 복사해 붙일 명령이 틀리면 문서가 없느니만 못합니다. - 저장소의 규칙을 먼저 맞춥니다. 문서만 바꿔도 차트 버전을 올리는 규칙, 제목 접두사, DCO 서명. 체크리스트를 다 채운 PR 은 메인테이너가 확인할 것이 적습니다. 이번에는 병합과 릴리스까지 자동으로 이어졌습니다.
- 같은 함정을 우리 운영 문서에도 적습니다. 업스트림 문서는 모두를 위한 것이고, 운영 절차는 TT Lab 클러스터에서 그대로 따라 할 수 있어야 합니다. 이번 PR 의 회전 순서(Grafana 먼저, Secret 나중)는 우리 운영 절차에 먼저 있었습니다.
티티 한마디. 비밀번호는 처음 한 번만 외우는 친구예요. 쪽지(Secret)를 바꿔 줘도 기억은 그대로라서, 먼저 친구에게 직접 새 비밀번호를 알려 주고 그다음에 쪽지를 바꿔야 해요. 문서에 그걸 적었더니 26분 만에 「고마워!」가 왔어요.
링크
모든 자료는 2026-10-17 에 열람했습니다.
- PR: grafana-community/helm-charts#896 (병합 커밋
e45de0a3) - 릴리스: grafana-14.0.1
- Grafana 설정 문서
admin_password: https://grafana.com/docs/grafana/latest/setup-grafana/configure-grafana/#admin_password - Grafana CLI 의 관리자 비밀번호 재설정: https://grafana.com/docs/grafana/latest/administration/cli/#reset-admin-password
- 옛 저장소의 보고: grafana/helm-charts#152
- 차트 소스(바탕 커밋):
templates/_pod.tpl,templates/_helpers.tpl