[K8s] K3s 클러스터 docker private registry 사용 설정

• K3s 클러스터
• rancher
• docker private registry

설정 내용

• /etc/hosts: docker private registry 도메인명 설정
• /etc/docker/daemon.json: docker 설정 파일 변경
• /etc/rancher/k3s/registries.yaml: K3s registry 클러스터 registry 설정 파일 변경

/etc/hosts

클러스터 노드 내 /etc/hosts 파일에 private docker registry 도메인에 대한 노드 IP에 대한 매핑 추가

127.0.0.1       localhost
127.0.1.1       <host-name>
172.20.10.231   <registry-domain>

# The following lines are desirable for IPv6 capable hosts
::1     ip6-localhost ip6-loopback
fe00::0 ip6-localnet
ff00::0 ip6-mcastprefix
ff02::1 ip6-allnodes
ff02::2 ip6-allrouters

• 172.20.10.231 <registry-domain>
  • <registry-domain>을 내부 IP로 직접 resolve 하도록 custom mapping 지정
  • 호스트 내에서 <registry-domain>이 오면 public DNS를 거치지 않고 클러스터 내 private registry 노드 IP로 resolve하기 위함
    • 이 설정이 없으면 public DNS를 거치거나 잘못된 주소를 찾을 수 있음
• K3s 클러스터 내 모든 노드에서 동일하게 설정해야 함

/etc/docker/daemon.json

Docker 엔진 설정 파일을 수정해 private registry와 네트워킹 환경을 정의

{
    "bip": "150.15.15.1/24",
    "default-address-pools": [
        {
            "base": "150.15.15.1/16",
            "size": 24
        }
    ],
    "default-runtime": "nvidia",
    "insecure-registries": [
        "<registry-domain>:<registry-port>"
    ],
    "registry-mirrors": [
        "<registry-domain>:<registry-port>"
    ],
    "runtimes": {
        "nvidia": {
            "args": [],
            "path": "/usr/local/nvidia/toolkit/nvidia-container-runtime"
        },
        "nvidia-cdi": {
            "args": [],
            "path": "/usr/local/nvidia/toolkit/nvidia-container-runtime.cdi"
        },
        "nvidia-legacy": {
            "args": [],
            "path": "/usr/local/nvidia/toolkit/nvidia-container-runtime.legacy"
        }
    }
}

• bip, default-address-pools
  • Docker bridge 네트워크와 기본 네트워크 풀을 직접 지정 (기본 172.17.0.0/16 과 충돌 방지)
• default-runtime
  • NVIDIA GPU가 있는 환경에서 기본 runtime을 nvidia로 지정
• insecure-registries
  • <registry-domain>:<registry-port> 연결 시 TLS 인증서 검증을 생략
  • HTTPS 인증서를 적용하지 않았거나 self-signed 인증서를 사용하는 경우 반드시 필요
• registry-mirrors
  • 기본 Docker Hub 대신 private registry를 이미지 pull 시도 우선 경로로 사용

/etc/rancher/k3s/registries.yaml

K3s는 내부적으로 containerd를 사용하므로, 해당 컨테이너 런타임에서 사용할 registry 설정을 별도로 지정

mirrors:
  "docker.io":
    endpoint:
      - "http://<registry-domain>:<registry-port>"

configs:
  "<registry-domain>:<registry-port>":
    tls:
      insecure_skip_verify: true

• mirrors : K3s 클러스터 내 docker 이미지 미러링 설정
  • docker.io(Docker Hub) 요청을 private registry로 미러링
• configs.tls.insecure_skip_verify
  • self-signed 또는 HTTP 기반 registry의 인증서 검증을 생략

결론

위 설정을 적용하면 K3s 클러스터 내에서 Docker 이미지 pull 시, private registry를 안정적으로 사용 가능

• /etc/hosts → 도메인 해석 문제 해결
• /etc/docker/daemon.json → Docker 엔진이 private registry 인식
• /etc/rancher/k3s/registries.yaml → K3s(cluster-level) containerd 설정

사내 클러스터 환경이기 때문에 아직 적용하지 않았으나, 추후 운영 시에는 가능하다면 private registry에 대해 HTTPS + 유효한 TLS 인증서를 사용하는 것이 안전할 것으로 보임