문제 해결

다음 섹션에서는 GKE On-Prem을 사용할 때 발생 가능한 문제와 이를 해결하는 방법을 설명합니다.

시작하기 전에

문제 해결을 시작하기 전에 다음 섹션을 확인하세요.

gkectl을 사용하여 클러스터 문제 진단

gkectl diagnose 명령어를 사용하여 클러스터 문제를 식별하고 클러스터 정보를 Google과 공유하세요. 클러스터 문제 진단을 참조하세요.

기본 로깅 동작

gkectl 및 gkeadm의 경우 기본 로깅 설정만 사용해도 됩니다.

  • 기본적으로 로그 항목은 다음과 같이 저장됩니다.

    • gkectl의 기본 로그 파일은 /home/ubuntu/.config/gke-on-prem/logs/gkectl-$(date).log이며 파일은 gkectl을 실행하는 로컬 디렉터리의 logs/gkectl-$(date).log 파일과 심볼릭 링크됩니다.
    • gkeadm의 경우 기본 로그 파일은 gkeadm을 실행하는 로컬 디렉터리의 logs/gkeadm-$(date).log입니다.
  • 모든 로그 항목은 터미널에서 출력되지 않더라도 로그 파일에 저장됩니다(--alsologtostderr가 false인 경우).
  • -v5 세부정보 수준(기본값)에는 지원팀에 필요한 모든 로그 항목이 포함됩니다.
  • 로그 파일에는 실행된 명령어와 실패 메시지도 포함되어 있습니다.

도움이 필요한 경우 로그 파일을 지원팀에 보내는 것이 좋습니다.

로그 파일에 기본값이 아닌 위치 지정

gkectl 로그 파일에 기본값이 아닌 위치를 지정하려면 --log_file 플래그를 사용합니다. 지정한 로그 파일은 로컬 디렉터리와 심볼릭 링크되지 않습니다.

gkeadm 로그 파일에 기본값이 아닌 위치를 지정하려면 --log_file 플래그를 사용합니다.

관리자 클러스터에서 Cluster API 로그 찾기

관리자 제어 영역이 시작된 후에 VM을 시작하지 못하는 경우 다음 안내에 따라 관리자 클러스터에서 Cluster API 컨트롤러의 로그를 검사하여 디버깅할 수 있습니다.

  1. kube-system 네임스페이스에서 Cluster API 컨트롤러 pod의 이름을 찾습니다. 여기서 [ADMIN_CLUSTER_KUBECONFIG]는 관리자 클러스터의 kubeconfig 파일 경로입니다.

    kubectl --kubeconfig [ADMIN_CLUSTER_KUBECONFIG] -n kube-system get pods | grep clusterapi-controllers

  2. pod의 로그를 엽니다. 여기서 [POD_NAME]은 pod 이름입니다. 원하는 경우 grep 또는 유사한 도구를 사용하여 오류를 검색할 수 있습니다.

    kubectl --kubeconfig [ADMIN_CLUSTER_KUBECONFIG] -n kube-system logs [POD_NAME] vsphere-controller-manager

설치

관리자 클러스터 제어 영역 노드의 kubeconfig를 사용하여 F5 BIG-IP 문제 디버깅

설치 후 GKE On-Prem은 이름이 internal-cluster-kubeconfig-debug인 관리자 워크스테이션의 홈 디렉터리에 kubeconfig 파일을 생성합니다. 이 kubeconfig 파일은 관리자 클러스터의 kubeconfig와 동일하지만 관리 제어 영역이 실행되는 관리자 클러스터의 제어 영역 노드를 직접 가리킨다는 것만 다릅니다. internal-cluster-kubeconfig-debug 파일을 사용하여 F5 BIG-IP 문제를 디버깅할 수 있습니다.

gkectl check-config 검사 실패: F5 BIG-IP 파티션을 찾을 수 없음

증상

F5 BIG-IP 파티션이 존재하더라도 이를 찾을 수 없어서 검사가 실패합니다.

가능한 원인

F5 BIG-IP API 관련 문제로 인해 검사가 실패할 수 있습니다.

해결 방법

gkectl check-config를 다시 실행해 보세요.

gkectl prepare --validate-attestations 실패: 빌드 증명을 검사할 수 없음

증상

선택사항인 --validate-attestations 플래그로 gkectl prepare를 실행하면 다음 오류가 반환됩니다.

could not validate build attestation for gcr.io/gke-on-prem-release/.../...: VIOLATES_POLICY
가능한 원인

해당 이미지에 대한 증명이 존재하지 않을 수 있습니다.

해결 방법

관리 워크스테이션 만들기 안내를 따라 관리 워크스테이션 OVA를 다시 다운로드하고 배포하세요. 문제가 계속되면 Google에 도움을 요청하세요.

부트스트랩 클러스터 로그를 사용하여 디버깅

설치 중 GKE On-Prem은 임시 부트스트랩 클러스터를 만듭니다. 설치가 성공한 후에는 GKE On-Prem이 부트스트랩 클러스터를 삭제하고 관리자 및 사용자 클러스터를 남겨둡니다. 일반적으로 이 클러스터와 상호작용할 이유가 없습니다.

설치 중 문제가 발생하고 --cleanup-external-cluster=false를 gkectl create cluster에 전달한 경우 부트스트랩 클러스터의 로그를 사용하여 디버깅하는 것이 유용할 수 있습니다. Pod를 찾은 후 해당 로그를 가져올 수 있습니다.

kubectl --kubeconfig /home/ubuntu/.kube/kind-config-gkectl get pods -n kube-system
kubectl --kubeconfig /home/ubuntu/.kube/kind-config-gkectl -n kube-system get logs [POD_NAME]

관리 워크스테이션

openssl이 관리자 워크스테이션 OVA를 검사할 수 없음

증상

관리자 워크스테이션 OVA 파일에 openssl dgst를 실행하면 Verified OK가 반환되지 않습니다.

가능한 원인

OVA 파일에 검사 성공을 방해하는 문제가 있습니다.

해결 방법

관리자 워크스테이션 OVA 다운로드의 설명대로 관리자 워크스테이션 OVA를 다시 다운로드하고 배포하세요. 문제가 계속되면 Google에 도움을 요청하세요.

연결

사용자 클러스터를 등록할 수 없음

사용자 클러스터를 등록하는 데 문제가 발생하면 Google에 도움을 요청하세요.

알파 버전에서 생성된 클러스터가 등록 취소됨

연결 문서의 사용자 클러스터 등록을 참조하세요.

또한 클러스터를 삭제하고 다시 만들기를 선택할 수 있습니다.

업그레이드

업그레이드 중 다운타임 정보

리소스 설명
관리자 클러스터

관리자 클러스터가 다운되면 다운타임을 유발한 오류의 영향을 받지 않는 한 사용자 클러스터 제어 영역과 워크로드는 사용자 클러스터에서 계속 실행됩니다.
사용자 클러스터 제어 영역

일반적으로 사용자 클러스터 제어 영역에는 뚜렷한 다운타임이 없어야 합니다. 하지만 Kubernetes API 서버로의 장기 실행 연결이 끊어져 다시 설정해야 할 수 있습니다. 이 경우 API 호출자는 연결을 설정할 때까지 다시 시도해야 합니다. 최악의 경우에는 업그레이드 중에 다운타임이 최대 1분간 발생할 수 있습니다.
사용자 클러스터 노드

업그레이드 시 사용자 클러스터 노드를 변경해야 하는 경우 GKE On-Prem은 노드를 롤링 방식으로 다시 만들고 이 노드에서 실행 중인 pod를 다시 예약합니다. 적절한 podDisruptionBudget과 안티어피니티 규칙을 설정하여 워크로드에 대한 영향을 방지할 수 있습니다.

사용자 클러스터 크기 조절

사용자 클러스터 크기 조절 실패

증상

사용자 클러스터의 크기 조절 작업이 실패합니다.

가능한 원인

여러 요인으로 인해 크기 조절 작업이 실패할 수 있습니다.

해결 방법

크기 조절에 실패하는 경우 다음 단계를 따르세요.

  1. 클러스터의 MachineDeployment 상태를 살펴보고 이벤트 또는 오류 메시지가 있는지 확인합니다.

    kubectl describe machinedeployments [MACHINE_DEPLOYMENT_NAME]

  2. 새로 생성된 머신에 오류가 있는지 확인합니다.

    kubectl describe machine [MACHINE_NAME]

오류: '할당할 수 있는 주소가 없음'

증상

사용자 클러스터의 크기를 조절하면 kubectl describe machine [MACHINE_NAME]에 다음 오류가 표시됩니다.

Events:
   Type     Reason  Age                From                    Message
   ----     ------  ----               ----                    -------
   Warning  Failed  9s (x13 over 56s)  machineipam-controller  ipam: no addresses can be allocated
가능한 원인

사용자 클러스터에 사용할 수 있는 IP 주소가 충분하지 않습니다.

해결 방법

클러스터에 더 많은 IP 주소를 할당합니다. 그런 다음 영향을 받은 머신을 삭제합니다.

kubectl delete machine [MACHINE_NAME]

클러스터가 올바르게 구성되면 IP 주소로 대체 머신이 생성됩니다.

할당된 IP 주소의 수가 충분하지만 클러스터에 머신이 등록되지 않음

증상

네트워크에 할당된 주소가 충분하지만 사용자 클러스터에 머신이 등록되지 않습니다.

가능한 원인

IP 충돌이 있을 수 있습니다. 해당 IP를 다른 머신 또는 부하 분산기에서 사용하고 있을 수 있습니다.

해결 방법

영향을 받는 머신의 IP 주소가 사용되지 않았는지 확인합니다. 충돌이 있는 경우 사용자 환경에서 충돌을 해결해야 합니다.

기타

Terraform vSphere 제공업체 세션 한도

GKE On-Prem은 Terraform의 vSphere 제공업체를 이용하여 vSphere 환경에 VM을 가져옵니다. 제공업체의 세션 한도는 1,000개입니다. 현재 구현은 사용 후 활성 세션을 닫지 않습니다. 실행 중인 세션이 너무 많으면 503 오류가 발생할 수 있습니다.

세션은 300초 후 자동으로 닫힙니다.

증상

실행 중인 세션이 너무 많으면 다음과 같은 오류가 발생할 수 있습니다.

Error connecting to CIS REST endpoint: Login failed: body:
  {"type":"com.vmware.vapi.std.errors.service_unavailable","value":
  {"messages":[{"args":["1000","1000"],"default_message":"Sessions count is
  limited to 1000. Existing sessions are 1000.",
  "id":"com.vmware.vapi.endpoint.failedToLoginMaxSessionCountReached"}]}},
  status: 503 Service Unavailable
가능한 원인

환경에서 실행 중인 Terraform 제공업체 세션이 너무 많습니다.

해결 방법

이는 현재 정상적인 작동입니다. 세션은 300초 후 자동으로 닫힙니다. 자세한 내용은 GitHub 문제 #618을 참조하세요.

Docker용 프록시 사용: oauth2: cannot fetch token

증상

프록시를 사용하는 동안 다음 오류가 발생할 수 있습니다.

oauth2: cannot fetch token: Post https://oauth2.googleapis.com/token: proxyconnect tcp: tls: oversized record received with length 20527
가능한 원인

HTTP 대신 HTTPS 프록시를 제공했을 수 있습니다.

해결 방법

Docker 구성에서 프록시 주소를 https:// 대신 http://로 변경합니다.

라이선스가 올바른지 확인

특히 평가판 라이선스를 사용할 때는 해당 라이선스가 올바른지 확인해야 합니다. F5, ESXi 호스트, vCenter 라이선스가 만료되면 예기치 않은 오류가 발생할 수 있습니다.