DongHyeonkaandClaude Opus 5
8062cc9a19
The guides were written before the skill existed and a scored audit found
three gaps. Fixed by a subagent running under the skill, with measured
values, versions, IPs and quoted output declared off limits.
The big one: every step showed a command and its output, and almost none
said which line to look at or what it meant. 64 interpretation pairs added
across the seven files, weighted where the reading is hardest — 20 in the
Keycloak stage, where a Secret existing and a pod having received it are
different facts.
Only the extracting form of curl appeared. Where the reader meets a response
for the first time the guides now open with curl -I or curl -v and name the
lines worth reading; -w '%{http_code}' survives only where the code is a
value being compared — two upstream nodes against each other, or the 900-run
control loop.
Listing Secret keys went from a three-stage pipe to kubectl describe secret,
which prints the key names and their byte counts in one native command
without exposing a value.
And a tool assumption: jq and yamllint are installed on neither the lab host
nor the guests. The guides now say so where JSON is read by eye, rather than
sending the reader to install something mid-diagnosis. cloud-init schema is
on the guests and is now the guest-side check.
Also removes a stray Playwright screenshot committed at the repository root
in 919547a; the evidence copy under docs/evidence/b7a-orphan-session/ is the
one the document references.
Four things the audit left standing are recorded in the agent's report rather
than papered over — notably that 04's reload measurements are stated without
a reproduction procedure, and that 05 and 06 reference each other as
prerequisites.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
실습 가이드 — 직접 쳐보면서 만드는 실험대
이 문서 묶음은 읽는 문서가 아니라 따라 치는 문서다. 기존
experiment-*.md 가 「무엇을 발견했나」를 적었다면, 여기는
「그 발견을 재현하려면 무엇을 어떤 순서로 치는가」를 적는다.
두 종류의 명령을 구별해 적는다
실무자가 터미널에서 치는 명령과, 근거를 남기려고 재는 명령은 길이도 목적도 다르다. 이 가이드는 둘을 섞지 않는다.
| 표시 | 무엇인가 |
|---|---|
| 하기 · 확인 | 실무자가 실제로 치는 형태. 짧고, 한 번에 하나씩 |
| 근거를 재려면 | 이 실험대가 문서에 남기려고 쓴 긴 형태. 평소에는 필요 없다 |
예를 들어 nginx 에러 로그가 잘렸을 때, 실무자는 잘린 걸 보고 access 로그로 넘어간다. 길이를 재서 2048인지 확인하는 것은 몰라서 재는 것이고, 알면 재지 않는다.
같은 이유로 curl 도 두 형태가 있다.
curl -I https://auth.hyeonworks.com/realms/master # 한 번 볼 때
curl -s -o /dev/null -w '%{http_code}\n' <url> # 여러 번 재서 비교할 때
이 가이드의 확인은 값을 대조해야 해서 두 번째 형태를 자주 쓴다. 실제로 터미널에서 눈으로 볼 때는 첫 번째로 충분하다.
자리표시자를 두지 않는다
<토큰> 처럼 적어 두면 그 값을 어디서 가져오는지가 문서 밖으로 나간다.
이 가이드는 값을 찾는 명령을 함께 적는다.
TOKEN=$(ssh kc-lab-1 'sudo cat /var/lib/rancher/k3s/server/node-token')
echo "${#TOKEN} 자" # 값이 아니라 길이만 확인한다
비밀은 길이나 존재 여부만 확인하고 값을 찍지 않는다. 터미널 스크롤백과 화면 공유에 남기 때문이다.
순서
앞 단계가 끝나야 다음이 된다. 각 단계 첫머리에 「이 단계가 끝나면」이 있고, 그 상태를 확인하는 명령이 있다. 그것이 통과해야 다음으로 넘어간다.
| 단계 | 무엇을 세우나 | 끝나면 확인되는 것 |
|---|---|---|
| 00 | lab host 가상화 준비 | virsh list 가 돈다 |
| 01 | VM 두 대 | 두 게스트에 SSH 가 붙는다 |
| 02 | k3s server + agent | kubectl get nodes 에 둘 다 Ready |
| 03 | 호스트 nginx 라우팅 | 밖에서 요청이 파드까지 닿는다 |
| 04 | Let's Encrypt | https:// 가 열리고 체인이 4단계 |
| 05 | Keycloak 2노드 + PostgreSQL | 관리 콘솔 로그인이 된다 |
| 06 | Prometheus · Grafana | vendor_cluster_size 가 2 |
| experiments | 실험 26건 | 각 실험의 판정 기준 |
이 가이드가 검증된 방식
읽기 전용 확인은 돌아가는 실험대에서 실제로 실행해 출력을 그대로 실었다. 버전·IP·메모리 같은 값은 지어내지 않았다.
만드는 명령은 다르다. VM 을 다시 만들거나 k3s 를 다시 깔면 지금 돌고 있는 실험대가 없어지므로, 그 명령들은 실제로 구축할 때 쓴 것을 그대로 옮겼고 결과 상태를 확인하는 것으로 대신했다. 어느 쪽인지 각 단계에 표시한다.
막혔을 때
각 단계 끝에 「막히면」 표가 있다. 거기 적힌 증상은 전부 이 실험대가
실제로 겪은 것이고, 원문은 ../evidence/ 에 있다.
지어낸 실패 사례는 없다.