노드 등록 문제 해결

표준

이 문서에서는 Google Kubernetes Engine(GKE) Standard 클러스터에 노드를 추가할 때 발생하는 문제를 해결하는 방법을 설명합니다. 이러한 문제가 발생하는 몇 가지 시나리오에는 클러스터 생성 및 노드 풀 생성과 수직 확장 이벤트 등이 포함됩니다.

GKE Autopilot 클러스터 문제를 해결하려면 Autopilot 클러스터 문제 해결을 참조하세요.

노드 등록 정보

노드는 GKE에서 사용자를 대신하여 만든 Compute Engine VM 인스턴스입니다. 새 노드가 GKE 클러스터에 추가되면 클러스터의 제어 영역에 등록해야 합니다. 노드 등록 또는 노드 부트스트랩이라는 프로세스는 노드가 생성될 때 수행됩니다.

노드 등록 발생 시

다음 시나리오를 포함하여 노드가 생성될 때마다 노드 등록이 발생합니다.

클러스터를 만듭니다.
노드 풀을 만듭니다.
GKE는 노드 자동 프로비저닝으로 노드 풀을 만듭니다.
클러스터 자동 확장 처리는 클러스터를 확장합니다.
클러스터 크기를 조절합니다.
노드 자동 복구가 새 노드를 만듭니다.

노드 등록 프로세스는 다음 단계를 따릅니다.

노드 풀에 설정된 노드 수는 관리형 인스턴스 그룹(MIG)에 복제됩니다.
MIG가 필요한 수의 VM 인스턴스를 만듭니다.
생성된 각 VM 인스턴스에 다음이 수행됩니다.
1. VM 인스턴스가 부팅됩니다.
2. VM 인스턴스는 Kubernetes 노드로 실행하는 데 필요한 패키지를 구성하고 설치합니다.
3. 이제 VM 인스턴스에서 실행되는 kubelet이 제어 영역의 API 서버와 통신하여 노드로 등록합니다.

노드 등록 오류 메시지

GKE가 클러스터에 노드를 추가하려고 시도할 때 노드 등록이 실패하면 Google Cloud 콘솔에 다음 오류가 표시됩니다.

  All cluster resources were brought up, but: only 0 nodes out of * have
  registered; this is likely due to the Nodes failing to start correctly; try
  re-creating the cluster or contact support if that doesn't work.

이 오류 메시지는 노드가 클러스터에 성공적으로 등록되지 않았음을 나타냅니다. 다음 섹션에서는 이 오류의 가능한 원인을 설명합니다.

성공적인 노드 등록을 위한 기본 요건

GKE 클러스터에 대한 성공적인 노드 등록은 다음과 같은 요소에 따라 달라집니다.

네트워크 연결
리소스 가용성
서비스 계정 권한

인스턴스 생성을 위한 기본 요건

GKE가 클러스터에 노드를 만들 때 첫 번째 단계는 새 Compute Engine VM 인스턴스를 만드는 것입니다.

다음 이유 중 하나로 인해 인스턴스 생성이 실패할 수 있습니다.

인스턴스 생성 실패는 GKE에서 인스턴스를 GKE 노드로 등록하기 위해 인스턴스를 만들려고 시도한 시간 동안 인스턴스가 생성되지 않았기 때문에 인스턴스 생성에 대한 로그가 누락되었음을 의미합니다. 누락된 로그를 확인하려면 노드 등록에 실패한 인스턴스 찾기 안내를 참조하세요.

서비스 계정 권한

GKE 노드에는 연관된 IAM 서비스 계정이 있습니다. 기본적으로 이 서비스 계정은 Compute Engine 기본 서비스 계정입니다. 필요한 최소 권한이 포함된 커스텀 IAM 서비스 계정을 사용하여 클러스터를 강화하는 것이 좋습니다.

이 서비스 계정에는 VM 인스턴스를 GKE 노드로 초기화하기 위해 올바른 권한이 있어야 합니다. 서비스 계정을 삭제하거나 사용 중지하거나 올바른 권한을 부여하지 않으면 노드 등록이 실패할 수 있습니다.

Google API 및 서비스의 네트워크 연결을 위한 기본 요건

VM 인스턴스는 패키지를 다운로드하여 GKE 노드로 실행할 준비를 합니다. 연결 시간 초과는 클러스터가 Google API 및 서비스(예: storage.googleapis.com)에 연결하는 데 필요한 네트워킹 요구사항을 충족하지 못했음을 의미할 수 있습니다. 인스턴스가 이러한 서비스에 연결할 수 없으면 Kubernetes 배포를 다운로드하여 노드 등록 프로세스를 완료할 수 없습니다.

네트워크 연결에 따라 이 연결을 허용한다는 것은 비공개 Google 액세스를 구성하거나 연결을 허용하는 클러스터의 Virtual Private Cloud(VPC) 네트워크에 방화벽 규칙 및 경로가 있음을 의미할 수 있습니다.

제어 영역과의 네트워크 연결 기본 요건

제어 영역과 노드 간의 연결은 노드 등록과 정규 기능에 매우 중요합니다. 이 통신은 기본적으로 허용됩니다. VPC 방화벽 규칙을 배치할 때 노드와 제어 영역 간 통신이 여전히 허용되는지 확인합니다.

자세한 내용은 제어 영역 연결 허용을 참조하세요.

노드 등록 검사기를 사용하여 노드 등록 문제 해결

GKE 버전 1.24.0-gke.100 이상에서 생성된 노드 풀의 경우 노드 등록 검사기라는 유틸리티가 새로 생성된 인스턴스에서 실행되고 인스턴스가 노드 등록 단계를 성공적으로 완료했는지 확인합니다.

노드 등록에 실패하면 유틸리티는 인스턴스가 실패한 프로세스의 위치를 기반으로 충족되지 않은 기본 요건을 확인할 수 있는 요약 보고서를 생성합니다.

다음 섹션의 안내에 따라 노드 등록에 실패한 인스턴스를 찾고 노드 등록 검사기 요약을 사용하여 실패한 이유를 알아봅니다.

노드 풀에서 노드 등록 검사기를 사용할 수 없는 경우 노드 등록 검사기가 없는 노드 등록 문제 해결을 참조하세요.

노드 등록에 실패한 인스턴스 찾기

하나 이상의 인스턴스가 GKE 클러스터의 제어 영역에 노드로 등록되지 못하면 Google Cloud 콘솔의 클러스터 세부정보 페이지에 표시된 오류 메시지에서 실패한 인스턴스의 수를 확인할 수 있습니다. 여러 인스턴스가 한 번에 등록되지 못하면 동일한 근본 이유가 있을 수 있습니다. 따라서 실패한 인스턴스 중 하나를 사용하여 모든 인스턴스가 실패한 이유를 조사할 수 있습니다.

하지만 인스턴스가 GKE 노드로 등록되지 않았으므로 다음 안내에 따라 등록에 실패한 기본 Compute Engine VM의 이름을 찾아야 합니다.

Google Cloud 콘솔에서 로그 탐색기 페이지로 이동합니다.

로그 탐색기로 이동

다음 로그 필터를 사용하여 VM 인스턴스 생성 로그를 찾습니다.

resource.type="gce_instance"
logName="projects/PROJECT_ID/logs/cloudaudit.googleapis.com%2Factivity"
protoPayload.requestMetadata.callerSuppliedUserAgent="GCE Managed Instance Group for GKE"
protoPayload.response.status="RUNNING"

PROJECT_ID를 클러스터의 프로젝트 ID로 바꿉니다.

로그 필터 아래의 히스토그램을 사용하여 노드 생성이 수행되었어야 하는 시간 범위를 좁힙니다.
쿼리 결과 아래에 표시되는 로그 중 하나를 클릭한 다음 중첩된 필드 확장을 클릭하여 세부정보를 표시합니다.
protoPayload.resourceName 필드를 찾습니다. 나열된 경로의 마지막 부분은 인스턴스 이름입니다. 인스턴스 이름은 클러스터 이름과 노드 풀 이름으로 시작하는 형식을 따릅니다. 예를 들면 다음과 같습니다.

gke-cluster-1-default-pool-b0ac62d3-9g1v는 gke-cluster-1의 default-pool 노드 풀 인스턴스입니다.
Google Cloud 콘솔에서 Compute Engine VM 인스턴스 페이지로 이동합니다.

VM 인스턴스로 이동

필터를 사용하여 VM 인스턴스의 이름을 찾습니다. 클릭하여 자세히 알아보세요.

노드 등록 검사기로 인스턴스 문제 해결

등록하지 못한 인스턴스의 이름을 찾은 후 노드 등록 검사기를 사용하여 실패한 인스턴스를 조사할 수 있습니다.

VM 인스턴스 세부정보 탭의 로그 섹션에서 직렬 포트 1(콘솔)을 클릭합니다.

GKE 버전 1.24.0-gke.100 이상에서 생성된 노드 풀의 경우 새로 생성된 인스턴스의 출력에 노드 등록 검사기가 시작되었음을 나타내는 다음과 같은 결과가 포함됩니다.

** Starting Node Registration Checker **
** Loading variables from kube-env **
** Sleeping for 7m to allow registration to complete  **

노드 등록이 성공하면 출력에 다음 메시지가 포함됩니다.

** Node ready and registered. **
** Completed running Node Registration Checker **

이러한 메시지가 표시되지 않으면 노드 등록이 실패한 것이며 노드 등록 검사기에서 등록이 실패한 이유를 요약한 보고서를 생성한 것입니다. 요약을 보려면 다음 추가 메시지를 확인하세요.

** Here is a summary of the checks performed: **

이 메시지 아래에서 다음과 비슷한 테이블을 찾습니다.

------------------------------
Service    DNS      Reachable
------------------------------
LOGGING    true     true
GCR        true     true
GCS        true     true
Master     N/A      false
------------------------------

LOGGING, GCR 또는 GCS가 연결할 수 없는 것으로 표시되면 노드 등록을 위한 서비스 계정 권한 및 노드 등록을 위한 Google API 및 서비스의 네트워크 연결을 확인하세요.

Master가 연결할 수 없는 것으로 표시되면 노드 등록을 위한 제어 영역이 있는 네트워크 연결의 기본 요건을 확인합니다.

성공적인 노드 등록을 방해하는 모든 문제를 해결한 후 근본 원인 해결 후 노드 등록 완료를 참조하세요.

앞의 단계에서 노드 등록이 실패한 이유를 알려주지 않으면 추가 조사를 위한 정보 수집을 참조하세요.

노드 등록 검사기가 없는 노드 등록 문제 해결

1.24.0-gke.100 이전 GKE 버전에서 생성된 노드 풀에 노드 등록이 실패하면 노드 등록 문제만 수동으로 해결할 수 있습니다. 노드 풀이 GKE 버전 1.24.0-gke.100 이상에서 생성된 경우 노드 등록 검사기를 사용하여 노드 등록 문제 해결의 안내를 따릅니다.

성공적인 노드 등록을 방해하는 모든 문제를 해결한 후 다음 안내에 따라 근본 원인을 해결한 후 노드 등록을 완료하세요.

이 페이지의 조사 단계에서 노드 등록이 실패한 이유를 알려주지 않으면 추가 조사를 위한 정보 수집을 참조하세요.

노드 등록을 위한 서비스 계정 권한 확인

노드에서 사용하는 서비스 계정에는 노드 등록을 위한 필수 권한이 있어야 합니다. 다음 안내에 따라 이러한 기본 요건을 충족하는지 확인하세요.

노드 등록에 실패한 인스턴스를 찾습니다.
VM 인스턴스 세부정보 탭의 API 및 ID 관리 섹션에 있는서비스 계정 필드에서 서비스 계정의 이름을 찾습니다. 노드에서 Compute Engine 기본 서비스 계정을 사용한 경우 이름은 PROJECT_NUMBER-compute@developer.gserviceaccount.com 형식을 따릅니다. 이 서비스 계정에는 최소 필수 권한이 있어야 합니다.
직렬 콘솔 출력에서 성공적인 등록 지표를 확인합니다. VM 인스턴스 세부정보 탭의 로그 섹션에서 직렬 포트 1(콘솔)을 클릭합니다.

인스턴스가 올바른 권한이 있는 서비스 계정을 사용한 경우 출력에 다음이 포함됩니다.
- Started Download and install k8s binaries and configurations
- Started Docker Application Container Engine.
- Started Configure kubernetes node.
- Reached target Kubernetes.
이러한 메시지는 이 출력의 여러 위치에 있습니다. 또한 Starting [0;1;39mConfigure kubernetes node와 같이 타임스탬프를 방해하는 다른 아티팩트가 있을 수 있습니다. 이러한 메시지가 모두 표시되면 서비스 계정 기본 요건이 충족된 것입니다.

이러한 메시지가 표시되지 않으면 VM 인스턴스에 할당된 서비스 계정이 삭제되었거나 사용 중지되었거나 올바른 권한이 없는 것일 수 있습니다.

노드 등록을 위해 Google API 및 서비스의 네트워크 연결 확인

SSH 액세스로 연결 확인

프로젝트에 VM 인스턴스에 대한 SSH 액세스 권한이 있는 경우 VM 인스턴스에 Google API 및 서비스의 네트워크 연결이 있는지 확인할 수도 있습니다.

노드 등록에 실패한 인스턴스를 찾습니다.
VM 인스턴스 세부정보 탭에서 SSH를 클릭합니다.
VM 인스턴스의 명령줄에 연결한 후 다음 명령어를 실행하여 Google API 및 서비스에 대한 연결을 확인합니다.
```
curl -m 5 -v https://storage.googleapis.com/generate_204
```
연결에 성공하면 출력은 다음과 비슷합니다.
```
*   Trying 142.250.148.128:443...
* Connected to storage.googleapis.com (142.250.148.128) port 443 (#0)

...

< HTTP/1.1 204 No Content
< Content-Length: 0
< Cross-Origin-Resource-Policy: cross-origin
< Date: Wed, 04 Jan 2023 00:58:41 GMT
<
* Connection #0 to host storage.googleapis.com left intact
```
연결에 실패하면 출력은 다음과 비슷합니다.
```
*   Trying 142.250.148.128:443...
* Connection timed out after 5000 milliseconds
* Closing connection 0
curl: (28) Connection timed out after 5000 milliseconds```
```
연결 시간이 초과되고 반환된 IP 주소가 199.36.153.0/24 IP 주소 범위 내에 있으면 클러스터가 Google API 및 서비스에 연결하기 위한 네트워킹 요구사항을 충족하는지 확인합니다. 연결 시간이 초과되고 반환된 IP 주소가 언급된 IP 주소 범위를 벗어나는 경우 클러스터의 VPC 네트워크에서 나가는 트래픽 또는 잘못 구성된 경로를 차단하는 방화벽 규칙을 확인합니다.

VM 인스턴스에 대한 SSH 연결을 열린 상태로 유지하고 다음 섹션으로 진행합니다.

연결 테스트를 사용하여 SSH 액세스 권한 없이 연결 확인

VM 인스턴스에 대한 SSH 액세스 권한이 없으면 연결 테스트를 사용하여 VM 인스턴스가 Google API 및 서비스에 연결되어 있는지 확인합니다.

노드 등록에 실패한 인스턴스를 찾습니다.
VM 인스턴스를 소스로, storage.googleapis.com TCP/443을 대상으로 사용하여 연결 테스트를 만들고 실행합니다.

테스트 결과를 사용하여 클러스터의 네트워킹 구성을 확인합니다.

노드 등록을 위해 제어 영역과의 네트워크 연결 확인

프로젝트에 VM 인스턴스에 대한 SSH 액세스 권한이 있는 경우 VM 인스턴스에 클러스터의 제어 영역에 대한 네트워킹 연결이 있는지 확인할 수 있습니다.

노드 등록에 실패한 인스턴스를 찾습니다.
VM 인스턴스 세부정보 탭에서 SSH를 클릭합니다.
VM 인스턴스의 명령줄에 연결한 후 클러스터의 제어 영역 엔드포인트를 환경 변수로 저장합니다.
```
source <(sudo grep KUBERNETES_MASTER_NAME /home/kubernetes/kube-env)
```

제어 영역 엔드포인트로 GET 요청을 보냅니다.

curl -k -m 5  https://${KUBERNETES_MASTER_NAME}/version

출력이 다음과 비슷하면 VM 인스턴스가 제어 영역과 연결을 설정할 수 있습니다.

{
"major": "1",
"minor": "24",
"gitVersion": "v1.24.7-gke.900",
"gitCommit": "e35c4457f66187eff006dda6d2c0fe12144ef2ec",
"gitTreeState": "clean",
"buildDate": "2022-10-26T09:25:34Z",
"goVersion": "go1.18.7b7",
"compiler": "gc",
"platform": "linux/amd64"
}

출력이 다음과 유사하면 VM 인스턴스가 제어 영역과 연결을 설정할 수 없습니다.

curl: (28) Connection timed out after 5000 milliseconds

VM 인스턴스가 제어 영역과 연결을 설정할 수 없는 경우 GKE 네트워킹 권장사항에서 제어 영역 연결 허용 섹션을 참조하세요.

근본 원인 해결 후 노드 등록 완료

노드 등록을 차단하는 문제를 해결한 후 처리하는 방법은 실패 컨텍스트에 따라 다릅니다.

클러스터 생성 시 노드 등록이 실패하면 클러스터를 삭제하고 다시 시도합니다.
클러스터 자동 확장 처리를 사용하여 확장하는 동안 노드 등록이 실패하면 VM 인스턴스가 다시 등록을 시도할 때까지 기다립니다.
노드 풀 생성 시 노드 등록에 실패한 경우:
- VM 인스턴스가 생성된 경우 VM 인스턴스가 다시 등록을 시도할 때까지 기다립니다.
- VM 인스턴스가 생성되지 않은 경우 노드 풀을 삭제하고 다시 시도합니다.
클러스터 크기 조절 시 노드 등록에 실패한 경우 명령어를 다시 실행하여 클러스터의 크기를 늘립니다.
복구 작업 도중과 같이 작업 범위를 벗어나 노드 등록이 실패한 경우 VM 인스턴스가 다시 등록을 시도할 때까지 기다립니다.

추가 조사를 위한 정보 수집

노드 등록 문제를 해결할 수 없는 경우 다음 안내에 따라 Cloud Customer Care의 조사에 도움이 되는 추가 정보를 수집할 수 있습니다. 이 단계에서는 프로젝트의 VM 인스턴스에 대한 SSH 액세스 권한이 필요하며, COS 이미지에 포함된 sosreport 유틸리티를 사용해야 합니다.

노드 등록에 실패한 인스턴스를 찾습니다.

sosreport를 사용하여 디버깅 정보 수집

또는 노드에 sosreport 유틸리티가 다운로드되지 않았고 설치할 수 없는 경우 다음 명령어를 실행하여 디버깅 정보를 수동으로 수집합니다.

sudo journalctl -u cloud-init-local
sudo journalctl -u cloud-init
sudo journalctl -u cloud-final
sudo journalctl -u cloud-config
systemctl status kubelet
journalctl -u kubelet
systemctl status kube-node-installation.service
systemctl status kube-node-configuration.service
journalctl -u kube-node-installation.service --no-pager
journalctl -u kube-node-configuration.service --no-pager
journalctl -u kubelet.service --no-pager

이 정보를 ZIP 파일로 패키징하여 Cloud Customer Care에 지원 케이스를 제출할 때 포함합니다.