Containerd v3에서 Insecure Registry 설정 방식 변경

Overview

containerd가 v2에서 v3로 업그레이드되면서 insecure registry 설정 방법이 크게 변경되었다. 기존의 `config.toml` 파일 내 설정 방식에서 별도 디렉토리 구조를 사용하는 방식으로 변경되었다.

 

출처 : https://github.com/containerd/containerd/releases

 

 

 

 

 

 

---

 

 

 

주요 변경사항

 

 

 

containerd v2 (기존 방식)

# /etc/containerd/config.toml
version = 2
[plugins."io.containerd.grpc.v1.cri".registry]
  [plugins."io.containerd.grpc.v1.cri".registry.mirrors]
    [plugins."io.containerd.grpc.v1.cri".registry.mirrors."harbor.somaz.link"]
      endpoint = ["http://harbor.somaz.link"]
  [plugins."io.containerd.grpc.v1.cri".registry.configs]
    [plugins."io.containerd.grpc.v1.cri".registry.configs."harbor.somaz.link".tls]
      insecure_skip_verify = true

 

 

containerd v3 (새로운 방식)

# /etc/containerd/config.toml
version = 3
[plugins."io.containerd.cri.v1.images".registry]
  config_path = "/etc/containerd/certs.d"

 

# /etc/containerd/certs.d/harbor.somaz.link/hosts.toml
server = "https://harbor.somaz.link"
[host."http://harbor.somaz.link"]
  capabilities = ["pull", "resolve", "push"]
  skip_verify = true
  plain_http = true

 

 

 

 

 

 

---

 

 

 

 

 

kubespray를 통한 설정

 

 

설정 파일 수정

# inventory/mycluster/group_vars/all/containerd.yml
containerd_registries_mirrors:
  - prefix: harbor.somaz.link
    mirrors:
      - host: http://harbor.somaz.link
        capabilities: ["pull", "resolve", "push"]
        skip_verify: true
        plain_http: true

# registry 인증 정보 별도 설정
containerd_registry_auth:
  - registry: harbor.somaz.link
    username: admin
    password: somaz123!

 

 

 

kubespray 적용

# containerd 설정만 적용
nohup ansible-playbook -i inventory/somaz-cluster/inventory.ini \
  cluster.yml --become --tags=containerd &

# 로그 확인
tail -f nohup.out

 

 

 

 

 

 

 

---

 

 

 

 

 

 

 

 

수동 설정 방법

 

 

1. 디렉토리 생성

sudo mkdir -p /etc/containerd/certs.d/harbor.somaz.link

 

 

 

2. `hosts.toml` 파일 생성

sudo tee /etc/containerd/certs.d/harbor.somaz.link/hosts.toml <<EOF
server = "http://harbor.somaz.link"
[host."http://harbor.somaz.link"]
  capabilities = ["pull", "resolve", "push"]
  skip_verify = true
  plain_http = true
EOF

 

 

 

3. 권한 설정 및 재시작

sudo chmod 644 /etc/containerd/certs.d/harbor.concrit.us/hosts.toml
sudo systemctl restart containerd

 

 

 

 

설정 확인 방법

 

 

containerd v2에서의 확인

# config.toml에서 registry 설정 확인
sudo containerd config dump | grep -A 20 "harbor.somaz.link"

 

 

 

 

containerd v3에서의 확인

# hosts.toml 파일 확인 (v3에서는 config dump에 나타나지 않음)
sudo cat /etc/containerd/certs.d/harbor.somaz.link/hosts.toml

# 실제 이미지 pull 테스트로 확인
sudo crictl pull harbor.somaz.link/library/alpine:latest

 

 

 

 

 

 

 

 

---

 

 

 

 

 

마무리

containerd v3에서는 registry 설정이 별도 디렉토리 구조로 분리되어 더욱 체계적으로 관리할 수 있게 되었다.

 

kubespray를 사용하는 환경에서는 `containerd_registries_mirrors` 변수를 통해 쉽게 설정할 수 있으며, 수동 설정 시에는 `/etc/containerd/certs.d/` 디렉토리 하위에 registry별 설정 파일을 생성하면 된다.

 

중요한 점은 v3에서는 `containerd config dump` 명령어로 registry 설정을 확인할 수 없으므로, 실제 이미지 pull 테스트나 `hosts.toml` 파일을 직접 확인하는 방법을 사용해야 한다는 것이다.

 

 

 

마지막으로 아래의 글을 확인하면 imagetools를 이용해 dockerhub 이미지를 손쉽게 harbor나 다른 private registry로 옮기는 방법을 참고할 수 있다.

2025.05.29 - [IaC/Container] - 도커 이미지 복사 자동화: buildx imagetools vs skopeo 실전 비교

 

 

 

 

 

 

---

Reference

https://github.com/containerd/containerd/discussions/6468

https://www.reddit.com/r/kubernetes/comments/187kbgn/kubespray_changing_containerd_config/