--- kind: PROJECT_DECISION slug: no-docker-on-the-lab-host title: lab host 에는 Docker 를 깔지 않는다 — 이미지 저장소가 갈리고, 그 위에 네트워크 변수가 하나 더 붙는다 topic: lab-environment-build topicName: 실험대 환경 구성 project: virtualization status: 게시 전 decisionStatus: ADOPTED source: - final/document.md#281-docker를-lab-host에-설치하면-안-되는-이유 - final/document.md#282-그러면-이미지는-어떻게-넣는가 - final/document.md#280-무엇을-어디에-설치하는가 sourceRevision: 9465582b5d1630eb4ae7c4e078021486919bf6b6 --- # lab host 에는 Docker 를 깔지 않는다 — 이미지 저장소가 갈리고, 그 위에 네트워크 변수가 하나 더 붙는다 Docker 는 워크스테이션에만 두고 lab host 와 게스트에서는 뺀다. 깔면 containerd 가 둘이 되어 `docker build` 한 이미지를 k3s 가 보지 못하고, 증상이 `docker images` 에는 보이는데 파드는 `ErrImageNeverPull` 인 모양으로 나온다. ## 근거 - **호스트에 직접 깔지 않고 게스트 VM 두 대로 간다 — 관측자가 실험 대상과 함께 죽으면 안 된다** 같은 축의 결정이다. 호스트를 진입점과 하이퍼바이저로만 남긴다는 그 판단이 컨테이너 런타임 쪽에서 한 번 더 쓰였다. - **k3s server 와 agent 를 게스트 두 대에 깔고 lab host 에서 kubectl 로 본다** k3s 가 자체 containerd 를 들고 들어오는 절차다. 그 절차가 끝난 뒤에 「이미지는 어떻게 넣지」가 처음 나온다. - **Keycloak 2노드와 PostgreSQL 을 k3s 에 올리고 클러스터가 묶였는지 확인한다** 공개 이미지만 쓰는 배포라 반입이 필요 없는 쪽의 예다. 자체 빌드 이미지와 갈리는 지점을 그 절차가 보여 준다. - **Prometheus 와 Grafana 를 올려 클러스터 안을 밖에서 본다** 같은 이유로 공개 이미지를 그대로 당겨 쓴다. 노드마다 따로 반입해야 하는 일이 여기서는 생기지 않는다. - **도구가 낸 출력은 대상의 상태가 아니다 — 그 명령이 무엇을 세는지부터 가른다** `docker images` 가 보여 주는 목록이 k3s 의 이미지 목록이 아니라는 것을 그 기준이 일반화한다. ## 결정문 lab host 와 게스트에는 Docker 를 설치하지 않는다. 이미지 빌드는 워크스테이션에서만 하고, 자체 빌드 이미지는 `docker save` 로 내보내 lab host 를 경유해 게스트의 `k3s ctr images import` 로 밀어 넣는다. §280 의 설치 위치 표가 그 상태를 적는다. libvirt 와 QEMU 와 nginx 와 certbot 과 `kubectl` 은 lab host 에, k3s 는 게스트에, Docker 는 워크스테이션에만 있다. ## 판단 이유 k3s 는 자체 containerd 를 번들한다. Docker 와 무관하게 이미 완결된 스택이고, 소켓도 이미지 저장 경로도 다르다. k3s 의 소켓 : `/run/k3s/containerd/containerd.sock` Docker 의 소켓 : `/run/containerd/containerd.sock` k3s 의 이미지 저장 : `/var/lib/rancher/k3s/agent/containerd/` Docker 의 이미지 저장 : `/var/lib/docker/` Docker 를 깔면 containerd 인스턴스가 두 개가 되고, 둘은 서로의 이미지를 알지 못한다. `docker build` 한 것은 `/var/lib/docker/` 로 들어가는데 k3s 는 거기를 보지 않아서, 파드를 만들면 이미지가 없다고 한다. 그래서 증상이 `docker images` 에는 보이는데 파드는 `ErrImageNeverPull` 인 모양으로 나오고, 원인이 눈에 보이지 않아 오래 헤맨다. 충돌은 저장소 말고도 §281 이 넷을 더 든다. cgroup 드라이버 : dockerd 의 기본은 `cgroupfs` 이고 k3s 는 `systemd` 다. 한 노드에서 두 관리자가 cgroup 트리를 다툰다 iptables 와 nftables : Docker 가 `DOCKER` 와 `DOCKER-USER` 체인과 MASQUERADE 규칙을 심는다. flannel 규칙과 순서가 엉키면 파드 트래픽이 Docker 규칙에 걸린다 브리지 대역 : `docker0` 가 `172.17.0.0/16` 을 점유한다. 클러스터 서비스 대역이나 사내망과 겹치면 라우팅이 깨진다 디스크 : 같은 이미지가 두 벌 저장된다 이 실험대에는 이유가 하나 더 붙는다. lab host 에서 libvirt 가 `virbr0` NAT 와 자체 방화벽 규칙을 이미 운영하고 있어서, Docker 의 iptables 규칙이 그 위에 얹히면 게스트 네트워크가 예측 불가능해진다. 네트워크 장애를 일부러 주입하는 실험대에서 원인 불명의 네트워크 변수를 늘리면 실험 결과인지 환경 문제인지 구분할 수 없게 된다. 대안 하나를 기각했다. `k3s server --docker` 로 Docker 를 런타임으로 지정하는 방법이 과거에 있었지만, 쿠버네티스 1.24 의 dockershim 제거 이후로는 별도 `cri-dockerd` 를 요구하며 권장되지 않는다. 얻는 것이 없다. ## 영향 이미지를 넣는 길 셋 가운데 둘째로 좁아졌다. 공개 레지스트리에서 당기는 쪽과 클러스터 안에 레지스트리를 두는 쪽이 나머지 둘이고, 지금은 `ctr images import` 로 반입한다. Keycloak 과 PostgreSQL 과 Redis 처럼 공식 이미지를 쓰는 것은 아무 준비도 필요 없다. 값을 치르는 쪽은 자체 빌드 이미지인 BFF 와 token-mediator 와 echo 다. 워크스테이션에서 `docker save` 로 내보내 lab host 를 거쳐 게스트로 흘려 넣어야 하고, 그때 주의가 셋 붙는다. 노드마다 따로 반입한다 : 스케줄러가 어느 노드에 배치할지 모르기 때문에, 한쪽에만 있으면 반대편에 배치될 때 실패한다 매니페스트에 `imagePullPolicy: Never` 를 준다 : 없으면 로컬에 이미지가 있어도 레지스트리에서 당기려 시도하다 실패한다 `ctr` 이 아니라 `k3s ctr` 을 쓴다 : `k3s ctr` 은 k3s 의 containerd 소켓을 가리키는 래퍼다. 시스템에 별도 `ctr` 이 있으면 다른 소켓을 보게 되어 「성공했는데 파드는 이미지를 못 찾는」 상태가 된다 ssh 가 두 번 중첩되는 것도 값이다. 게스트가 lab host 의 libvirt NAT 뒤에 있어 워크스테이션에서 직접 붙지 못하고, lab host 의 `~/.ssh/config` 에 있는 `kc-lab-*` 별칭을 거쳐야 한다. 명령 한 줄이 `docker save` 와 바깥 ssh 와 안쪽 ssh 와 `k3s ctr images import` 를 한꺼번에 담게 된다. 되돌릴 조건은 정해 두었다. 빌드와 배포 반복이 잦아지면 셋째 길인 클러스터 내 레지스트리로 옮긴다. 지금은 자체 이미지가 셋뿐이라 반입 한 번이 레지스트리를 세우고 유지하는 것보다 싸다.