태그 하나를 붙이려고 파일을 고쳤다

목표

대시보드의 버전과 저장 메시지를 읽고, 두 판의 차이를 사람이 읽을 수 있게 뽑고, 데이터소스를 변수로 빼 옮길 수 있게 만든 뒤, 파일이 원본이 되게 바꾸고 파일과 화면이 같은지 스스로 검사하는 도구까지 만듭니다.

왜 중요한가

대시보드를 저장소에 넣어 두기만 하면 반년 뒤에 화면과 파일이 완전히 달라져 있다. 아무도 파일을 고칠 이유가 없고 화면에서 고치는 것을 막는 것도 없기 때문이다. 파일에서 제공되게 만들면 그때부터 화면 저장이 막히고, 대시보드를 바꾸는 유일한 길이 파일이 된다 — 불편해 보이는 그 제약이 화면과 파일이 갈라질 길을 없앤다. 그리고 버전이 남아 있다는 사실과 무엇이 바뀌었는지 안다는 사실은 다르다. 저장할 때마다 바뀌는 필드를 걷어 내지 않으면 diff 는 통째로 빨개져서 아무것도 알려 주지 않는다.

단계

1. lab-start-grafana 로 Grafana 를 띄우고 /opt/lab/gfd/gfd-as-code/start.json 를 올리세요(uid gfd-code). 그 다음 1번 패널의 제목을 지금 요청률 로 바꾸고, 저장 메시지를 10자 이상 붙여 다시 저장하세요.
2. http://127.0.0.1:3000/api/dashboards/uid/gfd-code/versions 를 받아 /root/gfd-as-code/02-versions.txt 에 세 줄을 적으세요. latest= 최신 버전 번호, message= 그 버전의 저장 메시지, first_message= 버전 1 의 저장 메시지입니다. 세 값 모두 응답에 적힌 그대로 옮겨 적습니다.
3. /root/gfd-as-code/normalize.py 를 만드세요. 대시보드 JSON 파일 경로를 인자로 받아 대시보드 본문만({"dashboard": ...} 로 감싸여 있으면 벗겨서) 남기고, 최상위의 version·id·iteration 을 걷어 내고, 키를 정렬해 표준출력으로 내놓아야 합니다. 패널의 id 는 남깁니다.
4. /root/gfd-as-code/diff.sh 를 만드세요. 버전 번호 둘을 인자로 받아 두 버전을 정규화한 뒤 견주고, 같으면 아무것도 출력하지 않고 0 으로, 다르면 차이를 출력하고 0 이 아닌 값으로 끝나야 합니다. 그리고 bash /root/gfd-as-code/diff.sh 1 2 의 결과를 보고 /root/gfd-as-code/04-diff.txt 의 changed= 줄에 어느 패널의 무엇이 어떻게 바뀌었는지 20자 이상으로 적으세요.
5. 없는 데이터소스 uid 로 질의를 던져 보고 돌아오는 HTTP 코드를, 그리고 이 파드의 실제 prometheus 데이터소스 uid 를 /root/gfd-as-code/05-uid.txt 에 missing_status= 와 ds_uid= 두 줄로 적으세요. 그 다음 DS 라는 이름의 datasource 타입 템플릿 변수(대상은 prometheus)를 만들고, 두 패널이 모두 그 변수(${DS})를 가리키게 바꿔 저장하세요.
6. 지금 대시보드를 정규화해 /root/gfd-as-code/dash/gfd-code.json 에 저장하고, /root/gfd-as-code/provisioning/dashboards/lab.yml 에 그 폴더를 읽는 프로비저닝 설정을 쓴 뒤, Grafana 를 GF_PATHS_PROVISIONING=/root/gfd-as-code/provisioning 으로 다시 띄우세요. 대시보드가 파일에서 오게 되면 조회 응답의 meta.provisioned 가 참이 됩니다.
7. 지금 대시보드를 그대로 다시 저장해 보고, 돌아오는 HTTP 코드와 응답 본문의 message 를 /root/gfd-as-code/07-blocked.txt 에 status= 와 message= 로 적으세요. 그리고 procedure= 줄에 앞으로 이 대시보드를 바꾸려면 무엇을 고치고 무엇을 다시 해야 하는지 40자 이상으로 적으세요.
8. 대시보드에 gitops 태그를 붙이세요. 단 파일을 고쳐서 해야 합니다. 그리고 /root/gfd-as-code/verify.sh 를 만드세요 — 대시보드 JSON 파일 경로를 인자로 받아(기본값 /root/gfd-as-code/dash/gfd-code.json) 그 파일과 지금 화면을 정규화해 견주고, 같으면 0, 다르면 0 이 아닌 값으로 끝나야 합니다. 마지막으로 /root/gfd-as-code/08-bundle.md 에 files= (저장소에 올릴 파일 목록)와 revert= (되돌리는 방법, 40자 이상) 두 줄을 적으세요.

참고

• Grafana 는 lab-start-grafana 로 켭니다. 6단계부터는 프로비저닝 경로를 바꿔 직접 다시 띄웁니다.
• 시작 대시보드는 /opt/lab/gfd/gfd-as-code/start.json 에 있습니다. 읽기만 하세요 — 8단계에서 반례로 다시 씁니다.
• 버전 목록 응답의 각 항목에는 그 버전의 본문이 data 에 함께 들어 있습니다.
• 프로비저닝 설정은 기동할 때 한 번만 읽습니다. 파일을 고쳤는데 화면이 그대로면 다시 띄우지 않은 것입니다.
• 흔한 실수 ① 다시 띄울 때 GF_PATHS_DATA 를 빼먹는 것. 버전 이력이 통째로 사라집니다.
• 흔한 실수 ② 화면에서 고치고 파일을 안 고치는 것. 6단계 뒤에는 화면 저장이 막히므로 바로 드러납니다.
• [프로비저닝](https://grafana.com/docs/grafana/latest/administration/provisioning/) · [대시보드 JSON 모델](https://grafana.com/docs/grafana/latest/visualizations/dashboards/build-dashboards/view-dashboard-json-model/) · [대시보드 HTTP API](https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/dashboard/) · [변수](https://grafana.com/docs/grafana/latest/visualizations/dashboards/variables/)

단계 8개

1. 저장 메시지 없이 바꾸면 아무것도 남지 않는다
2. 버전 목록이 실제로 남기는 것
3. 두 판을 견줄 수 있게 만든다
4. 무엇이 바뀌었나 — 양방향으로 도는 도구
5. 옮기면 패널이 비는 이유
6. 파일이 원본이 되게 한다
7. 이제 화면에서는 저장할 수 없다
8. 응용 — 파일을 고쳐 화면을 바꾸고 둘이 같은지 검사한다