diff --git a/infrastructure/host/README.md b/infrastructure/host/README.md new file mode 100644 index 0000000..ba8a22a --- /dev/null +++ b/infrastructure/host/README.md @@ -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를 다시 시작한다(설치 전에는 +이 파일이 없었다).