업그레이드 문제 해결

이 페이지에서는 Google Kubernetes Engine(GKE) 클러스터 업그레이드 문제를 해결하는 방법을 보여줍니다.

추가 지원이 필요하면 Cloud Customer Care에 연락합니다.

문제: 컨트롤 플레인 업그레이드 후 kube-apiserver가 비정상 상태임

클러스터 GKE 버전의 수동 컨트롤 플레인 업그레이드를 시작하면 다음 문제가 발생합니다. 일부 사용자 배포 허용 웹훅은 시스템 구성요소가 올바르게 작동하는 데 필요한 허용 RBAC 역할을 만들지 못하도록 차단할 수 있습니다. 컨트롤 플레인 업그레이드 중에 Google Cloud는 Kubernetes API 서버(kube-apiserver) 구성요소를 다시 만듭니다. 웹훅이 API 서버 구성요소에 대한 RBAC 역할을 차단하면 API 서버가 시작되지 않고 클러스터 업그레이드가 완료되지 않습니다.

gcloud CLI의 오류 메시지는 다음과 비슷합니다.

FAILED: All cluster resources were brought up, but: component "KubeApiserverReady" from endpoint "readyz of kube apiserver is not successful" is unhealthy.

실패한 웹훅을 식별하려면 다음 정보를 사용하여 RBAC 호출에 대한 GKE 감사 로그를 확인합니다.

protoPayload.resourceName="RBAC_RULE"
protoPayload.authenticationInfo.principalEmail="system:apiserver"

RBAC_RULE은 RBAC 역할의 전체 이름입니다(예: rbac.authorization.k8s.io/v1/clusterroles/system:controller:horizontal-pod-autoscaler).

실패한 웹훅의 이름은 다음 형식으로 로그에 표시됩니다.

admission webhook WEBHOOK_NAME denied the request

이 문제를 해결하려면 다음을 시도해 보세요.

  • system: 프리픽스가 있는 ClusterRoles를 만들고 업데이트할 수 있도록 제약조건을 조정합니다.
  • 시스템 RBAC 역할 생성 및 업데이트에 대한 요청을 가로채지 않도록 웹훅을 조정합니다.
  • 웹훅을 사용 중지합니다.

이런 문제가 생기는 이유는 무엇인가요?

Kubernetes는 최신 부 버전의 기본 정책으로 기본 시스템 RBAC 역할을 자동 조정{track-name="k8sLink" track-type="troubleshooting"}합니다. 시스템 역할에 대한 기본 정책은 새 Kubernetes 버전에서 변경되는 경우가 있습니다.

이 조정을 수행하기 위해 GKE는 클러스터에서 ClusterRoles 및 ClusterRoleBindings를 만들거나 업데이트합니다. 기본 RBAC 정책이 사용하는 권한 범위로 인해 생성 또는 업데이트 요청을 가로채고 거부하는 웹훅이 있는 경우 API 서버가 새 마이너 버전에서 작동하지 않습니다.

문제: Standard 클러스터 업그레이드 후 워크로드 제거됨

다음 조건에 모두 해당하는 경우 클러스터 업그레이드 후 워크로드가 제거될 위험이 있음

  • 클러스터 컨트롤 플레인이 새 GKE 버전을 실행할 때 시스템 워크로드에 더 많은 공간이 필요함
  • 기존 노드에 새 시스템 워크로드와 기존 워크로드를 실행하기에 충분한 리소스가 없음
  • 클러스터에 클러스터 자동 확장 처리가 사용 중지됨

이 문제를 해결하려면 다음을 단계를 시도해 보세요.

문제: 노드 버전이 컨트롤 플레인 버전과 호환되지 않음

클러스터의 컨트롤 플레인이 실행 중인 Kubernetes 버전을 확인한 다음 클러스터의 노드 풀이 실행 중인 Kubernetes 버전을 확인하세요. 클러스터의 노드 풀 중 컨트롤 플레인보다 오래된 부 버전이 2개 초과이면 클러스터에 문제가 발생할 수 있습니다.

GKE팀은 사용자를 대신하여 클러스터 컨트롤 플레인의 업그레이드를 주기적으로 수행합니다. 컨트롤 플레인은 안정적인 새 Kubernetes 버전으로 업그레이드됩니다. 기본적으로 클러스터 노드는 자동 업그레이드가 사용 설정되어 있으며, 사용 중지하지 않는 것이 좋습니다.

클러스터 노드에 자동 업그레이드가 사용 중지되어 있고 노드 풀 버전을 컨트롤 플레인과 호환되는 버전으로 수동으로 업그레이드하지 않으면 자동으로 업그레이드되는 컨트롤 플레인과 노드는 결국 호환되지 않게 됩니다. 클러스터의 컨트롤 플레인과 노드 간의 비호환성으로 인해 예기치 않은 문제가 발생할 수 있습니다.

Kubernetes 버전 및 버전 편향 지원 정책은 컨트롤 플레인보다 최대 2개 부 버전이 낮은 노드와 컨트롤 플레인이 호환된다고 명시되어 있습니다. 예를 들어 Kubernetes 1.19 컨트롤 플레인은 Kubernetes 1.19, 1.18, 1.17 노드와 호환됩니다. 이 문제를 해결하려면 노드 풀 버전을 컨트롤 플레인과 호환되는 버전으로 수동으로 업그레이드하세요.

영향을 받는 노드에서 실행되는 워크로드가 워크로드 프로세스로 인해 중단되는 것이 우려되는 경우 다음 단계를 수행하여 워크로드를 새 노드 풀로 마이그레이션합니다.

  1. 호환되는 버전으로 새 노드 풀을 만듭니다.
  2. 기존 노드 풀의 노드를 Cordon합니다.
  3. (선택사항) 기존 노드 풀에서 실행되는 워크로드를 업데이트하여 cloud.google.com/gke-nodepool:NEW_NODE_POOL_NAME 라벨의 nodeSelector를 추가합니다. 여기서 NEW_NODE_POOL_NAME은 새 노드 풀의 이름입니다. 이렇게 하면 GKE가 새 노드 풀의 노드에 이러한 워크로드를 배치합니다.
  4. 기존 노드 풀을 드레이닝합니다.
  5. 새 노드 풀에서 워크로드가 성공적으로 실행되는지 확인합니다. 성공적으로 실행될 경우 이전 노드 풀을 삭제할 수 있습니다. 워크로드 중단이 발견되면 기존 노드 풀에서 노드 차단을 취소하고 새 노드를 드레이닝하여 기존 노드에서 워크로드를 다시 예약합니다. 문제 해결을 수행하고 다시 시도합니다.

문제: 노드 할당 가능을 구성한 후 포드가 대기 중 상태에서 멈춤

노드 할당 가능을 구성하고 노드 버전 업그레이드를 수행한 후 실행 중인 포드가 대기 중으로 변경될 수 있습니다.

업그레이드 후 Pod가 대기 중이면 다음을 수행하는 것이 좋습니다.

  • 포드의 CPU 및 메모리 요청이 최대 사용량을 초과하지 않는지 확인합니다. GKE에서 오버헤드에 사용할 CPU와 메모리를 예약하는 반면 Pod는 이러한 리소스를 요청할 수 없습니다. Pod가 사용량 보다 많은 CPU 또는 메모리를 요청하면 다른 Pod가 이러한 리소스를 요청하지 못하게 되어 클러스터 사용률이 떨어질 수 있습니다. 자세한 내용은 리소스 요청이 있는 pod 예약 방법을 참조하세요.

  • 클러스터 크기를 조정해 봅니다. 자세한 내용은 클러스터 크기 조절을 참조하세요.

  • 클러스터를 다운그레이드하여 이 변경사항을 되돌립니다. 자세한 내용은 클러스터 또는 노드 풀 수동 업그레이드를 참조하세요.

다음 단계

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