GKE에서 비공개 클러스터 문제 해결

이 페이지에서는 Google Kubernetes Engine(GKE) 비공개 클러스터의 문제를 해결하는 방법을 설명합니다.

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

비공개 클러스터가 실행 중이 아님

클러스터 제어 영역과 클러스터 노드 사이의 VPC 피어링을 삭제하거나, 포트 10250에서 클러스터 제어 영역으로부터 노드까지 인그레스 트래픽을 허용하는 방화벽 규칙을 삭제하거나, 기본 인터넷 게이트웨이의 기본 경로를 삭제하면 비공개 클러스터가 작동을 중지합니다. 기본 경로를 삭제할 경우 필요한 Google Cloud 서비스로 가는 트래픽을 라우팅해야 합니다. 자세한 내용은 커스텀 라우팅을 참조하세요.

비공개 클러스터 생성 시 제한 시간

모든 비공개 클러스터에는 VPC 간의 피어링 경로가 필요하지만 한 번에 피어링 작업 하나만 수행할 수 있습니다. 비공개 클러스터 여러 개를 동시에 만들려고 하면 클러스터 만들기가 타임아웃될 수 있습니다. 이를 방지하려면 이후의 각 비공개 클러스터에 VPC 피어링 경로가 이미 존재하도록 새 비공개 클러스터를 순차적으로 만듭니다. VPC에서 실행 중인 작업이 있는 경우 비공개 클러스터 하나를 만들려고 해도 타임아웃될 수 있습니다.

비공개 클러스터에서 VPC 네트워크 피어링 연결이 사고로 삭제됨

증상

VPC 네트워크 피어링 연결을 실수로 삭제한 경우 클러스터가 복구 상태로 전환되고 모든 노드가 UNKNOWN 상태로 표시됩니다. 제어 영역에 대한 연결 기능이 해제되었기 때문에 어떤 작업도 수행할 수 없습니다. 제어 영역을 검사하면 로그에 다음과 비슷한 로그가 표시됩니다.

error checking if node NODE_NAME is shutdown: unimplemented
가능한 원인

VPC 네트워크 피어링 연결이 실수로 삭제되었습니다.

해결 방법

다음 단계를 따르세요.

  • 새로운 임시 VPC 네트워크 피어링 클러스터를 만듭니다. 클러스터를 만들면 VPC 네트워크 피어링이 다시 생성되고 이전의 클러스터가 정상 작동으로 복원됩니다.

  • 이전 클러스터가 정상 작동으로 복원된 후 임시로 생성된 VPC 네트워크 피어링 클러스터를 삭제합니다.

클러스터가 활성 피어와 겹침

증상

비공개 클러스터를 만들려고 하면 다음과 비슷한 오류가 반환됩니다.

Google Compute Engine: An IP range in the peer network overlaps with an IP
range in an active peer of the local network.
가능한 원인

겹치는 제어 영역 CIDR을 선택했습니다.

해결 방법

클러스터를 삭제하고 다른 제어 영역 CIDR을 사용하여 다시 만듭니다.

비공개 클러스터의 제어 영역에 연결할 수 없음

클러스터 엔드포인트 액세스 구성을 구현하여 클러스터 제어 영역의 연결 가능성을 높입니다. 자세한 내용은 클러스터 엔드포인트에 액세스를 참조하세요.

증상

비공개 클러스터를 만든 후 클러스터에 kubectl 명령어를 실행하려고 하면 다음 중 하나와 비슷한 오류가 반환됩니다.

Unable to connect to the server: dial tcp [IP_ADDRESS]: connect: connection
timed out.

Unable to connect to the server: dial tcp [IP_ADDRESS]: i/o timeout.
가능한 원인

kubectl이 클러스터 제어 영역에 연결할 수 없습니다.

해결 방법

kubeconfig에 대해 클러스터 사용자 인증 정보가 생성되었거나 올바른 컨텍스트가 활성화되었는지 확인합니다. 클러스터 사용자 인증 정보 설정에 대한 자세한 내용은 kubeconfig 항목 생성을 참조하세요.

외부 IP 주소를 사용하여 제어 영역에 액세스하는 것이 허용되는지 확인합니다. 클러스터 컨트롤 플레인에 대한 외부 액세스를 중지하면 클러스터가 인터넷에서 격리됩니다. 클러스터를 만든 후에는 이 구성을 변경할 수 없습니다. 이 구성을 사용하면 승인된 내부 네트워크 CIDR 범위 또는 예약된 네트워크만 제어 영역에 액세스할 수 있습니다.

  1. 원본 IP 주소가 제어 영역에 도달하도록 승인되었는지 확인합니다.

      gcloud container clusters describe CLUSTER_NAME \
      --format="value(masterAuthorizedNetworksConfig)"\
      --location=COMPUTE_LOCATION

    다음을 바꿉니다.

    원본 IP 주소가 승인되지 않으면 출력에서 원본 IP 주소가 포함되지 않은 빈 결과(중괄호만) 또는 CIDR 범위가 반환될 수 있습니다.

    cidrBlocks:
  cidrBlock: 10.XXX.X.XX/32
  displayName: jumphost
  cidrBlock: 35.XXX.XXX.XX/32
  displayName: cloud shell
enabled: true

  2. 제어 영역에 액세스할 수 있도록 승인된 네트워크를 추가합니다.

온프레미스 환경 또는 클러스터 위치와 다른 리전에서 kubectl 명령어를 실행하는 경우 제어 영역 비공개 엔드포인트 전역 액세스가 사용 설정되어 있는지 확인합니다. 자세한 내용은 제어 영역의 비공개 엔드포인트에 전역 액세스를 참조하세요.

  1. 클러스터를 설명하여 제어 액세스 구성 응답을 확인합니다.

    gcloud container clusters describe CLUSTER_NAME \
    --location=COMPUTE_LOCATION \
    --flatten "privateClusterConfig.masterGlobalAccessConfig"

    다음을 바꿉니다.

    성공적인 출력은 다음과 비슷합니다.

      enabled: true

  2. null이 반환되면 제어 영역에 대한 전역 액세스를 사용 설정합니다.

겹치는 IPv4 CIDR 블록으로 인해 클러스터를 만들 수 없음

증상

gcloud container clusters create는 다음과 비슷한 오류를 반환합니다.

The given master_ipv4_cidr 10.128.0.0/28 overlaps with an existing network
10.128.0.0/20.
가능한 원인

VPC의 기존 서브넷과 겹치는 제어 영역 CIDR 블록을 지정했습니다.

해결 방법

--master-ipv4-cidr의 기존 서브넷과 겹치지 않는 CIDR 블록을 지정합니다.

이미 다른 클러스터에서 사용 중인 서비스 범위로 인해 클러스터를 만들 수 없음

증상

비공개 클러스터를 만들려고 하면 다음과 비슷한 오류가 반환됩니다.

Services range [ALIAS_IP_RANGE] in network [VPC_NETWORK], subnetwork
[SUBNET_NAME] is already used by another cluster.
가능한 원인

다음 중 하나입니다.

  • 다른 클러스터에서 아직 사용 중인 서비스 범위를 선택했거나 클러스터가 삭제되지 않았습니다.
  • 삭제된 서비스 범위를 사용하는 클러스터가 있지만 보조 범위 메타데이터가 제대로 삭제되지 않았습니다. GKE 클러스터의 보조 범위는 Compute Engine 메타데이터에 저장되며 클러스터가 삭제되면 삭제되어야 합니다. 클러스터가 성공적으로 삭제되더라도 메타데이터가 삭제되지 않을 수 있습니다.
해결 방법

다음 단계를 따르세요.

  • 기존 클러스터에서 서비스 범위를 사용하고 있는지 확인합니다. gcloud container clusters list 명령어를 filter 플래그와 함께 사용하여 클러스터를 검색할 수 있습니다. 서비스 범위를 사용하는 기존 클러스터가 있으면 클러스터를 삭제하거나 새 서비스 범위를 만들어야 합니다.
  • 기존 클러스터에서 서비스 범위를 사용하지 않는 경우 사용하려는 서비스 범위와 일치하는 메타데이터 항목을 수동으로 삭제합니다.

서브넷을 만들 수 없음

증상

자동 서브넷을 사용하여 비공개 클러스터를 만들거나 커스텀 서브넷을 만들려고 하면 다음과 같은 오류가 발생할 수 있습니다.

An IP range in the peer network overlaps
with an IP range in one of the active peers of the local network.
가능한 원인

지정한 제어 영역 CIDR 범위가 클러스터의 다른 IP 범위와 겹칩니다. 최근에 비공개 클러스터를 삭제했고 동일한 제어 영역 CIDR을 사용하여 새 비공개 클러스터를 만들려고 하는 경우에도 이 문제가 발생할 수 있습니다.

해결 방법

다른 CIDR 범위를 사용해 봅니다.

공개 Docker Hub에서 이미지를 가져올 수 없음

증상

클러스터에서 실행 중인 포드가 kubectl describe에 경고를 표시합니다.

Failed to pull image: rpc error: code = Unknown desc = Error response
from daemon: Get https://registry-1.docker.io/v2/: net/http: request canceled
while waiting for connection (Client.Timeout exceeded while awaiting
headers)
가능한 원인

비공개 클러스터의 노드에 외부 IP 주소가 없으므로 인터넷 액세스 요구사항을 충족하지 않습니다. 단, 비공개 Google 액세스를 사용 설정하고 네트워크 요구사항을 충족한 경우 노드는 Artifact Registry를 포함한 Google Cloud API 및 서비스에 액세스할 수 있습니다.

해결 방법

다음 해결 방법 중 하나를 사용하세요.

  • 비공개 클러스터의 이미지를 Docker Hub에서 Artifact Registry로 복사합니다. 자세한 내용은 타사 레지스트리에서 컨테이너 마이그레이션을 참조하세요.

  • GKE는 자주 액세스되는 Docker Hub 이미지의 캐시된 복사본을 자동으로 mirror.gcr.io에서 확인합니다.

  • Docker Hub 또는 다른 공개 저장소에서 이미지를 가져와야 하는 경우 정적 0.0.0.0/0 경로의 대상인 Cloud NAT 또는 인스턴스 기반 프록시를 사용합니다.

허용 웹훅 타임아웃을 트리거하는 API 요청

증상

443이 아닌 targetPort로 서비스를 사용하도록 구성된 허용 웹훅을 트리거하는 API 요청이 시간 초과되어 요청이 실패합니다.

Error from server (Timeout): request did not complete within requested timeout 30s
가능한 원인

기본적으로 방화벽은 포트 443(HTTPS) 및 10250(kubelet)을 제외한 노드에 대한 TCP 연결을 허용하지 않습니다. 트래픽을 허용하는 커스텀 방화벽 규칙이 없으면 443 이외의 포트에서 포드와 통신을 시도하는 허용 웹훅이 실패합니다.

해결 방법

구체적 사용 사례에 맞는 방화벽 규칙을 추가합니다.

상태 점검 실패로 인해 클러스터를 만들 수 없음

증상

비공개 클러스터를 만들면 상태 점검 단계에서 중지되어 다음 중 하나와 유사한 오류가 보고됩니다.

All cluster resources were brought up, but only 0 of 2 have registered.

All cluster resources were brought up, but: 3 nodes out of 4 are unhealthy
가능한 원인

다음 중 하나인 경우:

  • 클러스터 노드는 Cloud Storage API(storage.googleapis.com)에서 필요한 바이너리를 다운로드할 수 없습니다.
  • 이그레스 트래픽을 제한하는 방화벽 규칙
  • 공유 VPC IAM 권한이 잘못되었습니다.
  • 비공개 Google 액세스를 사용하려면 *.gcr.io의 DNS를 구성해야 합니다.
해결 방법

다음 해결 방법 중 하나를 사용하세요.

kubelet 포드 샌드박스를 만들 수 없음

증상

비공개 클러스터를 만든 후 다음 중 하나와 비슷한 오류가 보고됩니다.

Warning  FailedCreatePodSandBox  12s (x9 over 4m)      kubelet  Failed to create pod sandbox: rpc error: code = Unknown desc = Error response from daemon: Get https://registry.k8s.io/v2/: net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers)

NetworkReady=false reason:NetworkPluginNotReady message:docker: network plugin is not ready: cni config uninitialized
가능한 원인

calico-node 또는 netd 포드는 *.gcr.io에 도달할 수 없습니다.

해결 방법

다음 해결 방법 중 하나를 사용하세요.

비공개 클러스터 노드가 생성되었지만 클러스터에 조인되지 않음

비공개 클러스터에서 사용 중인 VPC에서 커스텀 라우팅 및 타사 네트워크 어플라이언스를 사용할 때 기본 인터넷 게이트웨이 대신 기본 경로(0.0.0.0/0)가 리디렉션되는 경우가 많습니다. 제어 영역 연결 외에도 다음 대상에 연결할 수 있는지 확인해야 합니다.

  • *.googleapis.com
  • *.gcr.io
  • gcr.io

3개 도메인 모두에 대해 비공개 Google 액세스를 구성합니다. 이 권장사항을 따르면 새 노드가 인터넷 연결 트래픽 제한을 제한하면서 클러스터를 시작하고 조인할 수 있습니다.

비공개 GKE 클러스터의 워크로드에서 인터넷에 액세스할 수 없음

비공개 GKE 클러스터의 포드는 인터넷에 액세스할 수 없습니다. 예를 들어 exec shell 포드에서 apt update 명령어를 실행한 후 다음과 비슷한 오류를 보고합니다.

0% [Connecting to deb.debian.org (199.232.98.132)] [Connecting to security.debian.org (151.101.130.132)]

클러스터의 포드에 사용되는 서브넷 보조 IP 주소 범위가 Cloud NAT 게이트웨이에 구성되지 않은 경우 포드는 Cloud NAT 게이트웨이에 대해 구성된 외부 IP 주소가 없으므로 인터넷에 연결할 수 없습니다.

클러스터에 사용되는 서브넷에 대해 최소한 다음 서브넷 IP 주소 범위를 적용하도록 Cloud NAT 게이트웨이를 구성해야 합니다.

  • 서브넷 기본 IP 주소 범위(노드에 사용됨)
  • 클러스터의 포드에 사용되는 서브넷 보조 IP 주소 범위
  • 클러스터의 서비스에 사용되는 서브넷 보조 IP 주소 범위

자세한 내용은 포드에 사용되는 보조 서브넷 IP 범위를 추가하는 방법을 참조하세요.