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.
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」로 버려져, 미래 시각을 따라잡을 때까지 지표와 경보가 멈춘다.
고치는 방법은 둘이다.
- k3s가 시간 동기화 뒤에 시작한다.
systemd-time-wait-sync.service는 커널 시계가 NTP로 맞춰질 때까지time-sync.target을 막는다. k3s는After=time-sync.target으로 그 뒤에 시작한다. 이 서비스는 기본으로 꺼져 있고 끝없이 기다리므로, 켜고 10분 상한을 둔다. 10분 안에 NTP에 닿지 못하면 k3s는 지금처럼 그냥 시작한다. - 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를 다시 시작한다(설치 전에는
이 파일이 없었다).