다음 섹션에서는 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 컨트롤러의 로그를 검사하여 디버깅할 수 있습니다.
kube-system
네임스페이스에서 Cluster API 컨트롤러 pod의 이름을 찾습니다. 여기서 [ADMIN_CLUSTER_KUBECONFIG]는 관리자 클러스터의 kubeconfig 파일 경로입니다.kubectl --kubeconfig [ADMIN_CLUSTER_KUBECONFIG] -n kube-system get pods | grep clusterapi-controllers
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에 도움을 요청하세요.
알파 버전에서 생성된 클러스터가 등록 취소됨
연결 문서의 사용자 클러스터 등록을 참조하세요.
또한 클러스터를 삭제하고 다시 만들기를 선택할 수 있습니다.
스토리지
볼륨이 연결되지 않음
증상
gkectl diagnose cluster
의 결과는 다음과 같습니다.
Checking cluster object...PASS Checking machine objects...PASS Checking control plane pods...PASS Checking gke-connect pods...PASS Checking kube-system pods...PASS Checking gke-system pods...PASS Checking storage...FAIL PersistentVolume pvc-776459c3-d350-11e9-9db8-e297f465bc84: virtual disk "[datastore_nfs] kubevols/kubernetes-dynamic-pvc-776459c3-d350-11e9-9db8-e297f465bc84.vmdk" IS attached to machine "gsl-test-user-9b46dbf9b-9wdj7" but IS NOT listed in the Node.Status 1 storage errors
하나 이상의 pod가 ContainerCreating
상태로 멈춰 있고 다음과 같은 경고가 표시됩니다.
Events: Type Reason Age From Message ---- ------ ---- ---- ------- Warning FailedAttachVolume 6s (x6 over 31s) attachdetach-controller AttachVolume.Attach failed for volume "pvc-776459c3-d350-11e9-9db8-e297f465bc84" : Failed to add disk 'scsi0:6'.
가능한 원인
가상 디스크가 잘못된 가상 머신에 연결되어 있으면 Kubernetes 1.12의 문제 #32727이 원인일 수 있습니다.
해결 방법
가상 디스크가 잘못된 가상 머신에 연결되어 있으면 이를 수동으로 분리해야 할 수 있습니다.
- 노드를 드레이닝합니다.
안전한 노드 드레이닝을 참조하세요.
kubectl drain
명령어에--ignore-daemonsets
및--delete-local-data
플래그를 포함할 수 있습니다. - VM을 끕니다.
- vCenter에서 VM 하드웨어 구성을 수정하여 볼륨을 삭제합니다.
- VM을 켭니다.
- 노드를 차단 해제합니다.
볼륨이 사라짐
증상
gkectl diagnose cluster
의 결과는 다음과 같습니다.
Checking cluster object...PASS Checking machine objects...PASS Checking control plane pods...PASS Checking gke-connect pods...PASS Checking kube-system pods...PASS Checking gke-system pods...PASS Checking storage...FAIL PersistentVolume pvc-52161704-d350-11e9-9db8-e297f465bc84: virtual disk "[datastore_nfs] kubevols/kubernetes-dynamic-pvc-52161704-d350-11e9-9db8-e297f465bc84.vmdk" IS NOT found 1 storage errors
하나 이상의 pod가 ContainerCreating
상태로 멈춰 있고 다음과 같은 경고가 표시됩니다.
Events: Type Reason Age From Message ---- ------ ---- ---- ------- Warning FailedAttachVolume 71s (x28 over 42m) attachdetach-controller AttachVolume.Attach failed for volume "pvc-52161704-d350-11e9-9db8-e297f465bc84" : File []/vmfs/volumes/43416d29-03095e58/kubevols/ kubernetes-dynamic-pvc-52161704-d350-11e9-9db8-e297f465bc84.vmdk was not found
가능한 원인
VMDK 파일과 관련해서 '찾을 수 없음' 오류가 표시되면 가상 디스크가 영구적으로 삭제되었기 때문일 수 있습니다. 이 문제는 작업자가 가상 디스크 또는 가상 디스크가 연결된 가상 머신을 수동으로 삭제한 경우에 발생할 수 있습니다. 이를 방지하려면 사용자 클러스터 크기 조절과 클러스터 업그레이드의 설명대로 가상 머신을 관리하세요.
해결 방법
가상 디스크가 영구적으로 삭제된 경우 관련 Kubernetes 리소스를 수동으로 삭제해야 할 수 있습니다.
kubectl delete pvc [PVC_NAME].
을 실행하여 PV를 참조한 PVC를 삭제합니다.kubectl delete pod [POD_NAME].
을 실행하여 PVC를 참조한 포드를 삭제합니다.- 2단계를 반복합니다. (자세한 내용은 Kubernetes 문제 74374를 참조하세요.)
vSphere CSI 볼륨이 분리되지 않음
증상
FailedAttachVolume
경고 표시와 함께 ContainerCreating
단계에 포드가 멈춰 있으면 다른 노드에서의 분리 실패로 인해 발생했을 수 있습니다.
다음 명령어를 실행하여 CSI 분리 오류를 찾습니다.
kubectl get volumeattachments -o=custom-columns=NAME:metadata.name,DETACH_ERROR:status.detachError.message
다음과 유사하게 출력됩니다.
NAME DETACH_ERROR csi-0e80d9be14dc09a49e1997cc17fc69dd8ce58254bd48d0d8e26a554d930a91e5 rpc error: code = Internal desc = QueryVolume failed for volumeID: "57549b5d-0ad3-48a9-aeca-42e64a773469". ServerFaultCode: NoPermission csi-164d56e3286e954befdf0f5a82d59031dbfd50709c927a0e6ccf21d1fa60192dcsi-8d9c3d0439f413fa9e176c63f5cc92bd67a33a1b76919d42c20347d52c57435c csi-e40d65005bc64c45735e91d7f7e54b2481a2bd41f5df7cc219a2c03608e8e7a8
가능한 원인
CNS > Searchable
권한이 vSphere 사용자에게 부여되지 않았습니다.
해결 방법
CNS > Searchable
권한을 vCenter 사용자 계정에 추가합니다. 분리 작업은 성공할 때까지 자동으로 재시도됩니다.
업그레이드
업그레이드 중 다운타임 정보
리소스 | 설명 |
---|---|
관리자 클러스터 | 관리자 클러스터가 다운되면 다운타임을 유발한 오류의 영향을 받지 않는 한 사용자 클러스터 제어 영역과 워크로드는 사용자 클러스터에서 계속 실행됩니다. |
사용자 클러스터 제어 영역 | 일반적으로 사용자 클러스터 제어 영역에는 뚜렷한 다운타임이 없어야 합니다. 하지만 Kubernetes API 서버로의 장기 실행 연결이 끊어져 다시 설정해야 할 수 있습니다. 이 경우 API 호출자는 연결을 설정할 때까지 다시 시도해야 합니다. 최악의 경우에는 업그레이드 중에 다운타임이 최대 1분간 발생할 수 있습니다. |
사용자 클러스터 노드 | 업그레이드 시 사용자 클러스터 노드를 변경해야 하는 경우 GKE On-Prem은 노드를 롤링 방식으로 다시 만들고 이 노드에서 실행 중인 pod를 다시 예약합니다. 적절한 podDisruptionBudget과 안티어피니티 규칙을 설정하여 워크로드에 대한 영향을 방지할 수 있습니다. |
사용자 클러스터 크기 조절
사용자 클러스터 크기 조절 실패
- 증상
사용자 클러스터의 크기 조절 작업이 실패합니다.
- 가능한 원인
여러 요인으로 인해 크기 조절 작업이 실패할 수 있습니다.
- 해결 방법
크기 조절에 실패하는 경우 다음 단계를 따르세요.
클러스터의 MachineDeployment 상태를 살펴보고 이벤트 또는 오류 메시지가 있는지 확인합니다.
kubectl describe machinedeployments [MACHINE_DEPLOYMENT_NAME]
새로 생성된 머신에 오류가 있는지 확인합니다.
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 주소가 사용되지 않았는지 확인합니다. 충돌이 있는 경우 사용자 환경에서 충돌을 해결해야 합니다.
vSphere
govc
로 디버깅
vSphere 관련 문제가 발생하면 govc
를 사용하여 문제 해결을 수행할 수 있습니다. 예를 들어 vCenter 사용자 계정에 대한 권한 및 액세스를 쉽게 확인하고 vSphere 로그를 수집할 수 있습니다.
vCenter 인증서 변경
평가 또는 기본 설정 모드에서 vCenter Server를 실행 중이고 여기에 생성된 TLS 인증서가 있으면 시간 경과에 따라 이 인증서가 변경될 수 있습니다. 인증서가 변경되었으면 실행 중인 클러스터에서 새 인증서를 확인할 수 있도록 해야 합니다.
새 vCenter 인증서를 검색하고 이를 파일로 저장합니다.
true | openssl s_client -connect [VCENTER_IP_ADDRESS]:443 -showcerts 2>/dev/null | sed -ne '/-BEGIN/,/-END/p' > vcenter.pem
이제 각 클러스터에 대해 vSphere 및 vCenter 인증서가 포함된 ConfigMap을 삭제하고 새 인증서로 새 ConfigMap을 만듭니다. 예를 들면 다음과 같습니다.
kubectl --kubeconfig kubeconfig delete configmap vsphere-ca-certificate -n kube-system
kubectl --kubeconfig kubeconfig delete configmap vsphere-ca-certificate -n user-cluster1
kubectl --kubeconfig kubeconfig create configmap -n user-cluster1 --dry-run vsphere-ca-certificate --from-file=ca.crt=vcenter.pem -o yaml | kubectl --kubeconfig kubeconfig apply -f -
kubectl --kubeconfig kubeconfig create configmap -n kube-system --dry-run vsphere-ca-certificate --from-file=ca.crt=vcenter.pem -o yaml | kubectl --kubeconfig kubeconfig apply -f -
각 클러스터에서 clusterapi-controllers pod를 삭제합니다. pod가 다시 시작되면 새 인증서가 사용됩니다. 예를 들면 다음과 같습니다.
kubectl --kubeconfig kubeconfig -n kube-system get pods
kubectl --kubeconfig kubeconfig -n kube-system delete pod clusterapi-controllers-...
기타
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 라이선스가 만료되면 예기치 않은 오류가 발생할 수 있습니다.