이 페이지에서는 VMware용 Anthos 클러스터(GKE On-Prem)에서 클러스터 생성, 업그레이드, 크기 조절과 관련된 문제를 조사하는 방법을 설명합니다.
gkectl 및 gkeadm의 기본 로깅 동작
gkectl 및 gkeadm의 경우 기본 로깅 설정만 사용해도 됩니다.
gkectl의 경우 기본 로그 파일은/home/ubuntu/.config/gke-on-prem/logs/gkectl-$(date).log이며 파일은gkectl을 실행하는 로컬 디렉터리의logs/gkectl-$(date).log파일과 심볼릭 링크됩니다.gkeadm의 경우 기본 로그 파일은gkeadm을 실행하는 로컬 디렉터리의logs/gkeadm-$(date).log입니다.기본
-v5세부정보 수준에는 지원팀에서 필요한 모든 로그 항목이 포함됩니다.로그 파일에는 실행된 명령어와 실패 메시지가 포함됩니다.
도움이 필요한 경우 로그 파일을 지원팀에 보내는 것이 좋습니다.
로그 파일에 기본 위치가 아닌 위치 지정
gkectl 로그 파일에 기본 위치가 아닌 위치를 지정하려면 --log_file 플래그를 사용합니다. 지정한 로그 파일은 로컬 디렉터리와 심볼릭 링크되지 않습니다.
gkeadm 로그 파일에 기본 위치가 아닌 위치를 지정하려면 --log_file 플래그를 사용합니다.
관리자 클러스터에서 Cluster API 로그 찾기
관리자 제어 영역이 시작된 후 VM이 시작되지 않으면 관리자 클러스터의 Cluster API 컨트롤러 Pod에서 로그를 검사하여 문제를 조사할 수 있습니다.
Cluster API 컨트롤러 Pod 이름을 찾습니다.
kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG --namespace kube-system \ get pods | grep clusterapi-controllersvsphere-controller-manager에서 로그를 봅니다. 먼저 Pod를 지정하되 컨테이너를 지정하지 않습니다.kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG --namespace kube-system \ logs POD_NAME출력에는 컨테이너를 지정해야 함을 알려주며 Pod에 있는 컨테이너의 이름이 표시됩니다. 예를 들면 다음과 같습니다.
... a container name must be specified ..., choose one of: [clusterapi-controller-manager vsphere-controller-manager rbac-proxy]
컨테이너를 선택하고 로그를 봅니다.
kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG --namespace kube-system \ logs POD_NAME --container CONTAINER_NAME
govc를 사용하여 vSphere 문제 해결
govc를 사용하여 vSphere 문제를 조사할 수 있습니다. 예를 들어 vCenter 사용자 계정에 대한 권한과 액세스 권한을 확인하고 vSphere 로그를 수집할 수 있습니다.
부트스트랩 클러스터 로그를 사용하여 디버깅
설치 중에 VMware용 Anthos 클러스터에서 임시 부트스트랩 클러스터를 만듭니다. 설치가 성공하면 VMware용 Anthos 클러스터에서 부트스트랩 클러스터를 삭제하고 관리자 클러스터와 사용자 클러스터를 남겨둡니다. 일반적으로 부트스트랩 클러스터와 상호작용할 이유가 없습니다.
--cleanup-external-cluster=false를 gkectl create cluster에 전달하면 부트스트랩 클러스터는 삭제되지 않으며 부트스트랩 클러스터의 로그를 사용하여 설치 문제를 디버깅할 수 있습니다.
kube-system네임스페이스에서 실행 중인 포드의 이름을 찾습니다.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
부트스트랩 클러스터에서 직접 로그를 가져오려면 클러스터 만들기, 업데이트 및 업그레이드 동안 다음 명령어를 실행할 수 있습니다.
docker exec -it gkectl-control-plane bash
이 명령어는 부트스트랩 클러스터에서 실행되는 gkectl-control-plane 컨테이너 내에서 터미널을 엽니다.
kubelet 및 containerd 로그를 검사하려면 다음 명령어를 사용하고 출력에서 오류 또는 경고를 찾습니다.
systemctl status -l kubelet journalctl --utc -u kubelet systemctl status -l containerd journalctl --utc -u containerd
업그레이드 후 노드 풀 롤백
사용자 클러스터를 업그레이드한 후 클러스터 노드에서 문제가 발견되면 선택한 노드 풀을 이전 버전으로 롤백할 수 있습니다.
선택한 노드 풀 롤백은 Ubuntu 및 COS 노드 풀에서 지원되지만 Windows 노드 풀에서는 지원되지 않습니다.
노드 풀 버전이 동일하거나 사용자 클러스터 제어 영역 버전 하나 이전의 마이너 버전일 수 있습니다. 예를 들어 제어 영역이 버전 1.14인 경우 노드 풀은 버전 1.14 또는 1.13일 수 있습니다.
사용 가능한 노드 풀 버전 보기
최근 사용자 클러스터 워커 노드와 제어 영역을 버전 1.13.1-gke.35에서 버전 1.14.0으로 업그레이드했는데 업그레이드된 워커 노드에 문제가 있다고 가정해 보겠습니다. 그래서 하나 이상의 노드 풀을 이전에 실행 중인 버전(1.13.1-gke.35)으로 롤백하기로 결정합니다.
롤백용으로 이전 버전을 사용할 수 있는지 확인합니다.
gkectl version --cluster-name USER_CLUSTER_NAME --kubeconfig ADMIN_CLUSTER_KUBECONFIG
user cluster version: 1.14.0-gke.x node pools: - pool-1: - version: 1.14.0-gke.x - previous version: 1.13.1-gke.35 - pool-2: - version: 1.14.0-gke.x - previous version: 1.13.1-gke.35 available node pool versions: - 1.13.1-gke.35 - 1.14.0-gke.x
노드 풀 롤백
한 번에 하나의 노드 풀을 롤백하거나 한 번에 여러 노드 풀을 롤백할 수 있습니다.
사용자 클러스터 구성 파일의 하나 이상의 노드 풀에서 gkeOnPremVersion 값을 이전 버전(이 예시의 경우 1.13.1-gke.35)으로 설정합니다.
nodePools: - name: pool-1 cpus: 4 memoryMB: 8192 replicas: 3 gkeOnPremVersion: 1.13.1-gke.35 ...
노드 풀을 롤백하도록 클러스터를 업데이트합니다.
gkectl update cluster --config USER_CLUSTER_CONFIG --kubeconfig ADMIN_CLUSTER_KUBECONFIG
롤백을 확인합니다.
gkectl version --cluster-name USER_CLUSTER_NAME --kubeconfig ADMIN_CLUSTER_KUBECONFIG
pool-1이 버전 1.13.1-gke.35로 롤백되었음을 보여줍니다.
user cluster version: 1.14.0-gke.x node pools: - pool-1: - version: 1.13.1-gke.35 - previous version: 1.14.0-gke.x - pool-2: - version: 1.14.0-gke.x - previous version: 1.13.1-gke.35 available node pool versions: - 1.13.1-gke.35 - 1.14.0-gke.x
새 패치 버전으로 업그레이드
새로운 패치 버전(예: 1.14.1)에서 문제가 수정되었다고 가정합니다. 이제 모든 노드 풀과 제어 영역을 새 패치 버전으로 업그레이드할 수 있습니다.
사용자 클러스터 구성 파일에서 다음을 수행합니다.
gkeOnPremVersion의 값을 새 패치 버전(이 예시에서는 1.14.1-gke.x)으로 설정합니다.각 노드 풀마다
gkeOnPremVersion필드를 삭제하거나 빈 문자열로 설정합니다. 노드 풀에 지정된 버전이 없으면 노드 풀 버전은 기본적으로 클러스터에 지정된 버전으로 지정됩니다.
예:
gkeOnPremVersion: 1.14.1-gke.x nodePools: - name: pool-1 cpus: 4 memoryMB: 8192 replicas: 3 gkeOnPremVersion: "" - name: pool-2 cpus: 8 memoryMB: 8192 replicas: 2 gkeOnPremVersion: ""
VMware용 Anthos 클러스터 업그레이드에 설명된 대로 gkectl prepare 및 gkectl upgrade cluster를 실행합니다.
새 클러스터 버전을 확인하고 지금 롤백에 사용할 수 있는 버전을 확인합니다.
gkectl version --cluster-name USER_CLUSTER_NAME --kubeconfig ADMIN_CLUSTER_KUBECONFIG
user cluster version: 1.14.1-gke.y node pools: - pool-1: - version: 1.14.1-gke.y - previous version: 1.13.1-gke.35 - pool-2: - version: 1.14.1-gke.y - previous version: 1.13.1-gke.35 available node pool versions: - 1.13.1-gke.35 - 1.14.0-gke.x - 1.14.1-gke.y
내부 kubeconfig 파일을 사용하여 F5 BIG-IP 문제 디버깅
설치 후 VMware용 Anthos 클러스터는 관리자 워크스테이션의 홈 디렉터리에 internal-cluster-kubeconfig-debug라는 kubeconfig 파일을 생성합니다. 이 kubeconfig 파일은 관리자 클러스터의 kubeconfig 파일과 동일하지만 Kubernetes API 서버가 실행되는 관리자 클러스터의 제어 영역 노드를 직접 가리킨다는 점이 다릅니다. internal-cluster-kubeconfig-debug 파일을 사용하여 F5 BIG-IP 문제를 디버깅할 수 있습니다.
사용자 클러스터 크기 조절 실패
사용자 클러스터 크기 조절을 실패한 경우:
MachineDeployment 및 머신의 이름을 찾습니다.
kubectl --kubeconfig USER_CLUSTER_KUBECONFIG get machinedeployments --all-namespaces kubectl --kubeconfig USER_CLUSTER_KUBECONFIG get machines --all-namespaces
MachineDeployment를 설명하여 로그를 봅니다.
kubectl --kubeconfig USER_CLUSTER_KUBECONFIG describe machinedeployment MACHINE_DEPLOYMENT_NAME
새로 만든 머신에서 오류를 확인합니다.
kubectl --kubeconfig USER_CLUSTER_KUBECONFIG describe machine MACHINE_NAME
클러스터 크기 조절에 주소 할당 불가
이 문제는 사용자 클러스터 크기를 조절할 수 있는 IP 주소가 부족하면 발생합니다.
kubectl describe machine에 다음 오류가 표시됩니다.
Events: Type Reason Age From Message ---- ------ ---- ---- ------- Warning Failed 9s (x13 over 56s) machineipam-controller ipam: no addresses can be allocated
이 문제를 해결하려면 클러스터에 IP 주소를 더 할당합니다. 그런 다음 영향을 받은 머신을 삭제합니다.
kubectl --kubeconfig USER_CLUSTER_KUBECONFIG delete machine MACHINE_NAME
VMware용 Anthos 클러스터는 새 머신을 만들고 새롭게 사용할 수 있는 IP 주소 중 하나를 할당합니다.
할당된 IP 주소의 수가 충분하지만 클러스터에 머신이 등록되지 않음
IP 주소가 충돌하면 이 문제가 발생할 수 있습니다. 예를 들어 머신에 지정한 IP 주소가 부하 분산기에서 사용되고 있습니다.
이 문제를 해결하려면 머신 주소가 클러스터 구성 파일이나 Seesaw IP 차단 파일에 지정한 주소와 충돌하지 않도록 클러스터 IP 차단 파일을 업데이트합니다.
관리자 클러스터 생성 또는 업그레이드가 실패하면 스냅샷이 자동으로 생성됨
관리자 클러스터 만들기 또는 업그레이드를 시도할 때 작업이 실패하면 VMware용 Anthos 클러스터가 관리자 클러스터를 만들거나 업그레이드하는 데 사용되는 임시 클러스터인 부트스트랩 클러스터의 외부 스냅샷을 만듭니다. 이러한 부트스트랩 클러스터의 스냅샷은 관리자 클러스터에서 gkectl diagnose snapshot 명령어를 실행하여 작성된 스냅샷과 비슷하지만, 자동으로 트리거됩니다. 이러한 부트스트랩 클러스터의 스냅샷에는 관리자 클러스터 만들기 및 업그레이드 프로세스에 관한 중요한 디버깅 정보가 포함되어 있습니다. 필요한 경우 Google Cloud 지원팀에 이 스냅샷을 제공할 수 있습니다.
외부 스냅샷에는 클러스터 생성 또는 업그레이드 문제를 디버깅하기 위해 볼 수 있는 onprem-admin-cluster-controller의 포드 로그가 포함됩니다. 로그는 별도의 파일에 저장됩니다. 예를 들면 다음과 같습니다.
kubectl_logs_onprem-admin-cluster-controller-6767f6597-nws8g_--container_onprem-admin-cluster-controller_--kubeconfig_.home.ubuntu..kube.kind-config-gkectl_--namespace_kube-system
클러스터 업그레이드가 실패하면 상태 점검이 자동으로 실행됩니다.
관리자 또는 사용자 클러스터를 업그레이드하려고 할 때 이 작업이 실패하면 VMware용 Anthos 클러스터가 자동으로 클러스터에서 gkectl diagnose cluster 명령어를 실행합니다.
자동 진단을 건너뛰려면 --skip-diagnose-cluster 플래그를 gkectl upgrade에 전달합니다.
업그레이드 프로세스 중단
VMware용 Anthos 클러스터는 업그레이드 중 백그라운드에서 Kubernetes drain 명령어를 사용합니다. 이 drain 절차는 minAvailable: 1을 사용해서 PodDisruptionBudget(PDB)가 생성된 복제본이 한 개만 있는 배포에 의해 차단될 수 있습니다.
VMware용 Anthos 클러스터 버전 1.13에서는 Kubernetes 포드 이벤트를 통해 오류를 확인할 수 있습니다.
머신 이름을 찾습니다.
kubectl --kubeconfig USER_CLUSTER_KUBECONFIG get machines --all-namespaces
kubectl describe machine명령어를 사용하여 오류를 확인합니다.kubectl --kubeconfig USER_CLUSTER_KUBECONFIG describe machine MACHINE_NAME
출력 예시는 다음과 같습니다.
Events: Type Reason Age From Message ---- ------ ---- ---- ------- Warning PodEvictionTooLong 3m49s machine-controller Waiting too long(12m10.284294321s) for pod(default/test-deployment-669b85c4cc-z8pz7) eviction.
머신 객체 상태에 대한 자세한 분석을 보려면 gkectl diagnose cluster를 실행합니다.
...
Checking machineset...SUCCESS
Checking machine objects...FAILURE
Reason: 1 machine objects error(s).
Unhealthy Resources:
Pod test-deployment-669b85c4cc-7zjpq: Pod cannot be evicted successfully. There is 1 related PDB.
...
Checking all poddisruptionbudgets...FAILURE
Reason: 1 pod disruption budget error(s).
Unhealthy Resources:
PodDisruptionBudget test-pdb: default/test-pdb might be configured incorrectly, the total replicas(3) should be larger than spec.MinAvailable(3).
...
Some validation results were FAILURE or UNKNOWN. Check report above.
이 문제를 해결하려면 PDB를 저장하고 업그레이드를 시도하기 전에 클러스터에서 삭제합니다. 그런 후 업그레이드가 완료된 다음 PDB를 다시 추가하면 됩니다.
가상 머신 상태 진단
가상 머신을 만드는 중에 문제가 발생하면 gkectl diagnose cluster를 실행하여 가상 머신 상태를 진단합니다.
출력 예시는 다음과 같습니다.
- Validation Category: Cluster Healthiness
Checking cluster object...SUCCESS
Checking machine deployment...SUCCESS
Checking machineset...SUCCESS
Checking machine objects...SUCCESS
Checking machine VMs...FAILURE
Reason: 1 machine VMs error(s).
Unhealthy Resources:
Machine [NODE_NAME]: The VM's UUID "420fbe5c-4c8b-705a-8a05-ec636406f60" does not match the machine object's providerID "420fbe5c-4c8b-705a-8a05-ec636406f60e".
Debug Information:
null
...
Exit with error:
Cluster is unhealthy!
Run gkectl diagnose cluster automatically in gkectl diagnose snapshot
Public page https://cloud.google.com/anthos/clusters/docs/on-prem/latest/diagnose#overview_diagnose_snapshot
자세한 내용은 클러스터 문제 진단을 참조하세요.
누락된 사용자 클러스터 kubeconfig 파일 다시 만들기
다음 몇 가지 상황에서 사용자 클러스터 kubeconfig 파일을 다시 만들 수 있습니다.
- 사용자 클러스터를 만들려고 하고 만들기 작업이 실패하고 사용자 클러스터 kubeconfig 파일을 보유하려는 경우
- 사용자 클러스터 kubeconfig 파일이 누락된 경우(예: 삭제 후)
다음 명령어를 실행하여 사용자 클러스터 kubeconfig 파일을 다시 만듭니다.
kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG get secrets -n admin \
-o jsonpath='{.data.admin\.conf}' | base64 -d > USER_CLUSTER_KUBECONFIG
다음을 바꿉니다.
- USER_CLUSTER_KUBECONFIG: 사용자 클러스터의 새 kubeconfig 파일 이름
- ADMIN_CLUSTER_KUBECONFIG: 관리자 클러스터의 kubeconfig 파일 경로
업그레이드가 차단 해제되도록 지원되지 않는 변경사항 삭제
클러스터를 1.16 이하 버전으로 업그레이드하는 경우 대부분의 필드에 대한 변경사항은 업그레이드 중에 자동으로 무시됩니다. 즉, 업그레이드 중과 업그레이드 후에는 이러한 변경사항이 적용되지 않습니다.
사용자 클러스터를 1.28 이상 버전으로 업그레이드하는 경우 구성 파일에서 수행된 모든 변경사항을 검증하고 단순히 변경사항을 무시하는 대신 지원되지 않는 변경사항에 대한 오류를 반환합니다. 예를 들어 사용자 클러스터를 1.28로 업그레이드할 때 노드 자동 복구를 중지하려고 하면 다음 오류 메시지가 표시되면서 업그레이드가 실패합니다.
failed to generate desired create config: failed to generate desired OnPremUserCluster from seed config: failed to apply validating webhook to OnPremUserCluster: the following changes on immutable fields are forbidden during upgrade: (diff: -before, +after):
v1alpha1.OnPremUserClusterSpec{
... // 20 identical fields
UsageMetering: nil,
CloudAuditLogging: &{ProjectID: "syllogi-partner-testing", ClusterLocation: "us-central1", ServiceAccountKey: &{KubernetesSecret: &{Name: "user-cluster-creds", KeyName: "cloud-audit-logging-service-account-key"}}},
- AutoRepair: &v1alpha1.AutoRepairConfig{Enabled: true},
+ AutoRepair: &v1alpha1.AutoRepairConfig{},
CARotation: &{Generated: &{CAVersion: 1}},
KSASigningKeyRotation: &{Generated: &{KSASigningKeyVersion: 1}},
... // 8 identical fields
}
이 오류를 우회해야 하는 경우 해결 방법은 다음과 같습니다.
- 시도한 변경사항을 되돌린 후 업그레이드를 다시 실행합니다. 예를 들어 이전 시나리오에서는
AutoRepair구성에 수행한 변경사항을 되돌리고gkectl upgrade를 다시 실행합니다. - 또는
gkectl get-config를 실행하여 현재 클러스터 상태와 일치하는 구성 파일을 생성하고 구성 파일에서 클러스터와 노드 풀에 대한gkeOnPremVersion필드를 업데이트한 후gkectl upgrade를 다시 실행할 수 있습니다.