Docker에서 containerd 노드 이미지로 마이그레이션

표준

이 페이지에서는 Google Kubernetes Engine(GKE) Standard 클러스터 및 노드 풀을 Docker에서 containerd 컨테이너 런타임을 사용하는 노드 이미지로 마이그레이션하는 방법을 보여줍니다.

개요

Kubernetes 노드는 컨테이너 런타임을 사용해서 포드에서 실행 중인 컨테이너를 시작, 관리, 중지합니다. containerd 런타임은 GKE에서 지원되는 산업 표준 컨테이너 런타임입니다.

containerd 런타임은 GKE 기능을 확장할 수 있는 gVisor 및 이미지 스트리밍과 같은 다양한 기능을 구현할 수 있는 레이어 추상화를 제공합니다. containerd 런타임은 Docker 런타임보다 리소스 효율과 보안성이 높은 것으로 간주됩니다.

컨테이너 런타임을 마이그레이션하려면 다음 안내를 따르세요.

Docker 런타임을 사용하는 노드 식별
마이그레이션 영향 확인
노드 이미지 변경

시작하기 전에

시작하기 전에 다음 태스크를 수행했는지 확인합니다.

Google Kubernetes Engine API를 사용 설정합니다.

Google Kubernetes Engine API 사용 설정

이 태스크에 Google Cloud CLI를 사용하려면 gcloud CLI를 설치한 후 초기화합니다. 이전에 gcloud CLI를 설치한 경우 gcloud components update를 실행하여 최신 버전을 가져옵니다.
참고: 기존 gcloud CLI 설치의 경우 compute/region 및 compute/zone 속성을 설정해야 합니다. 기본 위치를 설정하면 gcloud CLI에서 One of [--zone, --region] must be supplied: Please specify location과 같은 오류를 방지할 수 있습니다.

Docker 런타임을 사용하는 노드 식별

다음 메서드를 사용해서 Docker 기반 노드 이미지를 사용하는 노드를 확인할 수 있습니다.

Google Cloud 프로젝트에서 모든 GKE 클러스터에 있는 모든 노드에 스크립트를 반복 사용할 수 있습니다.
Google Cloud CLI, kubectl, Google Cloud 콘솔을 사용해서 노드 이미지를 식별합니다.
지원 중단 통계 및 권장사항을 사용해서 Google Cloud 프로젝트에서 특정 영역 또는 리전의 클러스터와 노드를 식별합니다.

마이그레이션해야 할 모든 노드를 빠르게 식별하기 위해서는 스크립트를 사용하는 것이 좋습니다.

스크립트를 사용하여 Docker 노드 식별

다음 스크립트는 사용 가능한 프로젝트의 모든 클러스터에 있는 모든 노드에 대해 반복 수행되고 다음과 같은 실행 가능한 권장사항을 제공합니다.

노드 자동 프로비저닝이 Docker 이미지에 대해 구성되었는지 여부
마이그레이션에 권장되는 상응하는 containerd 노드 이미지
마이그레이션에 권장되는 노드 이미지 버전
식별된 노드 및 설정을 마이그레이션하기 위해 실행할 권장되는 명령어

이 스크립트는 기본적으로 containerd 노드 이미지와 함께 Container-Optimized OS를 사용하는 GKE Autopilot 클러스터를 무시합니다.

다음 스크립트를 실행합니다.

for project in $(gcloud projects list --format="value(projectId)")
do
  echo "ProjectId: $project"
  for clusters in $( \
    gcloud container clusters list \
      --project $project \
      --format="csv[no-heading](name,location,autopilot.enabled,currentMasterVersion,autoscaling.enableNodeAutoprovisioning,autoscaling.autoprovisioningNodePoolDefaults.imageType)")
  do
    IFS=',' read -r -a clustersArray <<< "$clusters"
    cluster_name="${clustersArray[0]}"
    cluster_zone="${clustersArray[1]}"
    cluster_isAutopilot="${clustersArray[2]}"
    cluster_version="${clustersArray[3]}"
    cluster_minorVersion=${cluster_version:0:4}
    cluster_autoprovisioning="${clustersArray[4]}"
    cluster_autoprovisioningImageType="${clustersArray[5]}"

    if [ "$cluster_isAutopilot" = "True" ]; then
      echo "  Cluster: $cluster_name (autopilot) (zone: $cluster_zone)"
      echo "    Autopilot clusters are running Containerd."
    else
      echo "  Cluster: $cluster_name (zone: $cluster_zone)"

      if [ "$cluster_autoprovisioning" = "True" ]; then
        if [ "$cluster_minorVersion"  \< "1.20" ]; then
          echo "    Node autoprovisioning is enabled, and new node pools will have image type 'COS'."
          echo "    This settings is not configurable on the current version of a cluster."
          echo "    Please upgrade you cluster and configure the default node autoprovisioning image type."
          echo "    "
        else
          if [ "$cluster_autoprovisioningImageType" = "COS" ]; then
            echo "    Node autoprovisioning is configured to create new node pools of type 'COS'."
            echo "    Run the following command to update:"
            echo "    gcloud container clusters update '$cluster_name' --project '$project' --zone '$cluster_zone' --enable-autoprovisioning --autoprovisioning-image-type='COS_CONTAINERD'"
            echo "    "
          fi

          if [ "$cluster_autoprovisioningImageType" = "UBUNTU" ]; then
            echo "    Node autoprovisioning is configured to create new node pools of type 'UBUNTU'."
            echo "    Run the following command to update:"
            echo "    gcloud container clusters update '$cluster_name' --project '$project' --zone '$cluster_zone' --enable-autoprovisioning --autoprovisioning-image-type='UBUNTU_CONTAINERD'"
            echo "    "
          fi
        fi
      fi

      for nodepools in $( \
        gcloud container node-pools list \
          --project $project \
          --cluster $cluster_name \
          --zone $cluster_zone \
          --format="csv[no-heading](name,version,config.imageType)")
      do
        IFS=',' read -r -a nodepoolsArray <<< "$nodepools"
        nodepool_name="${nodepoolsArray[0]}"
        nodepool_version="${nodepoolsArray[1]}"
        nodepool_imageType="${nodepoolsArray[2]}"

        nodepool_minorVersion=${nodepool_version:0:4}

        echo "    Nodepool: $nodepool_name, version: $nodepool_version ($nodepool_minorVersion), image: $nodepool_imageType"

        minorVersionWithRev="${nodepool_version/-gke./.}"
        linuxGkeMinVersion="1.14"
        windowsGkeMinVersion="1.21.1.2200"

        suggestedImageType="COS_CONTAINERD"

        if [ "$nodepool_imageType" = "UBUNTU" ]; then
          suggestedImageType="UBUNTU_CONTAINERD"
        elif [ "$nodepool_imageType" = "WINDOWS_LTSC" ]; then
          suggestedImageType="WINDOWS_LTSC_CONTAINERD"
        elif [ "$nodepool_imageType" = "WINDOWS_SAC" ]; then
          suggestedImageType="WINDOWS_SAC_CONTAINERD"
        fi

        tab=$'\n      ';
        nodepool_message="$tab Please update the nodepool to use Containerd."
        nodepool_message+="$tab Make sure to consult with the list of known issues https://cloud.google.com/kubernetes-engine/docs/concepts/using-containerd#known_issues."
        nodepool_message+="$tab Run the following command to upgrade:"
        nodepool_message+="$tab "
        nodepool_message+="$tab gcloud container clusters upgrade '$cluster_name' --project '$project' --zone '$cluster_zone' --image-type '$suggestedImageType' --node-pool '$nodepool_name'"
        nodepool_message+="$tab "

        # see https://cloud.google.com/kubernetes-engine/docs/concepts/node-images
        if [ "$nodepool_imageType" = "COS_CONTAINERD" ] || [ "$nodepool_imageType" = "UBUNTU_CONTAINERD" ] ||
           [ "$nodepool_imageType" = "WINDOWS_LTSC_CONTAINERD" ] || [ "$nodepool_imageType" = "WINDOWS_SAC_CONTAINERD" ]; then
          nodepool_message="$tab Nodepool is using Containerd already"
        elif ( [ "$nodepool_imageType" = "WINDOWS_LTSC" ] || [ "$nodepool_imageType" = "WINDOWS_SAC" ] ) &&
               [ "$(printf '%s\n' "$windowsGkeMinVersion" "$minorVersionWithRev" | sort -V | head -n1)" != "$windowsGkeMinVersion" ]; then
          nodepool_message="$tab Upgrade nodepool to the version that supports Containerd for Windows"
        elif [ "$(printf '%s\n' "$linuxGkeMinVersion" "$minorVersionWithRev" | sort -V | head -n1)" != "$linuxGkeMinVersion" ]; then
          nodepool_message="$tab Upgrade nodepool to the version that supports Containerd"
        fi
        echo "$nodepool_message"
      done
    fi # not autopilot
  done
done

# Sample output:
#
# ProjectId:  my-project-id
#  Cluster: autopilot-cluster-1 (autopilot) (zone: us-central1)
#    Autopilot clusters are running Containerd.
#  Cluster: cluster-1 (zone: us-central1-c)
#    Nodepool: default-pool, version: 1.18.12-gke.1210 (1.18), image: COS
#
#       Please update the nodepool to use Containerd.
#       Make sure to consult with the list of known issues https://cloud.google.com/kubernetes-engine/docs/concepts/using-containerd#known_issues.
#       Run the following command to upgrade:
#
#       gcloud container clusters upgrade 'cluster-1' --project 'my-project-id' --zone 'us-central1-c' --image-type 'COS_CONTAINERD' --node-pool 'default-pool'
#
#    Nodepool: pool-1, version: 1.18.12-gke.1210 (1.18), image: COS
#
#       Please update the nodepool to use Containerd.
#       Make sure to consult with the list of known issues https://cloud.google.com/kubernetes-engine/docs/concepts/using-containerd#known_issues.
#       Run the following command to upgrade:
#
#       gcloud container clusters upgrade 'cluster-1' --project 'my-project-id' --zone 'us-central1-c' --image-type 'COS_CONTAINERD' --node-pool 'pool-1'
#
#    Nodepool: winpool, version: 1.18.12-gke.1210 (1.18), image: WINDOWS_SAC
#
#       Upgrade nodepool to the version that supports Containerd for Windows
#
#  Cluster: another-test-cluster (zone: us-central1-c)
#    Nodepool: default-pool, version: 1.20.4-gke.400 (1.20), image: COS_CONTAINERD
#
#      Nodepool is using Containerd already
#

Google Cloud를 사용하여 노드 이미지 식별

Google Cloud CLI, kubectl, Google Cloud 콘솔을 사용해서 기존 노드의 노드 이미지를 확인할 수 있습니다.

gcloud

다음 명령어를 실행합니다.

gcloud container node-pools list \
    --cluster=CLUSTER_NAME \
    --format="table(name,version,config.imageType)"

CLUSTER_NAME을 클러스터 이름으로 바꿉니다.

출력은 다음과 비슷합니다.

NAME          NODE_VERSION    IMAGE_TYPE
default-pool  1.19.6-gke.600  UBUNTU

콘솔

Google Cloud 콘솔에서 Google Kubernetes Engine 페이지로 이동합니다.

Google Kubernetes Engine으로 이동
클러스터 목록에서 확인할 클러스터 이름을 클릭합니다.
노드 탭을 선택합니다.
노드 풀 섹션에서 이미지 유형 열의 값을 확인합니다.

kubectl

다음 명령어를 실행합니다.

kubectl get nodes -o wide

출력은 다음과 비슷합니다.

# For Docker runtime
NAME         STATUS   VERSION             OS-IMAGE                             CONTAINER-RUNTIME
gke-node-1   Ready    v1.16.15-gke.6000   Container-Optimized OS from Google   docker://19.3.1
gke-node-2   Ready    v1.16.15-gke.6000   Container-Optimized OS from Google   docker://19.3.1
gke-node-3   Ready    v1.16.15-gke.6000   Container-Optimized OS from Google   docker://19.3.1

CONTAINER-RUNTIME 열의 값은 런타임 및 버전을 보여줍니다.

지원 중단 통계 및 권장사항을 사용하여 클러스터 식별

GKE는 Docker 기반 노드 이미지를 포함하여 일부 지원 중단된 기능 및 API 사용을 감지합니다. 자세한 내용은 GKE 지원 중단을 참조하세요.

지원 중단 사용을 감지하기 위해 GKE는 DEPRECATION_K8S_1_24_DOCKERSHIM 통계 하위 유형으로 Docker 기반 노드 이미지 사용을 식별하는 통계 및 권장사항을 생성합니다.

통계 및 권장사항 쌍 하나에서 Docker 기반 노드 이미지를 사용하는 노드가 있는 클러스터를 식별합니다. 각 통계 및 권장사항은 Docker 기반 노드 이미지를 사용 중이고 containerd 노드 이미지로 마이그레이션해야 하는 클러스터의 특정 노드 풀 목록을 제공합니다.

시작하려면 안내에 따라 지원 중단 통계 및 권장사항을 검토하세요. gcloud CLI 명령어의 경우 지원 중단에 대한 통계만 확인하려면 다음 플래그를 사용합니다.

--filter="insightSubtype:DEPRECATION_K8S_1_24_DOCKERSHIM"

Docker 기반 노드 이미지를 사용 중인 클러스터의 노드 풀을 확인한 후에는 안내에 따라 노드 이미지를 containerd 노드 이미지로 변경합니다.

마이그레이션 영향 확인

프로덕션 클러스터 및 노드 풀을 containerd가 사용되는 노드 이미지로 마이그레이션하기 전 문제가 발생할 위험을 최소화하기 위해 스테이징 환경에서 마이그레이션 영향을 테스트하는 것이 좋습니다.

노드를 마이그레이션할 때 노드를 업그레이드하는 것과 독립적으로 마이그레이션하는 것이 좋습니다. 그렇게 하면 워크로드가 새 구성으로 작동하는지 확인할 때 변수를 분리할 수 있습니다. 또한 노드 풀을 버전 1.24로 동시에 업그레이드하는 경우 1.24는 Docker 노드를 지원하지 않으므로 변경사항을 롤백할 수 없고 부 버전을 다운그레이드할 수 없습니다.

노드 이미지를 containerd 이미지로 변경

Docker 노드 식별을 위해 스크립트를 사용한 경우 스크립트로 반환된 권장 명령어를 사용해서 노드 자동 프로비저닝 설정 및 노드 이미지를 containerd에 상응하는 항목으로 변경할 수 있습니다.

또한 gcloud CLI 또는 Google Cloud 콘솔을 사용해서 노드 풀을 업데이트하고 다른 이미지를 설정하여 Docker 이미지 유형에서 containerd 이미지 유형으로 노드를 마이그레이션할 수도 있습니다.

GKE는 선택한 노드 업그레이드 전략 및 구성을 사용하여 노드 이미지를 마이그레이션합니다. 이 마이그레이션의 경우 블루-그린 업그레이드 전략을 사용하는 것이 좋습니다. 워크로드에서 업그레이드 중 새 노드 이미지에 문제가 발생하면 원래 노드 이미지 구성을 사용하여 이전 환경으로 롤백할 수 있기 때문입니다.

gcloud

다음 명령어를 실행합니다.

gcloud container clusters upgrade CLUSTER_NAME \
    --image-type=NODE_IMAGE \
    --node-pool=POOL_NAME \
    --cluster-version=NODE_VERSION

다음을 바꿉니다.

NODE_IMAGE: 노드에 사용할 노드 이미지입니다.
POOL_NAME: 마이그레이션할 노드 풀의 이름입니다.
NODE_VERSION: 노드 풀의 기존 버전입니다. 이 플래그를 설정하는 것이 좋습니다. 그러지 않으면 GKE가 노드 풀 버전을 컨트롤 플레인 버전으로 업그레이드하고 동일한 작업으로 노드 이미지를 업데이트하려고 시도합니다. 컨트롤 플레인에서 1.24를 실행하는 경우 명령어가 실패합니다. 제어 영역이 1.23을 실행하는 경우 명령어가 성공적으로 실행되어 두 변경사항(버전 업그레이드 및 이미지 업데이트)을 개별적으로 테스트할 수 없습니다.

출력은 다음과 비슷합니다.

NAME          NODE_VERSION    IMAGE_TYPE
default-pool  1.23.6-gke.600  UBUNTU_CONTAINERD

콘솔

Google Cloud 콘솔에서 Google Kubernetes Engine 페이지로 이동합니다.

Google Kubernetes Engine으로 이동
클러스터 목록에서 확인할 클러스터 이름을 클릭합니다.
노드 탭을 클릭합니다.
노드 풀 섹션에서 수정하려는 노드 풀의 이름을 클릭합니다.
노드 풀 세부정보 페이지에서 수정을 클릭합니다.
노드 섹션의 이미지 유형에서 변경을 클릭합니다.
containerd 이미지 유형 중 하나를 선택합니다.
변경을 클릭합니다.

Docker 노드 이미지로 롤백

노드가 containerd 노드로 자동 또는 수동으로 마이그레이션되고 워크로드에 문제가 발생하면 다음 단계를 수행하여 Docker 노드 이미지로 되돌립니다.

작업 상태에 따라 다음 단계를 선택합니다.
- 작업이 아직 진행 중이면 취소 및 롤백할 수 있습니다.
- 작업이 완료되면 이전 섹션의 단계를 참조하고 동등한 Docker 이미지를 선택합니다.
GKE가 일시적으로 마이그레이션을 재시도하지 못하도록 유지보수 제외를 구성합니다.
Docker에서 마이그레이션할 수 있도록 문제의 근본 원인을 조사하고 클러스터에서 지원되는 GKE 버전을 실행하고 있는지 확인합니다.
노드 이미지를 containerd 이미지로 변경하도록 다시 시도합니다. 유지보수 제외를 삭제하면 GKE가 작업을 다시 트리거합니다.

코드형 인프라(IaC) 도구 구성 업데이트

Terraform, Ansible, Pulumi와 같은 IaC 도구를 사용하여 GKE 클러스터를 관리하는 경우 containerd 노드 이미지를 사용하도록 구성을 업데이트하여 도구에서 이전에 원하는 상태를 새로운 실제 상태로 조정하지 못하도록 합니다. 예를 들어 GKE Terraform 제공업체는 구성 가능한 이미지 유형을 지원합니다.

containerd 노드 이미지로 마이그레이션한 후 도구에서 노드 이미지를 Docker 기반 노드 이미지로 다시 업데이트하지 않도록 구성을 업데이트합니다.

노드 자동 프로비저닝을 위한 기본 노드 이미지 변경

클러스터에서 노드 자동 프로비저닝을 사용하는 경우 기본 이미지 유형을 containerd 노드 이미지로 변경합니다. 기본 이미지 유형 변경은 새롭게 자동 프로비저닝된 노드 풀에만 적용됩니다. 기존 자동 프로비저닝된 노드 풀에 대해서는 노드 이미지를 수동으로 변경해야 합니다.

gcloud CLI 또는 구성 파일을 사용해서 기본 노드 자동 프로비저닝 이미지 유형을 변경할 수 있습니다.

gcloud

다음 명령어를 실행합니다.

gcloud container clusters update CLUSTER_NAME \
    --enable-autoprovisioning \
    --autoprovisioning-image-type=IMAGE_TYPE

다음을 바꿉니다.

CLUSTER_NAME: 업데이트할 클러스터의 이름입니다.
IMAGE_TYPE: 노드 이미지 유형이며 다음 중 하나일 수 있습니다.
- cos_containerd
- ubuntu_containerd
  
  참고: ubuntu_containerd의 경우 명령어에 --autoprovisioning-scopes=https://www.googleapis.com/auth/devstorage.read_only를 지정합니다.

파일

YAML 구성 파일을 사용해서 노드 자동 프로비저닝을 위한 기본 노드 이미지 유형을 변경할 수 있습니다. 파일을 사용할 때는 CPU 및 메모리 리소스에 대한 최댓값도 지정해야 합니다.

다음 YAML 파일을 저장합니다.
```
resourceLimits:
  - resourceType: 'cpu'
      minimum: 4
      maximum: 10
  - resourceType: 'memory'
      maximum: 64
autoprovisioningNodePoolDefaults:
  imageType: 'IMAGE_TYPE'
```
IMAGE_TYPE을 containerd 이미지 유형으로 바꿉니다.

참고: ubuntu_containerd의 경우 scopes: https://www.googleapis.com/auth/devstorage.read_only를 구성 파일에 추가합니다.

구성을 적용합니다.

gcloud container clusters update CLUSTER_NAME \
    --enable-autoprovisioning \
    --autoprovisioning-config-file=FILE_NAME

FILE_NAME을 구성 파일의 경로로 바꿉니다.

문제 해결

문제 해결 및 알려진 문제와 해결 방법을 보려면 컨테이너 런타임 문제 해결을 참조하세요.