Files
platform-core/infrastructure/host/README.md
T
DongHyeonka fb5535aeb6 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.
2026-11-12 07:28:03 +09:00

9.2 KiB

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의 「디스크와 정리」에 있다.

왜 바꾸나

디스크 (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이 지우지 않는다.

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에 다시 붙인다.

되돌리기: 라벨 값을 비운다.

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를 시간 동기화 뒤에 시작한다 (재시작 없음, 다음 부팅부터)

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

확인:

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 시작보다 앞서는지 본다.

되돌리기:

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다. 확인만 한다.

timedatectl | grep -e 'RTC in local TZ' -e 'System clock synchronized'

RTC in local TZ: no가 아니면 sudo timedatectl set-local-rtc 0을 실행한다.

Windows 쪽(다음에 Windows로 부팅했을 때, 관리자 명령 프롬프트):

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·이미지 빌드가 실패한다

안전한 때: 아래 세 가지가 모두 참일 때.

# 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을 잡은 채로 한다. 재시작하는 동안 새 게이트가 시작되지 않는다.

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를 다시 시작한다(설치 전에는 이 파일이 없었다).