클러스터 설치 또는 업그레이드 문제 해결

이 페이지에서는 베어메탈용 GKE 클러스터를 설치하거나 업그레이드할 때 문제가 발생하는 경우 문제 해결 정보를 제공합니다.

클러스터 문제 부트스트랩

베어메탈용 GKE에서 자체 관리형(관리자, 하이브리드 또는 독립형) 클러스터를 만드는 경우 클러스터를 만드는데 필요한 Kubernetes 컨트롤러를 일시적으로 호스트하도록 Docker의 Kubernetes(kind) 클러스터를 배포합니다. 이러한 임시 클러스터를 부트스트랩 클러스터라고 합니다. 사용자 클러스터는 부트스트랩 클러스터를 사용하지 않고 관리 관리자 또는 하이브리드 클러스터를 통해 생성되고 업그레이드됩니다.

설치하려고 할 때 kind 클러스터가 이미 배포에 있으면 베어메탈용 GKE에서 기존 kind 클러스터를 삭제합니다. 설치 또는 업그레이드가 성공한 후에만 삭제가 수행됩니다. 성공한 후에도 기존 kind 클러스터를 보존하려면 bmctl의 --keep-bootstrap-cluster 플래그를 사용합니다.

베어메탈용 GKE는 WORKSPACE_DIR/.kindkubeconfig 아래에 부트스트랩 클러스터 구성 파일을 만듭니다. 클러스터 만들기 및 업그레이드 중에만 부트스트랩 클러스터에 연결할 수 있습니다.

이미지를 가져오려면 부트스트랩 클러스터가 Docker 저장소에 액세스해야 합니다. 비공개 레지스트리를 사용하지 않는 한 레지스트리가 기본적으로 Container Registry로 지정됩니다. 클러스터를 만드는 동안 bmctl이 다음 파일을 만듭니다.

  • bmctl-workspace/config.json: 레지스트리 액세스를 위한 Google Cloud 서비스 계정을 포함합니다. 클러스터 구성 파일의 gcrKeyPath 필드에서 사용자 인증 정보를 가져옵니다.

  • bmctl-workspace/config.toml: kind 클러스터의 containerd 구성을 포함합니다.

부트스트랩 클러스터 디버그

부트스트랩 클러스터를 디버깅하려면 다음 단계를 수행합니다.

  • 클러스터 만들기 및 업그레이드 중에 부트스트랩 클러스터에 연결합니다.
  • 부트스트랩 클러스터의 로그를 가져옵니다.

다음 폴더에서 bmctl을 실행하기 위해 사용하는 머신에서 로그를 찾을 수 있습니다.

  • bmctl-workspace/CLUSTER_NAME/log/create-cluster-TIMESTAMP/bootstrap-cluster/
  • bmctl-workspace/CLUSTER_NAME/log/upgrade-cluster-TIMESTAMP/bootstrap-cluster/

CLUSTER_NAME 및 TIMESTAMP를 클러스터 이름과 해당 시스템 시간으로 바꿉니다.

부트스트랩 클러스터에서 직접 로그를 가져오려면 클러스터 만들기 및 업그레이드 동안 다음 명령어를 실행할 수 있습니다.

docker exec -it bmctl-control-plane bash

이 명령어는 부트스트랩 클러스터에서 실행되는 bmctl 제어영역 컨테이너 내에서 터미널을 엽니다.

kubelet 및 containerd 로그를 검사하려면 다음 명령어를 사용하고 출력에서 오류 또는 경고를 찾습니다.

journalctl -u kubelet
journalctl -u containerd

클러스터 업그레이드 문제

베어메탈용 GDCV를 업그레이드하면 진행 상황을 모니터링하고 클러스터와 노드의 상태를 확인할 수 있습니다.

다음 지침은 업그레이드가 정상적으로 계속 진행되는지 또는 문제가 있는지 확인하는 데 도움이 될 수 있습니다.

업그레이드 진행 상태 모니터링

업그레이드 프로세스 중에 클러스터의 상태를 보려면 kubectl describe cluster 명령어를 사용합니다.

kubectl describe cluster CLUSTER_NAME \
    --namespace CLUSTER_NAMESPACE \
    --kubeconfig ADMIN_KUBECONFIG

다음 값을 바꿉니다.

  • CLUSTER_NAME: 클러스터의 이름입니다.
  • CLUSTER_NAMESPACE: 클러스터의 네임스페이스입니다.
  • ADMIN_KUBECONFIG: 관리자 kubeconfig 파일입니다.
    • 기본적으로 관리자, 하이브리드, 독립형 클러스터는 인플레이스 업그레이드를 사용합니다. bmctl upgrade 명령어로 --use-bootstrap=true 플래그를 사용하면 업그레이드 작업에서 부트스트랩 클러스터를 사용합니다. 부트스트랩 클러스터가 사용될 때 업그레이드 진행 상황을 모니터링하려면 부트스트랩 클러스터 kubeconfig 파일(.kindkubeconfig)의 경로를 지정합니다. 이 파일은 작업공간 디렉터리에 있습니다.

출력에서 Status 섹션을 업그레이드하여 클러스터 업그레이드 상태의 집계를 확인합니다. 클러스터에서 오류를 보고하는 경우 다음 섹션을 수행하여 문제가 있는 문제를 해결합니다.

노드가 준비되었는지 확인

업그레이드 프로세스를 수행하는 동안 kubectl get nodes 명령어를 사용하여 클러스터의 노드 상태를 확인합니다.

kubectl get nodes --kubeconfig KUBECONFIG

노드가 업그레이드 프로세스를 성공적으로 완료했는지 확인하려면 명령어 응답의 VERSION 및 AGE 열을 확인합니다. VERSION는 클러스터의 Kubernetes 버전입니다. 지정된 베어메탈용 GDCV 버전의 Kubernetes 버전을 확인하려면 버전 지원 정책의 표를 참조하세요.

노드에 NOT READY가 표시되면 노드를 연결하고 kubelet 상태를 확인합니다.

systemctl status kubelet

kubelet 로그를 검토할 수도 있습니다.

journalctl -u kubelet

kubelet 상태 출력과 노드에 문제가 발생한 이유를 나타내는 메시지에 대한 로그를 검토합니다.

현재 업그레이드 중인 노드 확인

클러스터의 어느 노드를 업그레이드 중인지 확인하려면 kubectl get baremetalmachines 명령어를 사용합니다.

kubectl get baremetalmachines --namespace CLUSTER_NAMESPACE \
    --kubeconfig ADMIN_KUBECONFIG

다음 값을 바꿉니다.

  • CLUSTER_NAMESPACE: 클러스터의 네임스페이스입니다.
  • ADMIN_KUBECONFIG: 관리자 kubeconfig 파일입니다.
    • 관리자, 하이브리드 또는 독립형 업그레이드에 부트스트랩 클러스터를 사용하는 경우 부트스트랩 클러스터 kubeconfig 파일(bmctl-workspace/.kindkubeconfig)을 지정합니다.

다음 출력 예시는 업그레이드 중인 노드가 DESIRED ABM VERSION과 다른 ABM VERSION임을 보여줍니다.

NAME         CLUSTER    READY   INSTANCEID               MACHINE      ABM VERSION   DESIRED ABM VERSION
10.200.0.2   cluster1   true    baremetal://10.200.0.2   10.200.0.2   1.13.0        1.14.0
10.200.0.3   cluster1   true    baremetal://10.200.0.3   10.200.0.3   1.13.0        1.13.0

드레이닝되는 노드 확인

업그레이드 프로세스 중에는 노드에서 포드가 드레이닝되고 노드가 성공적으로 업그레이드될 때까지 예약이 사용 중지됩니다. 포드가 드레이닝되고 있는 노드를 확인하려면 kubectl get nodes 명령어를 사용합니다.

kubectl get nodes --kubeconfig USER_CLUSTER_KUBECONFIG | grep "SchedulingDisabled"

USER_CLUSTER_KUBECONFIG를 사용자 클러스터 kubeconfig 파일의 경로로 바꿉니다.

STATUS 열은 SchedulingDisabled를 보고하는 노드만 표시하도록 grep을 사용하여 필터링됩니다. 이 상태는 노드가 드레이닝되고 있음을 나타냅니다.

관리자 클러스터에서 노드 상태를 확인할 수도 있습니다.

kubectl get baremetalmachines -n CLUSTER_NAMESPACE \
  --kubeconfig ADMIN_KUBECONFIG

다음 값을 바꿉니다.

  • CLUSTER_NAMESPACE: 클러스터의 네임스페이스입니다.
  • ADMIN_KUBECONFIG: 관리자 kubeconfig 파일입니다.
    • 관리자, 하이브리드 또는 독립형 업그레이드에 부트스트랩 클러스터를 사용하는 경우 부트스트랩 클러스터 kubeconfig 파일(bmctl-workspace/.kindkubeconfig)을 지정합니다.

드레이닝되는 노드에는 MAINTENANCE 열 아래의 상태가 표시됩니다.

노드가 오랫동안 드레이닝 상태에 있는 이유 확인

이전 섹션의 방법 중 하나를 사용하여 kubectl get nodes 명령어를 사용하여 드레이닝되는 노드를 식별합니다. kubectl get pods 명령어를 사용하고 이 노드 이름을 필터링하여 추가 세부정보를 확인합니다.

kubectl get pods --all-namespaces -o wide --field-selector spec.nodeName=NODE_NAME

NODE_NAME을 드레이닝하는 노드의 이름으로 바꿉니다. 출력에서 중단되었거나 드레이닝이 느린 포드 목록이 반환됩니다. 노드의 드레이닝 프로세스가 20분 넘게 걸리면 포드가 중단된 상태에서도 업그레이드가 진행됩니다.

포드가 비정상적인 이유 확인

포드에 upgrade-first-node 또는 upgrade-node 제어 영역 IP 주소가 포함된 경우 업그레이드가 실패할 수 있습니다. 이 동작은 일반적으로 정적 포드가 정상이 아니기 때문에 발생합니다.

  1. crictl ps -a 명령어로 정적 포드를 확인하고 비정상 종료되는 Kubernetes 또는 etcd 포드를 찾습니다. 실패한 포드가 있으면 포드에 대한 로그를 검토하여 비정상 종료 이유를 확인합니다.

    비정상 종료 루프 동작의 가능한 원인은 다음과 같습니다.

    • 정적 포드에 마운트된 파일의 권한이나 소유자가 올바르지 않습니다.
    • 가상 IP 주소에 대한 연결이 작동하지 않습니다.
    • etcd 관련 문제입니다.

  2. crictl ps 명령어가 작동하지 않거나 아무것도 반환하지 않으면 kubelet 및 containerd 상태를 확인합니다. systemctl status SERVICE 및 journalctl -u SERVICE 명령어를 사용하여 로그를 확인합니다.