Files

78 lines
7.8 KiB
Markdown

---
kind: REFERENCE
slug: verify-a-build-guide-in-execution-order
title: 단계별 구축 문서는 작성 시점이 아니라 실행 순서로 검증한다
topic: lab-environment-build
topicName: 실험대 환경 구성
project: virtualization
status: 게시 전
sourceRevision: import-head 9465582b5d1630eb4ae7c4e078021486919bf6b6 · uncommitted-working-tree snapshot
source:
- final/document.md#182-이-구축에서-드러난-문서-결함의-공통-원인
- final/document.md#178-이-부의-출처와-범위
---
# 단계별 구축 문서는 작성 시점이 아니라 실행 순서로 검증한다
구축 문서는 빈 환경에서 첫 단계부터 순서대로 실행해 봐야 한다. 각 단계에서 필요한 리소스가 이미 만들어져 있는지, 명령을 어느 머신에서 실행해야 하는지까지 함께 확인한다. 이 실험대의 7단계 가이드는 명령 자체의 문법 오류보다 실행 순서와 실행 위치에서 여섯 가지 문제가 드러났다.
## 문장이 맞아도 순서가 틀릴 수 있다
이 기준이 막는 것은 각 줄이 참인데 순서대로는 못 따라가는 문서다. 「이 구축에서 드러난 문서 결함의 공통 원인」에서는 든 여섯 결함에서 틀린 명령은 하나도 없었고 전부 실제로 돌았던 것이다. 다만 구축이 끝난 뒤의 환경에서 확인한 출력이 앞 단계에 적혀 있었다. 「이 부의 출처와 범위」에서는 이 여섯이 실린 부의 범위를 구축에서 실제로 막힌 지점으로만 그었고, 막히지 않은 단계는 가이드에 있으니 여기서 반복하지 않는다고 적었다. 그래서 여섯은 가이드를 검토해 골라낸 것이 아니라, 그 단계까지 실제로 따라가다 막혀서 드러났다.
03 단계에서 /etc/nginx: No such file or directory 가 난 것은 설정 블록이 틀려서가 아니라 그 시점에 nginx 가 아직 깔려 있지 않아서다. 둘 중 어느 쪽인지는 문서를 읽어서는 알 수 없고 실제로 돌려 봐야 드러난다.
「이 구축에서 드러난 문서 결함의 공통 원인」에서는 검사할 것도 시점과 셸 둘로 갈라 적었다. 하나로 뭉뚱그리면 막힌 단계에서 무엇을 고쳐야 하는지가 안 나오기 때문이다.
## 실행 순서대로 검증한다
### 1. 검증 순서를 문서 작성 순서가 아니라 실행 순서에 맞춘다
문서를 쓴 사람은 구축이 끝난 환경에 있고 읽는 사람은 아무것도 없는 환경에서 1단계부터 시작하니, 검증도 1단계의 환경에서 시작한다.
### 2. 단계마다 그 시점에 리소스가 이미 존재하는지 따로 본다
여섯 중 셋이 여기서 깨졌다. 03 단계는 nginx 설치 단계가 없어 /etc/nginx: No such file or directory 로 막혔다. 00·03·05·06 단계는 저장소가 lab host 에 있다고 가정해 cp: cannot stat 'deploy/...' 로 막혔다. 05 단계는 BFF 가 한참 뒤에 뜨는데도 그 시점에 -l app=bff 로 리소스를 조회했다.
셋 모두 문서를 읽을 때는 보이지 않는다. 설치 명령이 빠졌다는 것도 파일이 그 기계에 없다는 것도 그 단계까지 실제로 와 봐야 드러나기 때문이다.
### 3. 단계마다 그 명령을 어느 기계에서 치는지 문서가 말하게 한다
04 단계의 확인 명령이 여기서 깨졌다. 게스트에는 Tailscale 이 없기 때문에 엣지 VM 안에서 tailnet 주소를 치면 connection refused 가 돌아온다. 명령 자체는 맞고 칠 위치가 틀렸다.
「이 부의 출처와 범위」의 구성에서 호스트는 Arch Linux 이고 게스트는 Debian 12 genericcloud 세 대다. 문서가 주체를 적지 않으면 읽는 사람은 직전 단계에서 쓰던 셸에 그대로 친다.
### 4. 나중 시점의 환경에서 확인한 명령과 출력을 앞 단계로 옮겨 적지 않는다
「이 구축에서 드러난 문서 결함의 공통 원인」에서는 여섯의 공통 원인으로 든 것이 이 하나다. 구축이 끝난 환경에서는 리소스가 전부 서 있고 저장소도 제 기계에 있으니 어떤 확인 명령이든 돈다. 그 출력을 앞 단계에 붙이면 문서의 각 줄은 참이 되고, 순서대로 따라가는 사람만 막힌다. 그래서 이 결함은 문서를 검토해서는 안 나오고 실행해야 나온다. 「이 구축에서 드러난 문서 결함의 공통 원인」에서는 여섯 결함과 그 결함을 묶은 해석을 구분했다. 여섯 결함은 실제 구축 순서에서 직접 확인했고, 하나의 공통 원인으로 묶은 부분은 그 사례들을 놓고 내린 판단이다.
## 단계별 Setup에 적용하는 기준
- 사람이 한 단계씩 따라 실행하도록 쓴 구축·운영 문서
- 앞 단계의 결과 위에 뒤 단계가 서는 문서. 기반 7단계 가이드가 그런 문서다
- 명령을 칠 기계가 둘 이상인 문서. 호스트와 게스트가 갈리면 어느 셸에서 치는지를 따로 본다
- 단계가 하나 끼어들거나 대상 환경이 바뀐 뒤
## 읽기 검토로 대체할 수 없는 부분
이 기준이 잡는 것은 순서와 위치이고 명령의 정확성은 아니다. 「이 구축에서 드러난 문서 결함의 공통 원인」에서는 적었듯 개별 명령은 전부 실제로 돌았던 것이라, 이 검사를 통과해도 오타나 잘못된 플래그나 낡은 옵션은 그대로 지나간다. 04 단계의 인증서 경로가 그런 경우다. 2026-09-17 실제 lineage 는 `live/auth.hyeonworks.com/` 이었는데 원본 가이드에는 `live/hyeonworks.com/` 이라고 적혀 있었다. 단계 순서를 맞춰도 그 잘못된 경로는 그대로 실패한다.
배포판 차이도 이 두 검사로는 안 잡힌다. 03 단계의 설정 블록에 있던 http2 on; 은 Debian 12 의 nginx 1.22 에서 unknown directive 가 됐다. 순서를 맞춰도 같은 오류가 나므로 대상 배포판에서 실제로 돌려야 드러난다.
한 번 통과한 문서가 계속 통과하지도 않는다. 단계가 하나 끼어들거나 환경이 바뀌면 같은 검사를 다시 돌린다.
2026-09-21에는 worker VM을 실제로 철거한 뒤 cloud-init → k3s → Keycloak → observability → power cycle까지 다시 올려 보는 구간 검증을 했다. 다만 빈 host에서 00단계부터 edge·인증서까지 포함해 전체 가이드를 처음부터 끝까지 다시 실행한 기록은 아직 없다. 따라서 이 기준이 전체 clean rebuild를 보장한다고 쓰지는 않는다.
다시 따라가 보지 않은 데는 까닭이 있다. 「이 부의 출처와 범위」에서는 가이드 자신도 읽기 전용 확인만 실제로 돌려 출력을 실었고 만드는 명령은 구축할 때 친 것을 그대로 옮겼다고 적었다. VM 을 다시 만들거나 k3s 를 다시 깔면 지금 돌고 있는 실험대가 없어지기 때문이다. 그래서 단계마다의 생성 명령은 「그때 이렇게 쳤다」까지이고, 지금 다시 쳐도 같은 상태가 되는지는 확인되지 않았다.
## 이번 구축에서 실제로 막힌 지점
- 03 단계 : nginx 설치 단계가 없어 /etc/nginx: No such file or directory
- 03 단계 : 설정 블록이 http2 on; 이라 Debian 12 의 nginx 1.22 에서 unknown directive
- 04 단계 : 인증서 경로가 실제 lineage 와 다르다. 실제는 `live/auth.hyeonworks.com/` 인데 원본 가이드는 `live/hyeonworks.com/` 을 적어 `nginx -t` 가 실패했다
- 00·03·05·06 단계 : 저장소가 lab host 에 있다고 가정해 cp: cannot stat 'deploy/...'
- 05 단계 : 그 단계에 없는 리소스를 -l app=bff 로 조회. BFF 는 한참 뒤에 뜬다
- 04 단계 : 확인 명령을 칠 위치가 틀렸다. 엣지 VM 안에서 tailnet 주소를 치면 connection refused
- 2026-09-21 재구축 : worker teardown/recreate부터 observability·power cycle까지 확인
- 빈 host에서 00단계부터 전체 재구축 : 아직 확인하지 않음