docs(host): add the owner steps for the desktop host settings

The host files need root, so agent sessions do not install them. The
owner needs one ordered list with checks and rollback for each step,
including when a Docker restart is safe.

Add infrastructure/host/README.md: why the disk and clock settings
exist, the BuildKit key meanings in Docker 29, and four steps. Pin the
tech-log images against kubelet image GC until they move to the Gitea
registry, install the k3s time-sync drop-ins, set the RTC to UTC on
the Windows side, and install the host daemon.json during a window
with no CI job, no agent gate holding the heavy lock, and workmachine
not in use.

Risk: the image pin is a manual label on the current tags; a new
deployment tag needs the label again until the registry move lands.

Verification: the commands were checked on the desktop where they do
not need root (systemctl show, timedatectl, docker buildx inspect,
docker exec gitea-runner docker ps); the sudo steps were not run.
This commit is contained in:
DongHyeonka
2026-11-11 21:52:39 +09:00
parent 7281a5654b
commit ed6ae3b0fa
+184
View File
@@ -0,0 +1,184 @@
# desktop 호스트 설정
desktop 한 대(k3s 노드 `donghyeon-system-product-name`)는 운영 k3s, Gitea
Actions runner, 에이전트 세션의 Docker 게이트를 같이 돌린다. 루트 SSD 하나와
시계 하나가 무너지면 운영까지 같이 내려간다. 이 폴더는 그 두 가지를 막는 호스트
설정 조각이다. Kubernetes 리소스가 아니므로 `kustomization.yaml`이 없고, root
권한으로 아래 경로에 설치한다.
| 파일 | 설치 경로 | 하는 일 |
| --- | --- | --- |
| `docker/daemon.json` | `/etc/docker/daemon.json` | 호스트 Docker 빌드 캐시 상한 |
| `systemd/k3s.service.d/10-after-time-sync.conf` | `/etc/systemd/system/k3s.service.d/` | k3s를 시간 동기화 뒤에 시작 |
| `systemd/systemd-time-wait-sync.service.d/10-timeout.conf` | `/etc/systemd/system/systemd-time-wait-sync.service.d/` | 동기화를 10분까지만 기다림 |
runner 안쪽 Docker 상한과 주 1회 정리는
[`../ci/gitea-runner/README.md`](../ci/gitea-runner/README.md)의 「디스크와 정리」에 있다.
## 왜 바꾸나
### 디스크 (2026-11-09 사고)
- 11-07~08 이틀 동안 에이전트 게이트의 Docker 빌드 캐시가 약 23G 쌓였다. 상한이 없었다.
- 루트 사용률 85%에서 kubelet이 안 쓰는 이미지를 지우기 시작했고, 90%(여유 10% 미만)에서
파드를 내보냈다. 내보내진 tech-log 파드의 이미지가 「안 쓰는 이미지」가 되어 지워졌고,
`imagePullPolicy: Never`라 다시 받지 못했다.
- 디스크 경보(85% 경고)는 사고 전 33시간 동안 울렸지만, 이미 kubelet 이미지 GC가 시작되는
시점이었다.
### BuildKit 상한 값
Docker 29에서 `builder.gc` 키의 뜻은 다음과 같다(moby `daemon/config/builder.go`).
| 키 | 뜻 | 호스트 값 |
| --- | --- | --- |
| `defaultReservedSpace` | 이 양 아래로는 지우지 않는다 | 5GB |
| `defaultMaxUsedSpace` | 캐시가 이 양을 넘으면 지운다(상한) | 15GB |
| `defaultMinFreeSpace` | 디스크 여유가 이 양 아래면 `reservedSpace`까지 지운다 | 35GB |
- 예전 키 `defaultKeepStorage`는 이제 `defaultReservedSpace`와 같은 뜻이다. 상한이 아니라
「최소 보존량」이라 쓰지 않는다.
- 설정 전 기본 정책은 `docker buildx inspect default`에서 Reserved 21.42GiB,
Max Used 169.5GiB, Min Free 42.84GiB였다(2026-11-11). 캐시가 21GB까지는 전혀 지워지지
않았다.
- `35GB`는 1024 단위다. 루트 228GiB에서 여유 35GiB는 사용률 약 85%, 즉 kubelet이 이미지를
지우기 시작하는 지점이다. 그 전에 빌드 캐시부터 줄인다.
- Docker 저장소를 HDD(sdb)로 옮기는 안은 빌드가 느려져 하지 않는다(소유자 결정, 2026-11-11).
### 시계 (2026-11-11 사고)
- desktop은 Windows와 이중 부팅한다(`efibootmgr`: Windows Boot Manager, Ubuntu).
- Linux는 RTC를 UTC로 읽는다(`timedatectl`: `RTC in local TZ: no`). Windows는 기본값으로
RTC에 현지 시각(KST)을 쓴다. 그래서 Windows를 쓴 뒤 Linux로 부팅하면 시계가 9시간 앞선다.
- 11-11 부팅이 그 상태로 시작했다(`journalctl --list-boots`의 시작 시각 11-12 04:33 KST).
k3s가 그 시각으로 인증서를 만든 뒤 timesyncd가 시계를 되돌렸고, 인증서가 「not yet valid」가
되어 전부 502가 됐다. `sudo systemctl restart k3s`로 복구했다.
- Prometheus도 그 사이 9시간 앞선 시각의 샘플을 저장했다. 시계가 돌아온 뒤 새 샘플이 전부
「out of bounds」로 버려져, 미래 시각을 따라잡을 때까지 지표와 경보가 멈춘다.
고치는 방법은 둘이다.
1. **k3s가 시간 동기화 뒤에 시작한다.** `systemd-time-wait-sync.service`는 커널 시계가
NTP로 맞춰질 때까지 `time-sync.target`을 막는다. k3s는 `After=time-sync.target`으로 그
뒤에 시작한다. 이 서비스는 기본으로 꺼져 있고 끝없이 기다리므로, 켜고 10분 상한을 둔다.
10분 안에 NTP에 닿지 못하면 k3s는 지금처럼 그냥 시작한다.
2. **Windows도 RTC를 UTC로 쓰게 한다.** 그러면 9시간 차이가 처음부터 생기지 않는다.
## 소유자가 실행할 명령
sudo가 필요해 에이전트 세션은 실행하지 않는다. platform-core checkout(이 PR이 병합된
main)에서 위에서부터 순서대로 실행한다. 단계마다 확인 명령과 되돌리는 법이 있다.
### 1. 운영 이미지를 kubelet 이미지 GC에서 지킨다 (재시작 없음, 바로)
tech-log 이미지를 Gitea 레지스트리로 옮기기 전까지만 쓴다. pinned 라벨이 있는 이미지는
kubelet이 지우지 않는다.
```bash
sudo k3s ctr -n k8s.io images label docker.io/library/tech-log-backend:46b1cc7 io.cri-containerd.pinned=pinned
sudo k3s ctr -n k8s.io images label docker.io/library/tech-log-frontend:7a4e201 io.cri-containerd.pinned=pinned
sudo k3s ctr -n k8s.io images ls | grep -E 'tech-log-(backend|frontend)'
```
마지막 줄의 LABELS 칸에 `io.cri-containerd.pinned=pinned`가 있어야 한다.
배포 이미지가 바뀌면 새 tag에 다시 붙인다.
되돌리기: 라벨 값을 비운다.
```bash
sudo k3s ctr -n k8s.io images label docker.io/library/tech-log-backend:46b1cc7 io.cri-containerd.pinned=
sudo k3s ctr -n k8s.io images label docker.io/library/tech-log-frontend:7a4e201 io.cri-containerd.pinned=
```
### 2. k3s를 시간 동기화 뒤에 시작한다 (재시작 없음, 다음 부팅부터)
```bash
sudo install -D -m 0644 infrastructure/host/systemd/k3s.service.d/10-after-time-sync.conf \
/etc/systemd/system/k3s.service.d/10-after-time-sync.conf
sudo install -D -m 0644 infrastructure/host/systemd/systemd-time-wait-sync.service.d/10-timeout.conf \
/etc/systemd/system/systemd-time-wait-sync.service.d/10-timeout.conf
sudo systemctl daemon-reload
sudo systemctl enable systemd-time-wait-sync.service
```
확인:
```bash
systemctl show k3s -p After -p Wants | grep -o time-sync.target
systemctl is-enabled systemd-time-wait-sync.service
systemctl show systemd-time-wait-sync.service -p TimeoutStartUSec
```
`time-sync.target` 두 줄, `enabled`, `TimeoutStartUSec=10min`이 나와야 한다. 순서는 부팅할
때만 쓰이므로 지금 k3s를 다시 시작하지 않는다. 다음 재부팅 뒤
`journalctl -b -u systemd-time-wait-sync -u k3s | head`에서 동기화가 k3s 시작보다 앞서는지 본다.
되돌리기:
```bash
sudo systemctl disable systemd-time-wait-sync.service
sudo rm /etc/systemd/system/k3s.service.d/10-after-time-sync.conf \
/etc/systemd/system/systemd-time-wait-sync.service.d/10-timeout.conf
sudo systemctl daemon-reload
```
### 3. RTC를 UTC로 맞춘다
Linux 쪽은 이미 UTC다. 확인만 한다.
```bash
timedatectl | grep -e 'RTC in local TZ' -e 'System clock synchronized'
```
`RTC in local TZ: no`가 아니면 `sudo timedatectl set-local-rtc 0`을 실행한다.
Windows 쪽(다음에 Windows로 부팅했을 때, 관리자 명령 프롬프트):
```bat
reg add "HKLM\SYSTEM\CurrentControlSet\Control\TimeZoneInformation" /v RealTimeIsUniversal /t REG_DWORD /d 1 /f
```
그 뒤 Windows 설정 → 시간 및 언어 → 날짜 및 시간 → 「지금 동기화」를 누른다. Windows가
RTC를 UTC로 다시 쓴다. Linux로 돌아와 `timedatectl`의 `RTC time`이 `Universal time`과
같은지 본다.
되돌리기(Windows): `reg delete "HKLM\SYSTEM\CurrentControlSet\Control\TimeZoneInformation" /v RealTimeIsUniversal /f`
### 4. 호스트 Docker 빌드 캐시 상한 (Docker 재시작 필요)
`systemctl restart docker`는 호스트 Docker의 컨테이너를 모두 다시 시작한다. 운영 k3s는
자기 containerd를 쓰므로 영향이 없다. 영향을 받는 것:
| 컨테이너 | 영향 |
| --- | --- |
| `gitea-runner` | 실행 중인 CI job이 실패한다. `restart: always`로 다시 뜬다 |
| `workmachine` | cokacremote 원격 작업이 끊긴다. `unless-stopped`로 다시 뜬다 |
| `chatgpt-cloudflared` | 터널이 잠깐 끊긴다. `unless-stopped`로 다시 뜬다 |
| 에이전트 세션 게이트 | 돌고 있던 Testcontainers·이미지 빌드가 실패한다 |
**안전한 때:** 아래 세 가지가 모두 참일 때.
```bash
# 1) CI job이 없다: job 컨테이너가 0개
docker exec gitea-runner docker ps --format '{{.Names}}' | wc -l
# 2) 에이전트 세션의 무거운 게이트가 없다: lock을 바로 잡을 수 있다
flock -n /tmp/claude-gates/heavy.lock true && echo free
# 3) workmachine을 지금 쓰고 있지 않다 (소유자 판단)
```
적용은 lock을 잡은 채로 한다. 재시작하는 동안 새 게이트가 시작되지 않는다.
```bash
sudo install -m 0644 infrastructure/host/docker/daemon.json /etc/docker/daemon.json
sudo dockerd --validate --config-file /etc/docker/daemon.json
flock /tmp/claude-gates/heavy.lock sudo systemctl restart docker
docker ps --format '{{.Names}} {{.Status}}'
docker buildx inspect default | sed -n '/GC Policy rule#1/,/Min Free/p'
```
`dockerd --validate`는 맨 위 키만 검사하고 `builder.gc` 안쪽 키 오타는 잡지 못한다. 그래서
마지막 줄로 실제 정책을 본다. `Reserved Space: 5GiB`, `Max Used Space: 15GiB`,
`Min Free Space: 35GiB`가 나와야 한다. 세 컨테이너가 `Up`이어야 한다.
되돌리기: `sudo rm /etc/docker/daemon.json` 뒤 같은 조건에서 Docker를 다시 시작한다(설치 전에는
이 파일이 없었다).