Files
DongHyeonka c04d79481c docs(host): point the time-sync step at the k3s restart bundle
scripts/bootstrap/apply-k3s-restart-bundle.sh now installs the two
time-sync drop-ins and enables systemd-time-wait-sync together with the
kubelet drop-ins, so the owner restarts k3s once. Say so in step 2 and
keep the manual commands for installing only these two files.
2026-11-12 07:36:11 +09:00

189 lines
9.6 KiB
Markdown

# 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를 시간 동기화 뒤에 시작한다 (재시작 없음, 다음 부팅부터)
k3s 재시작 창을 열 때는 `scripts/bootstrap/apply-k3s-restart-bundle.sh`(`infrastructure/host/k3s`의
kubelet drop-in과 함께)가 아래 두 파일을 그대로 설치하고 `systemd-time-wait-sync`를 켠다. 그 묶음을
쓰면 이 단계는 건너뛴다. 묶음 없이 이것만 할 때는 아래 명령을 쓴다.
```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를 다시 시작한다(설치 전에는
이 파일이 없었다).