이 페이지에서는 VMware용 Google Distributed Cloud(소프트웨어만 해당)에서 클러스터 생성 및 업그레이드 문제를 조사하는 방법을 설명합니다.
추가 지원이 필요하면 Cloud Customer Care에 연락합니다.설치 문제
다음 섹션은 Google Distributed Cloud 설치와 관련된 문제를 해결하는 데 유용할 수 있습니다.
부트스트랩 클러스터를 사용하여 문제 디버깅
설치 중 Google Distributed Cloud는 임시 부트스트랩 클러스터를 만듭니다. 설치가 완료되면 Google Distributed Cloud가 부트스트랩 클러스터를 삭제하고 관리자 클러스터와 사용자 클러스터를 남겨둡니다. 일반적으로 부트스트랩 클러스터와 상호작용할 이유가 없습니다. 그러나 설치 중에 문제가 발생하면 부트스트랩 클러스터 로그를 사용하여 문제를 디버그할 수 있습니다.
--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_NAMEPOD_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
부트스트랩 클러스터의 스냅샷 검사
관리자 클러스터 만들기 또는 업그레이드를 시도할 때 작업이 실패하면 Google Distributed Cloud가 부트스트랩 클러스터의 외부 스냅샷을 만듭니다.
이러한 부트스트랩 클러스터의 스냅샷은 관리자 클러스터에서 gkectl diagnose snapshot 명령어를 실행하여 작성된 스냅샷과 비슷하지만 프로세스에서 자동으로 트리거됩니다. 부트스트랩 클러스터 스냅샷에는 관리자 클러스터 만들기 및 업그레이드 프로세스에 관한 중요한 디버깅 정보가 포함되어 있습니다. 필요한 경우 Cloud Customer Care에 이 스냅샷을 제공할 수 있습니다.
외부 스냅샷에는 클러스터 생성 또는 업그레이드 문제를 디버깅하기 위해 볼 수 있는 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
관리자 컨트롤 플레인이 시작된 후 VM이 시작되지 않음
관리자 컨트롤 플레인이 시작된 후 VM이 시작되지 않으면 관리자 클러스터의 Cluster API 컨트롤러 포드에서 로그를 검사하여 문제를 조사할 수 있습니다.
Cluster API 컨트롤러 Pod 이름을 찾습니다.
kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG --namespace kube-system \ get pods | grep clusterapi-controllersvsphere-controller-manager에서 로그를 봅니다. 먼저 포드를 지정하되 컨테이너를 지정하지 않습니다.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
할당된 IP 주소의 수가 충분하지만 클러스터에 머신이 등록되지 않음
IP 주소가 충돌하면 이 문제가 발생할 수 있습니다. 예를 들어 머신에 지정한 IP 주소가 부하 분산기에서 사용되고 있습니다.
이 문제를 해결하려면 머신 주소가 클러스터 구성 파일이나 Seesaw IP 차단 파일에 지정한 주소와 충돌하지 않도록 클러스터 IP 차단 파일을 업데이트합니다.
클러스터 업그레이드 문제
다음 섹션에서는 클러스터 업그레이드 중에 발생할 수 있는 문제 해결 방법에 대한 팁을 제공합니다.
업그레이드 후 노드 풀 롤백
사용자 클러스터를 업그레이드한 후 클러스터 노드에서 문제가 발견되면 선택한 노드 풀을 이전 버전으로 롤백할 수 있습니다.
선택한 노드 풀 롤백은 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
새 패치 버전으로 업그레이드
모든 노드 풀과 컨트롤 플레인을 새 패치 버전으로 업그레이드할 수 있습니다. 이전 버전으로 롤백한 후 수정사항이 포함된 버전으로 업그레이드하려는 경우에 유용합니다.
새 버전으로 업그레이드하려면 다음 단계를 완료하세요.
사용자 클러스터 구성 파일을 다음과 같이 변경합니다.
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: ""
Google Distributed Cloud 업그레이드에 설명된 대로
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 ```
클러스터 업그레이드가 실패하면 상태 점검이 자동으로 실행됩니다.
관리자 또는 사용자 클러스터를 업그레이드하려고 할 때 이 작업이 실패하면 Google Distributed Cloud가 자동으로 클러스터에서 gkectl diagnose cluster 명령어를 실행합니다.
자동 진단을 건너뛰려면 --skip-diagnose-cluster 플래그를 gkectl upgrade에 전달합니다.
업그레이드 프로세스 중단
내부적으로 Google Distributed Cloud는 업그레이드 중에 Kubernetes drain 명령어를 사용합니다. 이 drain 절차는 minAvailable: 1을 사용해서 PodDisruptionBudget(PDB)가 생성된 복제본이 한 개만 있는 배포에 의해 차단될 수 있습니다.
Google Distributed Cloud 버전 1.13에서는 Kubernetes 포드 이벤트를 통해 장애를 확인할 수 있습니다.
머신 이름을 찾습니다.
kubectl --kubeconfig USER_CLUSTER_KUBECONFIG get machines --all-namespaceskubectl 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를 다시 추가하면 됩니다.
업그레이드가 차단 해제되도록 지원되지 않는 변경사항 삭제
클러스터를 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를 다시 실행할 수 있습니다.
내부 kubeconfig 파일로 F5 BIG-IP 문제 디버그
설치 후 Google Distributed Cloud는 관리자 워크스테이션의 홈 디렉터리에 internal-cluster-kubeconfig-debug라는 kubeconfig 파일을 생성합니다. 이 kubeconfig 파일은 관리자 클러스터의 kubeconfig 파일과 동일하지만 Kubernetes API 서버가 실행되는 관리자 클러스터의 컨트롤 플레인 노드를 직접 가리킨다는 점이 다릅니다. internal-cluster-kubeconfig-debug 파일을 사용하여 F5 BIG-IP 문제를 디버깅할 수 있습니다.
vSphere 문제 디버그
govc를 사용하여 vSphere 문제를 조사할 수 있습니다. 예를 들어 vCenter 사용자 계정에 대한 권한과 액세스 권한을 확인하고 vSphere 로그를 수집할 수 있습니다.
누락된 사용자 클러스터 kubeconfig 파일 다시 만들기
다음 상황에서 사용자 클러스터 kubeconfig 파일을 다시 만들 수 있습니다.
- 사용자 클러스터를 만들려고 하고 만들기 작업이 실패하고 사용자 클러스터
kubeconfig파일을 보유하려는 경우 - 사용자 클러스터
kubeconfig파일이 누락된 경우(예: 삭제 후)
사용자 클러스터의 새 kubeconfig 파일을 생성하려면 다음 단계를 실행합니다.
환경 변수 정의:
먼저 다음 환경 변수를 적절한 값으로 설정합니다.
USER_CONTROLPLANEVIP=USER_CONTROLPLANEVIP USER_CLUSTER_NAME=USER_CLUSTER_NAME ADMIN_CLUSTER_KUBECONFIG=PATH_TO_ADMIN_KUBECONFIG KUBECONFIG_SECRET_NAME=$(kubectl --kubeconfig $ADMIN_CLUSTER_KUBECONFIG get secrets -n $USER_CLUSTER_NAME | grep ^admin | cut -d' ' -f1 | head -n 1)다음을 바꿉니다.
ADMIN_CLUSTER_KUBECONFIG: 관리자 클러스터의kubeconfig파일 경로입니다.USER_CONTROLPLANEVIP: 사용자 클러스터의controlPlaneVIP입니다. 이는 사용자 클러스터 매니페스트 파일에서 가져올 수 있습니다.
Kubeconfig 파일 생성:
다음 명령어를 실행하여 새 kubeconfig 파일을 만듭니다.
kubectl --kubeconfig $ADMIN_CLUSTER_KUBECONFIG get secrets $KUBECONFIG_SECRET_NAME \ -n $USER_CLUSTER_NAME -o jsonpath='{.data.admin\.conf}' | base64 -d | \ sed -r "s/ kube-apiserver.*local\./${USER_CONTROLPLANEVIP}/" \ > USER_CLUSTER_KUBECONFIG다음과 같이 바꿉니다.
USER_CLUSTER_KUBECONFIG: 사용자 클러스터의 새kubeconfig파일 이름입니다.
다음 단계
- 추가 지원이 필요하면 Cloud Customer Care에 문의하세요.