이미지 가져오기 문제 해결

컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

이 페이지에서는 Google Kubernetes Engine (GKE)에서 이미지 가져오기 프로세스와 관련된 문제를 해결하는 데 도움이 됩니다. 이미지 스트리밍을 사용하는 경우 이미지 스트리밍 문제 해결을 참고하세요. 이 페이지에서는 표준 이미지 가져오기에 중점을 둡니다.

이 페이지는 앱이 성공적으로 배포되는지 확인하려는 애플리케이션 개발자와 이미지 가져오기 실패의 근본 원인을 파악하고 플랫폼 구성을 확인하려는 플랫폼 관리자 및 운영자를 위해 작성되었습니다. Google Cloud 콘텐츠에서 참조하는 일반적인 역할 및 예시 작업에 대해 자세히 알아보려면 일반 GKE Enterprise 사용자 역할 및 작업을 참고하세요.

이미지 가져오기 프로세스는 Kubernetes, 즉 GKE가 레지스트리에서 컨테이너 이미지를 가져오는 방법입니다. 이미지 가져오기에 실패하면 앱이 느려지거나 아예 작동하지 않을 수 있습니다.

이미지 가져오기가 앱이 작동하지 않는 원인인지 확인하려면 이 페이지에서 관련 오류 메시지를 찾아 이해하여 이미지 가져오기 실패를 진단하세요. 그런 다음 이미지 가져오기 실패의 일반적인 원인인 다음 문제를 해결하는 방법을 알아봅니다.

• 인증 설정: 클러스터에 컨테이너 이미지 레지스트리에 액세스하는 데 필요한 권한이 없습니다.
• 네트워크 연결: DNS 문제, 방화벽 규칙 또는 네트워크 격리를 사용하는 클러스터의 인터넷 액세스 부족으로 인해 클러스터가 레지스트리에 연결할 수 없습니다.
• 레지스트리에서 이미지를 찾을 수 없음: 지정된 이미지 이름 또는 태그가 잘못되었거나 이미지가 삭제되었거나 레지스트리를 사용할 수 없습니다.
• 성능 제한사항: 이미지 크기가 크거나 디스크 I/O가 느리거나 네트워크가 혼잡하면 가져오기가 느려지거나 제한시간이 발생할 수 있습니다.
• 호환되지 않는 이미지 아키텍처: 이미지가 GKE 노드 풀과 다른 CPU 아키텍처용으로 빌드되었습니다.
• 호환되지 않는 스키마 버전: 지원되지 않는 v1 Docker 스키마와 함께 containerd 2.0 이상을 사용하고 있을 수 있습니다.

이미 특정 이벤트 메시지가 표시된 경우 이 페이지에서 메시지를 검색하고 나열된 문제 해결 단계를 따르세요. 메시지가 표시되지 않으면 다음 섹션을 순서대로 진행하세요. 문제가 계속되면 Cloud Customer Care에 문의하세요.

이미지 가져오기 이해하기

문제 해결을 시작하기 전에 이미지의 수명 주기와 이미지를 호스팅할 수 있는 위치에 관해 자세히 알아보는 것이 좋습니다.

이미지 수명 주기

포드를 만들면 kubelet은 이미지 사양이 포함된 포드 정의를 수신합니다. kubelet은 이 이미지를 기반으로 컨테이너를 실행할 수 있어야 합니다. kubelet은 이미지를 가져오기 전에 컨테이너 런타임을 확인하여 이미지가 있는지 확인합니다. kubelet은 포드의 이미지 가져오기 정책도 확인합니다. 이미지가 컨테이너 런타임의 캐시에 없거나 이미지 pull 정책에서 요구하는 경우 kubelet은 컨테이너 런타임(containerd)에 레지스트리에서 지정된 이미지를 가져오도록 지시합니다. 이미지 가져오기에 실패하면 포드의 컨테이너가 시작되지 않습니다.

이미지 가져오기가 완료되면 컨테이너 런타임은 이미지를 압축 해제하여 컨테이너의 읽기 전용 기본 파일 시스템을 만듭니다. 컨테이너 런타임은 이 이미지를 저장하며 실행 중인 컨테이너가 이 이미지를 참조하는 한 이미지는 계속 존재합니다. 실행 중인 컨테이너가 이미지를 참조하지 않으면 이미지가 가비지 컬렉션 대상이 되고 결국 kubelet에서 삭제합니다.

이미지 호스팅 옵션

다음 옵션 중 하나를 사용하여 이미지를 호스팅하는 것이 좋습니다.

• Artifact Registry: Artifact Registry는 Google의 완전 관리형 패키지 관리자입니다. Artifact Registry는 다른 Google Cloud서비스와 긴밀하게 통합되며 세분화된 액세스 제어를 제공합니다. 자세한 내용은 Artifact Registry 문서의 컨테이너 이미지로 작업하기를 참고하세요.

• 자체 호스팅 레지스트리: 자체 호스팅 레지스트리는 더 많은 제어 기능을 제공하지만 레지스트리를 관리해야 합니다. Artifact Registry에서 충족할 수 없는 특정 규정 준수 또는 보안 요구사항이 있는 경우 이 옵션을 고려하세요.

이미지 가져오기 실패 진단

이미지 가져오기 실패를 진단하려면 다음 섹션에 설명된 조사를 실행합니다.

1. 포드 상태 및 이벤트를 확인합니다.
2. 상태의 의미를 이해합니다.
3. 이벤트 메시지를 사용하여 이미지 가져오기 실패의 원인을 찾습니다.
4. 로그 탐색기 로그를 봅니다.

포드 상태 및 이벤트 보기

이미지 가져오기에 실패했는지 확인할 수 있도록 GKE는 포드에 다음 상태를 기록합니다.

• ImagePullBackOff
• ErrImagePull
• ImageInspectError
• InvalidImageName
• RegistryUnavailable
• SignatureValidationFailed

ImagePullBackOff 및 ErrImagePull가 이러한 상태 중 가장 일반적입니다.

이러한 상태 외에도 Kubernetes 이벤트는 이미지 가져오기 실패의 원인을 찾는 데 도움이 됩니다.

이미지 가져오기에 실패했는지 확인하려면 상태 메시지를 확인한 다음 다음 옵션 중 하나를 선택하여 이벤트 메시지를 읽습니다.

상태 의미 이해하기

다양한 상태의 의미를 더 잘 이해하려면 다음 설명을 참고하세요.

• ImagePullBackOff: kubelet이 이미지를 가져오지 못했지만 최대 5분의 지연 (또는 백오프)을 늘려 계속 재시도합니다.
• ErrImagePull: 이미지 가져오기 프로세스 중에 발생하는 일반적이고 복구 불가능한 오류입니다.
• ImageInspectError: 컨테이너 런타임에서 컨테이너 이미지를 검사하려고 할 때 문제가 발생했습니다.
• InvalidImageName: Pod 정의에 지정된 컨테이너 이미지의 이름이 유효하지 않습니다.
• RegistryUnavailable: 레지스트리에 액세스할 수 없습니다. 이는 일반적으로 네트워크 연결 문제입니다.
• SignatureValidationFailed: 컨테이너 이미지의 디지털 서명을 확인할 수 없습니다.

이벤트 메시지를 사용하여 이미지 가져오기 실패 원인 찾기

다음 표에는 이미지 가져오기 실패와 관련된 이벤트 메시지와 이러한 메시지 중 하나가 표시되면 따라야 하는 문제 해결 단계가 나와 있습니다.

이미지 가져오기 실패와 관련된 메시지는 다음과 같은 접두사가 있는 경우가 많습니다.

Failed to pull image "IMAGE_ADDRESS": rpc error: code = CODE = failed to pull and unpack image "IMAGE_ADDRESS": failed to resolve reference "IMAGE_ADDRESS":

이 메시지에는 다음 값이 포함됩니다.

• IMAGE_ADDRESS: 이미지의 전체 주소입니다. 예를 들면 us-west1-docker.pkg.dev/my-project/my-repo/test:staging입니다.
• CODE: 로그 메시지와 연결된 오류 코드입니다. 예를 들면 NotFound 또는 Unknown입니다.

이미지 가져오기 실패의 일부 원인에는 관련 이벤트 메시지가 없습니다. 다음 표에 이벤트 메시지가 표시되지 않지만 이미지 가져오기 문제가 계속 발생하는 경우 페이지의 나머지 부분을 계속 읽어 보시기 바랍니다.

로그 탐색기 로그 보기

이전 이미지 가져오기 이벤트를 검사하거나 이미지 가져오기 실패를 다른 구성요소 활동과 연결하려면 로그 탐색기로 로그를 확인하세요.

1. Google Cloud 콘솔에서 로그 탐색기 페이지로 이동합니다.

   로그 탐색기로 이동

2. 쿼리 창에 다음 쿼리를 입력합니다.

   log_id("events")
   resource.type="k8s_pod"
   resource.labels.cluster_name="CLUSTER_NAME"
   jsonPayload.message=~"Failed to pull image"
   

   CLUSTER_NAME을 이미지 가져오기 오류가 있는 포드가 실행되는 클러스터의 이름으로 바꿉니다.

3. 쿼리 실행을 클릭하고 결과를 검토합니다.

인증 설정 조사

다음 섹션에서는 GKE 환경에 저장소에서 이미지를 가져오는 데 필요한 적절한 인증 설정이 있는지 확인하는 방법을 설명합니다.

이미지 가져오기 문제를 일으키는 인증 문제가 있는지 확인하려면 다음 섹션에 설명된 조사를 실행하세요.

1. 이미지에 대한 액세스 권한을 확인합니다.
2. imagePullSecret 구성 및 배포 사양을 확인합니다.
3. 비공개 Artifact Registry 저장소의 노드 액세스 범위 확인
4. Artifact Registry에 액세스할 수 있는 VPC 서비스 제어 설정을 확인합니다.

이미지 액세스 확인

403 Forbidden 이미지 가져오기 오류가 발생하면 필요한 구성요소가 컨테이너 이미지에 액세스할 수 있는지 확인합니다.

필요한 액세스 권한을 부여하는 데 필요한 역할을 확인하고 적용하는 방법은 이미지를 저장하는 저장소 유형에 따라 다릅니다. 액세스를 확인하고 부여하려면 다음 옵션 중 하나를 선택합니다.

imagePullSecret 구성 및 배포 사양 확인

imagePullSecret을 사용하는 경우 이미지 가져오기에 관한 인증 사용자 인증 정보를 보유하는 보안 비밀을 만들고 모든 배포에서 정의한 보안 비밀을 지정해야 합니다. 자세한 내용은 Kubernetes 문서의 Pod에서 imagePullSecrets 지정을 참고하세요.

비공개 Artifact Registry 저장소의 노드 액세스 범위 확인

컨테이너 이미지를 비공개 Artifact Registry 저장소에 저장하면 노드에 올바른 액세스 범위가 없을 수 있습니다. 이 경우 401 Unauthorized 이미지 가져오기 오류가 발생할 수 있습니다.

액세스 범위를 확인하고 필요한 경우 액세스 권한을 부여하려면 다음 단계를 따르세요.

1. 포드를 실행 중인 노드를 식별합니다.

   kubectl describe pod POD_NAME | grep "Node:"
   

   POD_NAME을 이미지 가져오기 실패가 발생한 포드의 이름으로 바꿉니다.

2. 이전 단계에서 식별한 노드에 올바른 스토리지 범위가 있는지 확인합니다.

   gcloud compute instances describe NODE_NAME \
       --zone="COMPUTE_ZONE \
       --format="flattened(serviceAccounts[].scopes)"
   

   다음을 바꿉니다.

   • NODE_NAME: 이전 단계에서 식별한 노드의 이름입니다.
   • COMPUTE_ZONE: 노드가 속한 Compute Engine 영역입니다.

   출력에 다음 액세스 범위 중 하나 이상이 포함되어야 합니다.

   • serviceAccounts[0].scopes[0]: https://www.googleapis.com/auth/devstorage.read_only
   • serviceAccounts[0].scopes[0]: https://www.googleapis.com/auth/cloud-platform

   노드에 이러한 범위 중 하나가 포함되어 있지 않으면 이미지 가져오기에 실패합니다.

3. 충분한 범위를 사용해서 노드가 포함된 노드 풀을 다시 만듭니다. 기존 노드는 수정할 수 없으므로 올바른 범위를 사용하여 노드를 다시 만들어야 합니다.

   gke-default 범위를 사용하여 노드 풀을 만드는 것이 좋습니다. 이 범위는 다음 범위에 대한 액세스 권한을 제공합니다.

   • https://www.googleapis.com/auth/devstorage.read_only
   • https://www.googleapis.com/auth/logging.write
   • https://www.googleapis.com/auth/monitoring
   • https://www.googleapis.com/auth/service.management.readonly
   • https://www.googleapis.com/auth/servicecontrol
   • https://www.googleapis.com/auth/trace.append

   gke-default 범위가 적합하지 않으면 노드 풀에 데이터 읽기 전용 액세스를 허용하는 devstorage.read_only 범위를 부여합니다.

   gke-default

   gke-default 범위로 노드 풀을 만듭니다.

   gcloud container node-pools create NODE_POOL_NAME \
       --cluster=CLUSTER_NAME \
       --zone=COMPUTE_ZONE \
       --scopes="gke-default"
   

   다음을 바꿉니다.

   • NODE_POOL_NAME: 새 노드 풀의 이름입니다.
   • CLUSTER_NAME: 기존 클러스터의 이름입니다.
   • COMPUTE_ZONE: 새 노드 풀이 속해야 하는 Compute Engine 영역입니다.

   devstorage.read_only

   devstorage.read_only 범위로 노드 풀을 만듭니다.

   gcloud container node-pools create NODE_POOL_NAME \
       --cluster=CLUSTER_NAME \
       --zone=COMPUTE_ZONE \
       --scopes="https://www.googleapis.com/auth/devstorage.read_only"
   

   다음을 바꿉니다.

   • NODE_POOL_NAME: 새 노드 풀의 이름입니다.
   • CLUSTER_NAME: 기존 클러스터의 이름입니다.
   • COMPUTE_ZONE: 새 노드 풀이 속해야 하는 Compute Engine 영역입니다.

Artifact Registry에 액세스하기 위한 VPC 서비스 제어 설정 확인

VPC 서비스 제어를 사용하는 경우 서비스 경계에서 Artifact Registry에 대한 액세스를 허용하는지 확인합니다. 자세한 내용은 Artifact Registry 문서의 서비스 경계에서 저장소 보호를 참고하세요.

네트워크 연결 조사

이미지를 가져오는 동안 네트워크 연결이 원활하지 않으면 프로세스가 완료되지 않을 수 있습니다.

네트워크 연결 문제로 인해 이미지 가져오기 문제가 발생하는지 확인하려면 다음 섹션에 설명된 조사를 실행합니다.

1. DNS 확인을 조사합니다.
2. 방화벽 구성을 조사합니다.
3. 외부 레지스터 엔드포인트의 인터넷 연결을 조사합니다.
4. Google API 연결 시간이 초과되는지 조사합니다.

DNS 확인 조사

server misbehaving 이미지 가져오기 오류가 표시되면 DNS 확인으로 인해 이미지 가져오기에 실패했을 수 있습니다.

DNS 확인 문제를 조사하려면 다음 솔루션을 시도해 보세요.

1. 메타데이터 서버 문제 해결하기 노드의 메타데이터 서버는 모든 DNS 쿼리를 확인합니다. 이 서버와 관련된 문제는 이름 확인을 방해하여 저장소에 연결하지 못하게 하고 이미지 가져오기에 실패하게 할 수 있습니다.
2. DNS 확인에 Cloud DNS를 사용하는 경우 Cloud DNS 관리형 비공개 영역, 전달 영역, 피어링 영역, 응답 정책이 올바르게 구성되어 있는지 확인합니다. 이러한 영역의 구성이 잘못되면 DNS 확인이 중단될 수 있습니다. Cloud DNS에 대한 자세한 내용은 GKE에 Cloud DNS 사용을 참고하세요. GKE에서 Cloud DNS 문제를 해결하는 방법에 관한 도움말은 GKE에서 Cloud DNS 문제 해결을 참고하세요.
3. DNS 확인에 kube-dns를 사용하는 경우 kube-dns가 올바르게 작동하는지 확인합니다. kube-dns 문제 해결에 관한 도움말은 GKE에서 kube-dns 문제 해결을 참고하세요.
4. 클러스터의 노드에 외부 IP 주소가 없는 경우 (네트워크 격리를 사용하는 경우 일반적) 클러스터에서 사용하는 서브넷에 비공개 Google 액세스를 사용 설정하고 네트워크 요구사항을 충족해야 합니다. Cloud NAT를 사용하는 경우Google Cloud 가 비공개 Google 액세스를 자동으로 사용 설정합니다.

방화벽 구성 조사

방화벽 문제로 인해 이미지 가져오기에 실패하면 다음과 같은 오류 메시지가 표시될 수 있습니다.

Failed to start Download and install k8s binaries and configurations

방화벽 문제 진단

표준 클러스터를 사용 중이며 방화벽 문제로 인해 이미지 가져오기에 문제가 있는지 확인하려면 다음 단계를 따르세요.

1. SSH를 사용하여 문제가 발생한 노드에 연결합니다.

   gcloud compute ssh NODE_NAME --zone=ZONE_NAME
   

   다음을 바꿉니다.

   • NODE_NAME: 노드 이름
   • ZONE_NAME: 노드가 생성된 Compute Engine 영역입니다.

2. kube-node-installation.service 및 kube-node-configuration.service 서비스의 최신 로그를 kube-node-installation_status.txt 및 kube-node-configuration_status.txt라는 텍스트 파일로 전송합니다.

   systemctl status kube-node-installation.service > kube-node-installation_status.txt
   systemctl status kube-node-configuration.service > kube-node-configuration_status.txt
   

   이러한 로그에 이미지 가져오기에 실패한 시점의 정보가 포함되지 않으면 로그의 전체 사본을 생성합니다.

   sudo journalctl -u kube-node-installation.service > kube-node-installation_logs.txt
   sudo journalctl -u kube-node-configuration.service > kube-node-configuration_logs.txt
   

3. kube-node-installation_status.txt 및 kube-node-configuration_status.txt 파일의 콘텐츠를 검토합니다. 출력에 i/o timeout가 표시되면 방화벽에 문제가 있는 것일 수 있습니다.

방화벽 구성 문제 해결

방화벽 문제를 해결하려면 다음 솔루션을 시도해 보세요.

1. 네트워크 트래픽을 차단하는 방화벽 규칙을 식별하고 해결합니다. 예를 들어 이미지를 저장하는 레지스트리로의 트래픽을 차단하는 규칙이 있을 수 있습니다.

   1. VPC 흐름 로그에 액세스하는 방법은 다음과 같습니다.

      1. Google Cloud 콘솔에서 로그 탐색기 페이지로 이동합니다.

         로그 탐색기로 이동

      2. 쿼리 창에 다음 쿼리를 입력합니다.

         resource.type="gce_subnetwork"
         logName="projects/PROJECT_ID/logs/[compute.googleapis.com%2Fvpc_flows](http://compute.googleapis.com%2Fvpc_flows)"
         resource.labels.subnetwork_name="SUBNET_NAME",
         

         다음을 바꿉니다.

         • PROJECT_ID: Google Cloud 프로젝트의 ID입니다.
         • SUBNET_NAME: 서브네트워크의 이름입니다.

         자세한 내용은 VPC 문서의 쿼리를 사용하여 흐름 로그에 액세스를 참고하세요.

   2. 필요한 트래픽을 차단하는 방화벽 규칙을 발견하면 업데이트합니다.

2. 클러스터의 노드에 외부 IP 주소가 없는 경우 (네트워크 격리를 사용하는 경우 일반적) 클러스터에서 사용하는 서브넷에 비공개 Google 액세스를 사용 설정하고 네트워크 요구사항을 충족해야 합니다. Cloud NAT를 사용하는 경우Google Cloud 가 비공개 Google 액세스를 자동으로 사용 설정합니다.

외부 레지스터 엔드포인트의 인터넷 연결 조사

네트워크 구성이 외부 레지스트리 엔드포인트를 통해 트래픽을 전달하는 경우 해당 엔드포인트에 인터넷 연결이 없을 수 있습니다. 엔드포인트에 액세스 권한이 없으면 이미지 가져오기에 실패하고 i/o timeout 이미지 가져오기 오류가 표시될 수 있습니다.

외부 레지스트리 엔드포인트에서 레지스트리로의 네트워크 연결을 확인하려면 ping 또는 traceroute를 사용하세요.

ping REGISTRY_ENDPOINT

또는

traceroute REGISTRY_ENDPOINT

REGISTRY_ENDPOINT를 레지스트리 엔드포인트로 바꿉니다. 이 값은 호스트 이름 또는 IP 주소일 수 있습니다.

연결에 오류가 있는 경우 VPC 경로를 검토합니다.

1. Google Cloud 콘솔에서 경로로 이동합니다.

   경로로 이동

2. 우선순위 열을 검토하고 우선순위가 가장 높은 경로가 레지스트리에 액세스할 수 있는 소스로 연결되는지 확인합니다. 값이 낮은 경로가 우선 적용됩니다.

Google API 연결 시간이 초과되는지 조사

네트워크 격리를 사용하면 Google API 및 서비스 연결 시간 초과 오류가 발생하여 i/o timeout 이미지 가져오기 오류가 발생할 수 있습니다.

이 오류는 노드가 레지스트리에서 이미지를 가져오려고 할 때 다음 API 중 하나에 연결할 수 없기 때문에 발생합니다.

• containerregistry.googleapis.com
• artifactregistry.googleapis.com

필수 API에 연결할 수 있도록 하려면 다음 솔루션을 시도해 보세요.

1. 비공개 Google 액세스를 사용 설정합니다. 외부 IP 주소가 없는 노드는 비공개 Google 액세스를 사용하여 Google API 및 서비스의 외부 IP 주소에 연결해야 합니다.
2. 지원되는 도메인을 사용합니다.

3. 방화벽 정책을 검토합니다.

   1. Google Cloud 콘솔에서 방화벽 정책으로 이동합니다.

      방화벽 정책으로 이동

   2. 443 포트에서 199.36.153.4/30, 199.36.153.8/30 또는 Google API 및 서비스에 선택한 도메인에서 사용하는 IP 주소 범위로의 이그레스 TCP 트래픽을 차단하는 규칙이 있는지 확인합니다. IP 주소 범위 199.36.153.4/30 및 199.36.153.8/30는 각각 비공개 Google 액세스 및 제한된 Google 액세스에 사용됩니다. 이러한 범위로 연결되는 포트 443의 TCP 트래픽은 Google API 및 서비스에 액세스하기 위한 것입니다.

      이러한 규칙이 있는 경우 이그레스 방화벽 규칙을 만들어 이러한 트래픽을 허용합니다.

4. Artifact Registry를 사용하는 경우 네트워크 격리와 함께 Artifact Registry를 사용하기 위한 요구사항을 충족하는지 확인합니다.

5. 가상 IP 주소 (VIP) (199.36.153.4/30 또는 199.36.153.8/30)에 VPC 경로가 구성되어 있는지 확인합니다.

   1. Google Cloud 콘솔에서 VPC 네트워크로 이동합니다.

      VPC 네트워크로 이동

   2. 이름 열에서 기본을 클릭합니다.

   3. VPC 네트워크 세부정보 페이지에서 경로 탭을 클릭합니다.

   4. 경로 테이블을 검토합니다.

      VPC 네트워크에 기본 경로 (대상 0.0.0.0/0 또는 ::0/0)가 있고 해당 경로의 다음 홉이 기본 인터넷 게이트웨이 (네트워크 기본값)인 경우 VIP가 Google API 및 서비스에 액세스하는 데 이 경로를 사용합니다.

      기본 경로를 다음 홉이 기본 인터넷 게이트웨이가 아닌 커스텀 경로로 대체한 경우 커스텀 라우팅을 사용하여 Google API 및 서비스의 라우팅 요구사항을 충족합니다.

kubelet에서 이미지를 찾을 수 없는 이유 조사

kubelet이 이미지를 찾을 수 없으면 image not found 오류가 표시되고 이미지 가져오기에 실패할 수 있습니다.

kubelet이 이미지를 찾을 수 있도록 하려면 다음 솔루션을 시도해 보세요.

1. 포드의 매니페스트를 검토하고 이미지 이름과 이미지 태그의 철자가 올바른지 확인합니다. 철자 또는 형식 오류가 있으면 이미지 가져오기에 실패합니다.
2. 저장한 레지스트리에 이미지가 여전히 있는지 확인합니다. 이미지에 전체 레지스트리 경로가 있으면 사용 중인 Docker 레지스트리에 있는지 확인합니다. 이미지 이름만 제공하는 경우, Docker Hub 레지스트리를 확인합니다.
3. 클러스터에서 네트워크 격리를 사용하는 경우 다음 해결 방법을 시도해 보세요.
   1. 비공개 Google 액세스를 사용 설정합니다.
   2. 서비스 경계가 올바르게 구성되었는지 확인합니다.

이미지 가져오기 시간 초과 또는 느린 이미지 가져오기의 원인 조사

GKE 워크로드에 매우 큰 이미지를 사용하면 이미지 가져오기에 시간 초과가 발생하여 context cancelled 오류가 발생할 수 있습니다. 이미지에는 정의된 크기 제한이 없지만 context cancelled 오류는 이미지 크기가 원인임을 나타내는 경우가 많습니다.

이미지 가져오기에 실패하지는 않지만 평소보다 훨씬 오래 걸리는 경우도 있습니다. 일반 이미지 가져오기 시간의 기준을 확인하려면 Successfully pulled image 로그 항목을 검토하세요. 예를 들어 다음 로그 메시지는 이미지 가져오기에 30.313387996초가 걸렸음을 보여줍니다.

Successfully pulled image "IMAGE_ADDRESS" in 30.313387996s.

제한 시간 초과와 느린 이미지 가져오기에는 많은 동일한 원인이 있습니다. 이 문제를 해결하려면 다음 솔루션을 시도해 보세요.

1. 서비스 중단이 있는지 확인합니다. 특정 기간에만 이 문제가 발생한 경우 서비스 중단이 있었는지 Google Cloud 확인하세요.
2. 디스크 성능을 확인합니다. 디스크 I/O가 느리면 이미지 가져오기 시간이 늘어날 수 있습니다. 성능을 개선하려면 SSD가 있는 영구 디스크 (pd-ssd)로 업그레이드하거나 더 큰 디스크를 사용하는 것이 좋습니다. 자세한 내용은 디스크 성능 문제 해결을 참고하세요.
3. 이미지 크기를 줄입니다. 예를 들어 일부 데이터를 컨테이너 이미지에서 영구 볼륨으로 이동할 수 있습니다.
4. 이미지 캐싱을 활용하여 포드 시작 시간을 단축하세요. GKE는 노드에 이미지를 캐시합니다. 이미지를 가져오는 동안 컨테이너 런타임은 캐시에 아직 없는 레이어만 다운로드합니다. 이 캐싱 메커니즘의 효과를 극대화하고 이미지 가져오기 시간을 최소화하려면 Dockerfile을 구성하여 이미지의 자주 변경되는 부분 (예: 애플리케이션 코드)을 파일 끝부분에 배치하고 더 작은 기본 이미지를 사용하세요.
5. 이미지 스트리밍을 사용 설정합니다. 이 기능을 사용하면 포드 시작 및 이미지 다운로드 속도를 높일 수 있습니다. 자세한 내용은 이미지 스트리밍을 사용하여 컨테이너 이미지 가져오기를 참고하세요.
6. 기본 서비스 계정에 필요한 권한이 있는지 확인합니다. 기본 서비스 계정에 할당된 역할을 수정하면 이미지 가져오기를 비롯한 워크로드가 중단될 수 있습니다. 자세한 내용은 중요한 권한이 누락된 노드 서비스 계정이 있는 클러스터 식별을 참고하세요.
7. 프록시 구성을 검사합니다. GKE 클러스터와 Google 이외의 관리 저장소 사이에 프록시가 있으면 지연 시간이 발생할 수 있습니다.
8. 서드 파티 소프트웨어를 확인합니다. 일부 서드 파티 소프트웨어는 이미지 가져오기를 방해할 수 있습니다. 최근에 설치한 도구가 충돌을 일으키는 것인지 조사합니다.

이미지 매니페스트가 올바른 아키텍처를 사용하는지 확인

가져오려는 이미지가 노드 풀에서 사용하는 컴퓨터 아키텍처와 다른 아키텍처용으로 빌드된 경우 이미지 가져오기에 실패합니다.

이미지 매니페스트가 올바른 아키텍처를 사용하는지 확인하려면 다음 단계를 따르세요.

1. 이미지에서 사용하는 아키텍처를 확인하려면 이미지의 매니페스트를 확인하세요. 예를 들어 Docker 이미지를 보려면 다음 명령어를 실행합니다.

   docker manifest inspect --verbose IMAGE_NAME
   

   IMAGE_NAME을 보려는 이미지의 이름으로 바꿉니다.

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

   ...
   "Platform": {
             "architecture": "amd64",
             "os": "linux"
     }
   ...
   

   이 예에서 지원되는 아키텍처는 amd64입니다.

2. 노드 풀에서 사용하는 머신 유형을 검토합니다.

   gcloud container node-pools list --cluster CLUSTER_NAME --location LOCATION
   

   다음을 바꿉니다.

   • CLUSTER_NAME: 이미지 가져오기 오류가 있는 Pod가 실행되는 클러스터의 이름입니다.
   • LOCATION: 노드가 생성된 Compute Engine 영역 또는 리전입니다. 예를 들면 us-central1-a 또는 us-central1입니다.

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

   NAME: example-node-pool
   MACHINE_TYPE: e2-standard-2
   DISK_SIZE_GB: 100
   NODE_VERSION: 1.30.8-gke.1162000
   

   이 예시에서 머신 유형은 e2-standard-2입니다.

3. architecture 및 MACHINE_TYPE 필드의 값을 비교하고 두 값이 모두 호환되는지 확인합니다. 예를 들어 이미지에 amd64 아키텍처가 있는 경우 e2-standard-2을 머신 유형으로 사용하는 노드 풀과 호환됩니다. 그러나 노드 풀이 t2a-standard-1 (Arm 기반 머신 유형)를 사용하는 경우 이 머신 유형으로 인해 실패가 발생합니다.

4. 이미지의 아키텍처가 노드 풀의 머신 유형과 호환되지 않으면 필요한 아키텍처를 타겟팅하도록 이미지를 다시 빌드합니다.

이미지 스키마 버전 호환성 확인

v1 Docker 스키마 이미지와 함께 containerd 2.0을 사용하면 이미지 가져오기에 실패합니다. containerd 2.0에서 GKE 1.33의 Docker 스키마 1 이미지 가져오기 지원이 삭제되었기 때문입니다. 이 문제가 이미지 가져오기 실패의 원인인 경우 다음과 같은 오류 메시지가 표시될 수 있습니다.

Failed to get converter for "IMAGE_ADDRESS": Pulling Schema 1 images have been deprecated and disabled by default since containerd v2.0. As a workaround you may set an environment variable `CONTAINERD_ENABLE_DEPRECATED_PULL_SCHEMA_1_IMAGE=1`, but this will be completely removed in containerd v2.1.

이 문제를 해결하려면 Docker 스키마 1 이미지에서 이전의 안내에 따라 이러한 이미지를 식별하고 이전하세요.

다음 단계

추가 지원이 필요하면 Cloud Customer Care에 문의하기