컨테이너 이미지에 레지스트리 미러 사용

이 페이지에서는 gcr.io 같은 공개 레지스트리가 아닌 레지스트리 미러에서 가져온 이미지를 사용하여 클러스터를 만들고 업그레이드하는 방법을 설명합니다. 이 기능은 클러스터 수명 주기 중 언제든지 사용 설정하거나 중지할 수 있습니다.

레지스트리 미러는 공개 레지스트리의 파일 구조를 복사하거나 미러링하는 공개 레지스트리의 로컬 복사본입니다. 예를 들어 로컬 레지스트리 미러의 경로가 172.18.0.20:5000이라고 가정합니다. containerd에서 gcr.io/kubernetes-e2e-test-images/nautilus:1.0과 같은 이미지 pull 요청이 수행되면 containerdgcr.io가 아닌 172.18.0.20:5000/kubernetes-e2e-test-images/nautilus:1.0 경로에 있는 로컬 레지스트리에서 이미지를 가져오려고 시도합니다. 이미지가 이 로컬 레지스트리 경로에 없으면 공개 레지스트리 gcr.io에서 이미지를 자동으로 가져옵니다.

레지스트리 미러를 사용할 때의 이점은 다음과 같습니다.

  • 공개 레지스트리 중단으로부터 보호합니다.
  • 포드 생성 속도가 빨라집니다.
  • 자체 취약점 스캔을 수행할 수 있습니다.
  • 공개 레지스트리에서 명령어를 실행할 수 있는 빈도에 적용되는 한도를 적용받지 않습니다.

시작하기 전에

  • 네트워크에서 Container Registry 서버가 설정되어 있어야 합니다.
  • 레지스트리 서버가 비공개 TLS 인증서를 실행할 경우 인증 기관(CA) 파일이 있어야 합니다.
  • 레지스트리 서버에 인증이 필요하면 적절한 로그인 사용자 인증 정보 또는 Docker 구성 파일이 있어야 합니다.
  • 레지스트리 미러를 사용하려면 컨테이너 런타임을 containerd로 설정해야 합니다.

Google Distributed Cloud에 필요한 모든 이미지 다운로드

bmctl 도구 및 이미지 패키지의 최신 버전을 다운로드 페이지에서 다운로드하세요.

레지스트리 서버에 컨테이너 이미지 업로드

다음을 실행하여 이미지 패키지의 이미지를 레지스트리 서버에 업로드합니다.

[HTTPS_PROXY=http://PROXY_IP:PORT] ./bmctl push images \
    --source=./bmpackages_VERSION.tar.xz \
    --private-registry=REGISTRY_IP:PORT \
    [--cacert=CERT_PATH] \
    [--need-credential=false]

다음을 바꿉니다.

  • PROXY_IP:PORT: 워크스테이션에서 레지스트리 서버로 이미지를 업로드하기 위해 프록시가 필요한 경우 프록시의 IP 주소 및 포트로 바꿉니다.
  • VERSION: 다운로드 페이지에서 다운로드한 이미지 패키지 버전으로 바꿉니다.
  • REGISTRY_IP:PORT: 비공개 레지스트리 서버의 IP 주소 및 포트로 바꿉니다.
  • CERT_PATH: 레지스트리 서버에 비공개 TLS 인증서가 사용되는 경우 CA 인증서 파일의 경로로 바꿉니다.

메시지가 표시되면 사용자 이름과 비밀번호를 입력하거나 Docker 구성 파일을 선택합니다. 레지스트리 서버에 사용자 인증 정보가 필요하지 않으면 --need-credential=false를 지정합니다.

bmctl push images 명령어에 대해 자세히 알아보려면 다음을 실행합니다.

bmctl push images --help

사용자 네임스페이스 사용

루트 네임스페이스 대신 레지스트리 서버에서 자체 네임스페이스를 사용하려는 경우 containerdregistryMirrors.endpoint의 비공개 레지스트리에 대해 API 엔드포인트를 제공한 경우 이 네임스페이스에서 가져올 수 있습니다. 엔드포인트는 일반적으로 <REGISTRY_IP:PORT>/v2/<NAMESPACE> 형식입니다. 특정 세부정보는 비공개 레지스트리 사용자 가이드에서 확인하세요.

예를 들어 172.18.0.20:5000/test-namespace/에 대한 액세스 권한만 있으면 다음 명령어를 사용하여 test-namespace 네임스페이스 아래의 모든 이미지를 업로드할 수 있습니다.

./bmctl push images \
    --source=./bmpackages_VERSION.tar.xz \
    --private-registry=172.18.0.20:5000/test-namespace \
    --username=<USERNAME> \
    --password=<PASSWORD> \
    --cacert <path/to/cert.crt>

그런 다음 클러스터 구성 파일에서 다음 항목을 추가하여 containerd가 네임스페이스에서 가져오게 할 수 있습니다.

registryMirrors:
  - endpoint: https://172.18.0.20:5000/v2/test-namespace

레지스트리 미러를 사용하도록 클러스터 구성

다음 샘플 클러스터 구성 파일은 엔드포인트가 https://172.18.0.20:5000인 로컬 레지스트리 미러에서 이미지를 가져오도록 지정합니다. 이 구성 파일의 시작 부분에 표시되는 일부 필드에 대해서는 다음 섹션에서 설명됩니다.

# Sample cluster config with registry mirror:
---
gcrKeyPath: /bmctl/bmctl-workspace/.sa-keys/my-gcp-project-anthos-baremetal-gcr.json
sshPrivateKeyPath: /root/ssh-key/id_rsa
registryMirrors:
  - endpoint: https://172.18.0.20:5000
    caCertPath: /root/ca.crt
    pullCredentialConfigPath: /root/.docker/config.json
    hosts:
      - somehost.io
      - otherhost.io
---
apiVersion: v1
kind: Namespace
metadata:
  name: cluster-admin1
---
apiVersion: baremetal.cluster.gke.io/v1
kind: Cluster
metadata:
  name: admin1
  namespace: cluster-admin1
spec:
  nodeConfig:
    containerRuntime: containerd
...

hosts 필드

containerd는 클러스터 구성 파일의 hosts 섹션에서 로컬로 미러링되는 호스트를 검색합니다. 예시 구성 파일에서 hosts 섹션에 나열되는 공개 레지스트리는 somehost.iootherhost.io입니다. 이러한 공개 레지스트리가 hosts 섹션에 표시되기 때문에 containerdsomehost.io 또는 otherhost.io에서 이미지에 대한 pull 요청이 수행될 때 비공개 레지스트리 미러를 먼저 검사합니다.

예를 들어 containerd에서 somehost.io/kubernetes-e2e-test-images/nautilus:1.0에 대한 pull 명령어를 수신한다고 가정해 보겠습니다. somehost.io가 클러스터 구성 파일의 hosts 섹션에 호스트 중 하나로 나열되기 때문에 containerd가 로컬 레지스트리 미러에서 kubernetes-e2e-test-images/nautilus:1.0 이미지를 찾습니다. somehost.iohosts 섹션에 나열되지 않은 경우 containerdsomehost.io의 로컬 미러가 존재한다는 것을 알지 못합니다. 이 경우 containerd는 이미지 미러를 검사하지 않고 somehost.io 공개 레지스트리에서 이미지를 가져옵니다.

기본적으로 Google Distributed Cloud는 gcr.io에서 이미지를 자동으로 미러링하므로 hosts 섹션에서 gcr.io를 호스트로 나열할 필요가 없습니다.

gcrKeyPath 필드

Google Distributed Cloud가 Container Registry(gcr.io)를 자동으로 사용해서 로컬 레지스트리에 표시되지 않는 이미지를 가져오도록 하려면 Container Registry 서비스 계정 키에 대한 경로를 지정해야 합니다. Google Distributed Cloud에는 다른 공개 레지스트리에 대한 키를 제공하기 위한 메커니즘이 없습니다.

이미지가 로컬 레지스트리에 표시되지 않을 때 gcr.io에서 이미지를 가져오는 기능을 사용할 계획이 없으면 클러스터 구성 파일에 gcrKeyPath를 추가할 필요가 없습니다.

caCertPath 필드

레지스트리에 비공개 전송 계층 보안(TLS) 인증서가 필요한 경우 이 필드는 서버 루트 CA 인증서 파일 경로를 사용합니다. 이 인증서 파일은 bmctl 명령어를 실행하는 머신인 관리자 워크스테이션에 있어야 합니다. 레지스트리에 비공개 TLS 인증서가 필요하지 않으면 caCertPath 필드를 비워 둘 수 있습니다.

pullCredentialConfigPath 필드

레지스트리 서버에 인증 Docker 구성 파일이 필요하지 않으면 pullCredentialConfigPath 필드를 비워 둘 수 있습니다. 이것은 bmctl 명령어를 실행하는 머신의 구성 파일 경로입니다.

사용자 클러스터에 레지스트리 미러 사용

관리자 클러스터가 레지스트리 미러에서 자동으로 이미지를 가져오도록 구성된 경우 사용자 클러스터는 자동으로 이미지를 가져오지 않습니다. 사용자 클러스터가 레지스트리 미러에서 가져오도록 하려면 레지스트리 미러를 사용하도록 클러스터 구성에 설명된 대로 개별적으로 구성해야 합니다.

레지스트리 미러 엔드포인트, 인증서, 가져오기 인증서 업데이트

레지스트리 미러 엔드포인트, 인증서, 가져오기 인증서를 업데이트하려면 다음 안내를 따르세요.

  1. 클러스터 구성 파일에서 엔드포인트, CA 인증서 파일, 가져오기 사용자 인증 정보 구성 파일의 경로를 업데이트합니다.

  2. 다음을 실행하여 변경사항을 적용합니다.

    bmctl update cluster -c CLUSTER_NAME --kubeconfig=ADMIN_KUBECONFIG
    

    다음을 바꿉니다.

    • CLUSTER_NAME: 업데이트하려는 클러스터 이름으로 바꿉니다.

    • ADMIN_KUBECONFIG: 관리자 클러스터 구성 파일의 경로로 바꿉니다.

레지스트리 미러에서 이미지를 가져왔는지 확인

이 섹션에서는 containerd가 공개 레지스트리가 아닌 로컬 레지스트리 미러에서 이미지를 가져오는지 확인하기 위해 사용할 수 있는 두 가지 방법을 설명합니다.

방법 1: 저장소 다이제스트 비교

이 방법에는 레지스트리 미러에서 이미지를 가져왔는지 확인하기 위해 저장소 다이제스트를 비교하는 작업이 포함됩니다.

레지스트리에는 저장소 다이제스트라고 부르는 고유한 식별자가 포함되고 이미지에는 컨테이너 이미지 다이제스트라고 부르는 고유한 식별자가 포함되어 있습니다. 동일한 두 이미지는 이미지의 시작 레지스트리가 다르더라도 동일한 컨테이너 이미지 다이제스트를 갖습니다. 하지만 이미지가 다른 레지스트리에서 온 경우에는 저장소 다이제스트도 다릅니다.

  1. SSH를 사용하여 클러스터 노드에 로그인합니다.

  2. 확인하려는 원본의 이미지를 선택합니다.

  3. 다음 명령어를 실행하여 사용되는 공개 레지스트리에서 이미지를 가져옵니다.

    crictl pull PUBLIC_ENDPOINT
    

    PUBLIC_ENDPOINT를 공개 레지스트리의 이미지 경로로 바꿉니다. 예를 들면 gcr.io/anthos-baremetal-release/kube-rbac-proxy:v0.6.0-gke.0입니다.

  4. 다음 명령어를 실행하여 레지스트리 미러에서 동일한 이미지를 가져옵니다.

    crictl pull MIRROR_ENDPOINT
    

    MIRROR_ENDPOINT를 레지스트리 미러의 이미지 경로로 바꿉니다. 예를 들면 10.168.15.224:5007/test-namespace/anthos-baremetal-release/kube-rbac-proxy:v0.6.0-gke.0입니다.

  5. 다음 명령어를 실행하여 이전 단계에서 가져온 두 이미지의 저장소 다이제스트를 표시합니다.

    crictl inspecti PUBLIC_OR_MIRROR_ENDPOINT | grep -A 3 repoDigests
    

    PUBLIC_OR_MIRROR_ENDPOINT를 이미지의 공개 엔드포인트 또는 이미지의 레지스트리 미러 엔드포인트로 바꿉니다. crictl inspecti 명령어는 여기에 전달되는 인수의 컨테이너 이미지 다이제스트를 확인하기 때문에 어느 것이든 사용 가능합니다. 공개 레지스트리의 이미지가 레지스트리 미러의 이미지와 동일하기 때문에 둘 다 동일한 컨테이너 이미지 다이제스트를 갖습니다.

    명령어 출력은 다음과 같이 표시됩니다.

    "repoDigests": [
      "gcr.io/anthos-baremetal-release/kube-rbac-proxy@sha256:
      27be66fb9140d83c4af8794a234b998c90e844e3414108ce72db603f4f6ea0b3",
      "10.168.15.224:5007/test-namespace/anthos-baremetal-release/kube-rbac-proxy@sha256:
      27be66fb9140d83c4af8794a234b998c90e844e3414108ce72db603f4f6ea0b3"
    ],
    
  6. 이전 단계의 출력에서 굵게 표시된 저장소 다이제스트를 비교합니다. 다이제스트가 동일하면 클러스터의 노드가 레지스트리 미러에서 가져옵니다. 그렇지 않으면 클러스터 노드가 공개 레지스트리에서 이미지를 가져옵니다.

방법 2: config.toml 파일 검사

다음 단계에 따라 config.toml 파일의 내용을 검사하여 containerd가 로컬 레지스트리에서 이미지를 가져오는지 여부를 확인할 수 있습니다.

  1. 노드에 로그인하고 /etc/containerd/config.toml 파일의 콘텐츠를 검사합니다.

  2. config.toml 파일의 plugins."io.containerd.grpc.v1.cri".registry.mirrors 섹션에서 레지스트리 서버가 endpoint 필드에 나열되어 있는지 확인합니다. 다음은 endpoint 필드가 굵게 표시된 예시 config.toml 파일에서 발췌한 부분입니다.

    version = 2
    root = "/var/lib/containerd"
    state = "/run/containerd"
    ...
    [plugins."io.containerd.grpc.v1.cri".registry]
      [plugins."io.containerd.grpc.v1.cri".registry.configs]
        [plugins."io.containerd.grpc.v1.cri".registry.configs."gcr.io"]
          [plugins."io.containerd.grpc.v1.cri".registry.configs."privateregistry2.io".tls]
            ca_file = '/etc/containerd/certs.d/privateregistry2.io/ca.crt'
      [plugins."io.containerd.grpc.v1.cri".registry.mirrors]
        [plugins."io.containerd.grpc.v1.cri".registry.mirrors."gcr.io"]
          endpoint = ["http://privateregistry.io", "http://privateregistry2.io"]
    ...
    

    레지스트리 미러가 endpoint 필드에 표시되면 노드가 공개 레지스트리가 아닌 레지스트리 미러에서 이미지를 가져옵니다.