Files
platform-core/infrastructure/host/k3s/README.md
T
DongHyeonka e88725aab8 feat(host): add the k3s kubelet, audit and pod security drop-ins
The kubelet has no memory eviction threshold and no reservations, so
under memory pressure the kernel OOM killer picks a victim and
Postgres (oom_score_adj 985) is near the front. The API server writes
no audit log. Namespaces without labels have no Pod Security level, and
graceful node shutdown is off.

Add the files for one k3s restart: a kubelet drop-in (system 1 CPU/2Gi,
kube 0.5 CPU/1Gi, hard eviction memory 500Mi plus the two k3s disk
defaults, soft eviction 1Gi for 1m, shutdown 60s/20s), an API server
drop-in that appends the audit and admission-config flags, a Metadata
audit policy and a cluster Pod Security default (baseline, warn and
audit restricted, kube-system exempt).

Rejected: protect-kernel-defaults, recommended in review 7.3. CIS
dropped it in v1.7, and the sysctls it requires include
kernel.panic_on_oops=1, which reboots this dual-boot desktop on any
kernel oops; a reboot started the 2026-11-11 clock incident. The README
records the reason.

Risk: nothing is installed by this commit. The kubelet merges the
drop-in after k3s's 00-k3s-defaults.conf (k3s passes only --config-dir);
evictionHard lists all three keys because setting the map zeroes the
others.

Verification: the apply script's --check parses every file and asserts
the invariants (next commit).
2026-11-12 00:49:58 +09:00

6.2 KiB

k3s 재시작 묶음

k3s를 한 번만 재시작해서 다음을 같이 넣는다. 근거는 docs/reviews/2026-11-11-k3s-maturity-review.md A3·A9·A10·7.2·7.3·7.5절, 결정은 같은 문서 8절 결정 5(2026-11-12 총괄 확정)다.

파일 설치 위치 하는 일
kubelet.conf.d/50-platform-resources.conf /var/lib/rancher/k3s/agent/etc/kubelet.conf.d/ 예약(system 1 CPU·2Gi, kube 0.5 CPU·1Gi), 메모리 축출(hard 500Mi, soft 1Gi/1분), graceful node shutdown(60초, critical 20초)
config.yaml.d/60-platform-apiserver.yaml /etc/rancher/k3s/config.yaml.d/ API 서버 감사 로그와 PodSecurity admission 설정 파일 지정
server/audit.yaml /var/lib/rancher/k3s/server/audit.yaml 감사 정책: Metadata 수준(본문을 남기지 않아 Secret 값이 로그에 없다), 잦고 값 없는 요청은 뺌
server/psa.yaml /var/lib/rancher/k3s/server/psa.yaml 라벨 없는 namespace의 기본값: enforce baseline, warn·audit restricted, kube-system 예외
(W1) ../systemd/k3s.service.d/10-after-time-sync.conf /etc/systemd/system/k3s.service.d/ k3s를 시간 동기화 뒤에 시작
(W1) ../systemd/systemd-time-wait-sync.service.d/10-timeout.conf /etc/systemd/system/systemd-time-wait-sync.service.d/ 동기화를 10분까지만 기다림

그리고 /var/lib/rancher/k3s/server/manifests/local-storage.yaml.skip을 만들어 k3s가 local-path addon을 다시 덮어쓰지 않게 한 뒤, local-path StorageClass의 기본 표시를 끈다. 쓰는 PVC가 없고 (2026-11-11), 기본으로 남아 있으면 storageClassName을 빠뜨린 PVC가 루트 SSD에 Delete 정책으로 생긴다. k3s 문서의 .skip 방식이다(packaged components). 그 뒤 local-path-provisioner는 k3s 업그레이드로 갱신되지 않는다.

값을 이렇게 정한 이유

  • 예약: 노드 32GiB, 12 CPU. 파드 requests 합이 메모리 11Gi(34%)라 예약 3Gi를 빼도 여유가 크다. 예약이 없으면 Allocatable = Capacity라 파드가 노드 전부를 잡을 수 있고, 같은 호스트의 Docker 빌드·CI·데스크톱 앱과 겹치면 커널 OOM killer가 고른다.
  • evictionHard: 메모리·디스크 셋을 모두 적는다. 이 맵을 정하면 정하지 않은 항목의 기본값이 0이 된다 (mergeDefaultEvictionSettings: false). 디스크 5%는 k3s 기본값 그대로다.
  • graceful shutdown: 두 값이 0이면 기능이 꺼진다. 재부팅 때 Postgres 같은 파드가 정상 종료할 시간을 준다. 호스트 종료가 최대 60초 늦어진다. kubelet이 logind InhibitDelayMaxSec(지금 30초)가 모자라면 스스로 늘린다. 적용 뒤 systemd-analyze cat-config systemd/logind.conf로 확인한다.
  • PSA 기본값은 restricted가 아니라 baseline이다. 라벨 없는 namespace는 default·kube-public· kube-node-lease뿐이고 파드가 없다. 플랫폼 namespace는 모두 자기 라벨이 있어 영향이 없다.

넣지 않은 것: protect-kernel-defaults

7.3절에서 권했지만 이 묶음에서 뺐다.

  • CIS Kubernetes Benchmark는 v1.7부터 이 항목(옛 4.2.6)을 뺐다.
  • 켜려면 kubelet이 기대하는 sysctl을 먼저 맞춰야 한다(k3s hardening 가이드: vm.overcommit_memory=1, kernel.panic=10, kernel.panic_on_oops=1, vm.panic_on_oom=0). kernel.panic_on_oops=1은 커널 oops가 한 번만 나도 10초 뒤 호스트를 재부팅한다. 이 기계는 GPU 드라이버가 있는 데스크톱이고 이중 부팅이며, 재부팅 자체가 11-11 시계 사고의 출발점이었다. vm.overcommit_memory=1은 호스트 전체의 메모리 할당 방식을 바꾼다.
  • 얻는 것(kubelet이 커널 값을 못 바꾸게 함)보다 잃는 것이 커서 뺀다. 다시 넣으려면 sysctl 변경을 따로 소유자가 정한다.

적용 (소유자, 한 번)

전제:

  • desktop, 이 디렉터리와 W1의 infrastructure/host/systemd/*가 둘 다 있는 platform-core main checkout (W1 PR 병합 뒤). 없으면 스크립트가 MISSING …(W1)을 찍고 멈춘다.
  • CI job과 에이전트 게이트가 없는 때. k3s 재시작 중 1~2분 API가 멈춘다. k3s는 KillMode=process라 컨테이너는 계속 돈다(파드가 재시작되지는 않는다).
cd /home/donghyeon/workspace/platform && git pull --ff-only
bash scripts/bootstrap/apply-k3s-restart-bundle.sh --check
sudo bash scripts/bootstrap/apply-k3s-restart-bundle.sh --execute

--execute가 하는 일:

  1. 클러스터 Ready와 health 셋(Keycloak OIDC discovery, tech-log health, Gitea healthz)을 본다.
  2. 바꿀 파일을 /var/backups/platform-k3s-restart-bundle/<시각>/에 복사하고, datastore를 sqlite3 .backup으로 복사한다(token도 같이, 모드 0600, PRAGMA integrity_check 출력).
  3. 파일을 설치하고 systemd-time-wait-sync를 켠 뒤 k3s를 한 번 재시작한다.
  4. 확인: kubelet configz(예약·eviction·shutdown 값), 감사 로그가 쓰이는지, default namespace에서 privileged 파드가 서버 dry-run으로 거절되는지, health 셋이 200인지, time-wait-sync가 enabled인지.
  5. 3·4 중 하나라도 실패하면 백업한 파일을 되돌리고 새 파일을 지운 뒤 k3s를 다시 재시작한다.
  6. 다 통과하면 local-path의 기본 표시를 끈다.

마지막 줄이 K3S RESTART BUNDLE APPLIED여야 한다.

같은 재시작 창에 이어서 할 것

PriorityClass를 파드에 붙이는 변경과 Keycloak 이미지 고정은 파드 재시작을 부르므로 이 묶음 바로 뒤에 한다(docs/runbooks/ 재시작 창 절차). Postgres의 priorityClassName·Guaranteed는 W1 범위다.

되돌리기 (수동)

B=/var/backups/platform-k3s-restart-bundle/<시각>
sudo rm -f /var/lib/rancher/k3s/agent/etc/kubelet.conf.d/50-platform-resources.conf \
  /etc/rancher/k3s/config.yaml.d/60-platform-apiserver.yaml \
  /var/lib/rancher/k3s/server/manifests/local-storage.yaml.skip
sudo systemctl daemon-reload && sudo systemctl restart k3s
kubectl annotate storageclass local-path storageclass.kubernetes.io/is-default-class=true --overwrite

audit.yaml·psa.yaml는 참조가 없어지면 쓰이지 않으므로 남겨도 된다. W1 시간 동기화 되돌리기는 infrastructure/host/README.md 2단계를 따른다.