TKGS 클러스터를 프로비저닝할 수 없는 경우 이 일반 오류 목록을 검토하여 문제를 해결합니다.

클러스터 API 로그 확인

TKG 클러스터를 생성할 수 없는 경우 CAPW/V가 작동하는지 확인합니다.

CAPW/V 컨트롤러는클러스터 API의 인프라별 구현입니다. CAPW/V는 감독자를 통해 사용하도록 설정됩니다. CAPW/V는 TKG의 구성 요소이며 TKG 클러스터의 수명 주기 관리를 담당합니다.

CAPW/V는 VirtualNetwork의 생성 및 업데이트를 담당합니다. VirtualNetwork가 준비된 경우에만 클러스터 노드 생성을 진행할 수 있습니다. 클러스터 생성 워크플로가 이 단계를 통과했습니까?

CAPW/V는 VirtualMachineService 생성 및 업데이트를 담당합니다. VirtualMachineService가 생성되었습니까? 외부 IP를 얻었습니까? 클러스터 생성 워크플로가 이 단계를 통과했습니까?

이러한 질문에 답하려면 다음과 같이 Cluster API 로그를 확인하십시오. 
kubectl config use-context tkg-cluster-ns
kubectl get pods -n vmware-system-capw  | grep capv-controller
kubectl logs -n vmware-system-capw -c manager capv-controller-manager-...

클러스터 규격 검증 오류

YAML 규격에 따라 공백 문자를 키 이름에 사용할 수 있습니다. 공백을 포함하는 스칼라 문자열이며 따옴표가 필요하지 않습니다.

그러나 TKGS 유효성 검사에서는 키 이름에 공백 문자를 사용할 수 없습니다. TKGS에서 유효한 키 이름은 영숫자, 대시(예: key-name), 밑줄(예: KEY_NAME) 또는 점(예: key.name)으로만 구성되어야 합니다.

클러스터 규격의 키 이름에 공백 문자를 사용하는 경우 TKGS 클러스터가 배포되지 않습니다. vmware-system-tkg-controller-manager 로그에 다음 오류 메시지가 표시됩니다.

Invalid value: \"Key Name\": a valid config key must consist of alphanumeric characters, '-', '_' or '.' (e.g. 'key.name', or 'KEY_NAME', or 'key-name', regex used for validation is '[-._a-zA-Z0-9]+')"

오류를 수정하려면 공백 문자를 완전히 제거하거나 지원되는 문자로 교체합니다.

TKG 클러스터 YAML 적용 시 오류 발생

TKG 클러스터 YAML을 적용할 때 오류가 발생하면 다음과 같이 문제를 해결합니다.
클러스터 네트워크가 올바른 상태가 아님
TKG 클러스터 프로비저닝 워크플로 이해:
  • CAPV는 각 TKG 클러스터 네트워크에 대한 VirtualNetwork 개체를 생성합니다.
  • 감독자가 NSX 네트워킹으로 구성된 경우 NCP는 VirtualNetwork 개체를 감시하고 각 VirtualNetwork에 대해 NSX Tier-1 라우터와 NSX 세그먼트를 생성합니다.
  • CAPV는 VirtualNetwork의 상태를 확인하고 준비가 되면 워크플로의 다음 단계로 진행합니다.

VM 서비스 컨트롤러는 CAPV에 의해 생성된 사용자 지정 개체를 감시하고 이러한 규격을 사용하여 TKG 클러스터를 구성하는 VM을 생성하고 구성합니다.

NCP(NSX Container Plugin)는 Kubernetes API를 통해 etcd에 추가된 네트워크 리소스를 감시하고 NSX에서 해당 개체의 생성을 오케스트레이션하는 컨트롤러입니다.

이러한 각 컨트롤러는 감독자 제어부에서 Kubernetes 포드로 실행됩니다. 네트워크 문제를 해결하려면 CAPV 컨트롤러 로그, VM 서비스 로그 및 NCP 로그를 확인하십시오.

컨테이너 로그를 확인합니다. 여기서 name-XXXX는 실행할 때 고유한 포드 이름입니다. 
kubectl get pods -A
kubectl logs pod/name-XXXXX -c pod-name -n namesapce
제어부 노드 수가 잘못됨

감독자의 TKG 클러스터는 1개 또는 3개의 제어부 노드를 지원합니다. 다른 수의 복제본을 입력하면 클러스터 프로비저닝이 실패합니다.

제어부/작업자 VM에 대한 스토리지 클래스가 잘못됨
다음 명령을 실행합니다. 
kubectl describe ns <tkg-clsuter-namesapce>

TKG 클러스터를 생성하려는 네임스페이스에 스토리지 클래스가 할당되었는지 확인합니다. 해당 스토리지 클래스를 참조하는 vSphere 네임스페이스에 ResourceQuota가 있어야 하며 스토리지 클래스가 감독자에 존재해야 합니다.

이름이 감독자에 있는 스토리지 클래스와 일치하는지 확인합니다. kubectl get storageclasses 감독자를 vSphere 관리자 권한으로 실행합니다. WCP는 스토리지 프로파일을 감독자에 적용할 때 이름을 변환할 수 있습니다(예: 하이픈이 밑줄이 됨).

잘못된 VM 클래스

클러스터 YAML에 제공된 값이 kubectl get virtualmachineclass에서 반환된 VM 클래스 중 하나와 일치하는지 확인합니다. 바인딩된 클래스만 TKG 클러스터에서 사용할 수 있습니다. VM 클래스는 vSphere 네임스페이스에 추가할 때 바인딩됩니다.

kubectl get virtualmachineclasses 명령은 감독자의 모든 VM 클래스를 반환하지만 바인딩된 클래스만 사용할 수 있습니다.

TKR 배포를 찾을 수 없음
다음과 유사한 오류가 표시되는 경우: 
“Error from server (unable to find Kubernetes distributions): 
admission webhook “version.mutating.tanzukubernetescluster.run.tanzu.vmware.com” 
denied the request: unable to find Kubernetes distributions”

컨텐츠 라이브러리 문제 때문일 수 있습니다. 사용 가능한 항목을 나열하려면 kubectl get virtualmachineimages -A 명령을 사용합니다. 결과는 컨텐츠 라이브러리에서 사용 가능하고 동기화되거나 업데이트되는 항목입니다.

감독자의 TKG에는 새 TKR API와 호환되는 새 TKR 이름이 있습니다. 컨텐츠 라이브러리에서 각 TKR의 이름을 올바르게 지정해야 합니다.

컨텐츠 라이브러리의 이름: photon-3-amd64-vmi-k8s-v1.23.8---vmware.2-tkg.1-zshippable

TKG 클러스터 규격의 해당 이름: version: v1.23.8+vmware.2-tkg.1-zshippable

TKG YAML이 적용되지만 VM이 생성되지 않음

TKG 2.0 클러스터 YAML이 유효하고 적용되지만 노드 VM이 생성되지 않은 경우 다음과 같이 문제를 해결합니다.
CAPI/CAPV 리소스 확인

TKG가 CAPI/CAPV 수준 리소스를 생성했는지 확인합니다.

  • CAPV가 VirtualMachine 리소스를 생성했는지 확인합니다.
  • VM Operator 로그를 확인하여 VM이 생성되지 않은 이유를 확인합니다. 예를 들어 ESX 호스트의 리소스가 부족하여 OVF 배포가 실패했을 수 있습니다.
  • CAPV 및 VM Operator 로그를 확인합니다.
  • NCP 로그를 확인합니다. NCP는 제어부에 대한 VirtualNetwork, VirtualNetworkInterface, LoadBalancer 인식을 담당합니다. 이러한 리소스와 관련된 오류가 있는 경우 문제가 될 수 있습니다.
가상 시스템 서비스 오류
가상 시스템 서비스 오류
  • 네임스페이스에서 kubectl get virtualmachineservices 명령을 실행합니다.
  • 가상 시스템 서비스가 생성되었습니까?
  • 네임스페이스에서 kubectl describe virtualmachineservices 명령을 실행합니다.
  • 가상 시스템 서비스에 보고된 오류가 있습니까?
가상 네트워크 오류

네임스페이스에서 kubectl get virtualnetwork 명령을 실행합니다.

이 클러스터에 대해 가상 네트워크가 생성되었습니까?

네임스페이스에서 kubectl describe virtual network 명령을 실행합니다.

VM에 대한 가상 네트워크 인터페이스가 생성되었습니까?

TKG 클러스터 제어부가 실행되지 않음

TKG 제어부가 실행되지 않으면 오류가 발생했을 때 리소스가 준비되었는지 확인합니다. 조인 노드 제어부가 작동하지 않습니까? 아니면 Init 노드가 작동하지 않습니까? 또한 노드 개체에 제공자 ID가 설정되어 있지 않은지 확인합니다.
오류가 발생했을 때 리소스가 준비되었는지 확인

로그를 찾아보는 것 외에도 관련 개체의 상태 ControlPlaneLoadBalancer를 확인하면 오류가 발생했을 때 리소스가 준비되었는지 이해하는 데 도움이 됩니다. 네트워크 문제 해결을 참조하십시오.

조인 노드 제어부가 작동하지 않습니까? 아니면 Init 노드가 작동하지 않습니까?

노드 조인이 제대로 작동하지 않는 경우가 있습니다. 특정 VM에 대한 노드 로그를 확인합니다. Init 노드가 나타나지 않으면 클러스터에 작업자 및 제어부 노드가 없을 수 있습니다.

노드 개체에 제공자 ID가 설정되지 않음

VM이 생성되면 IP가 있는지 확인한 다음 cloud-init 로그를 확인합니다(kubeadm 명령이 제대로 실행됨).

CAPI 컨트롤러 로그를 확인하여 문제가 있는지 확인합니다. TKG 클러스터에서 kubectl get nodes 명령을 사용하여 확인한 다음 노드 개체에 제공자 ID가 있는지 확인할 수 있습니다.

TKG 작업자 노드가 생성되지 않음

TKG 클러스터 및 제어부 VM이 생성되었지만 작업자가 생성되지 않았거나 다른 가상 시스템 개체가 생성되지 않은 경우 다음을 시도합니다. 
kubectl describe cluster CLUSTER-NAME

네임스페이스에서 가상 시스템 리소스를 확인합니다. 다른 리소스가 생성되었습니까?

그렇지 않은 경우 CAPV 로그를 확인하여 사용할 수 없는 다른 가상 시스템 개체 부트스트랩 데이터가 생성되지 않는 이유를 확인합니다.

CAPI가 로드 밸런서(노드 VM IP가 있는 NSX 또는 외부 로드 밸런서가 있는 VDS)를 통해 TKG 클러스터 제어부와 통신할 수 없는 경우, 네임스페이스의 암호를 사용하여 TKG 클러스터 kubeconfig를 가져옵니다.

네임스페이스의 암호를 사용하여 TKG 클러스터 kubeconfig를 가져옵니다. 
kubectl get secret -n <namespace> <tkg-cluster-name>-kubeconfig -o jsonpath='{.data.value}' | base64 -d 
> tkg-cluster-kubeconfig; kubectl --kubeconfig tkg-cluster-kubeconfig get pods -A

'연결이 거부됨'으로 인해 실패하면 제어부가 제대로 초기화되지 않았을 수 있습니다. I/O 시간 초과가 있는 경우 kubeconfig에서 IP 주소에 대한 연결을 확인합니다.

내장된 로드 밸런서가 있는 NSX:

  • 제어부 LB가 작동 중이고 연결 가능한지 확인합니다.
  • LB에 IP가 없는 경우 NCP 로그를 확인하고 NSX-T UI를 확인하여 관련 구성 요소가 올바른 상태인지 확인합니다. (NSX-T LB, VirtualServer, ServerPool은 모두 정상 상태여야 합니다.)
  • LB에 IP가 있지만 연결할 수 없는 경우 curl -k https://<LB- VIP>:6443/healthz 명령은 승인되지 않음 오류를 반환해야 합니다.

    LoadBalancer 서비스 유형 외부 IP가 "보류 중" 상태인 경우 TKG 클러스터가 감독자 LB VIP를 통해 감독자 Kubernetes API와 통신할 수 있는지 확인합니다. 겹치는 IP 주소가 없는지 확인합니다.

TKG 제어부 노드가 정상 상태인지 확인합니다.
  • TKG 클러스터 제어부가 오류를 보고하는지 확인합니다(예: 제공자 ID로 노드를 만들 수 없음).
  • TKG 클러스터 클라우드 제공자가 노드를 올바른 제공자 ID로 표시하지 않았으므로 CAPI는 게스트 클러스터 노드의 제공자 ID와 감독자 클러스터의 시스템 리소스를 비교하여 확인할 수 없습니다.
제어부 VM에 SSH를 통해 연결하거나 TKG 클러스터 kubeconfig를 사용하여 TKG Cloud Provider Pod가 실행 중이거나 기록된 오류가 있는지 확인합니다. Kubernetes 관리자 및 시스템 사용자로 TKG 서비스 클러스터에 연결의 내용을 참조하십시오. 
kubectl get po -n vmware-system-cloud-provider
kubectl logs -n vmware-system-cloud-provider <pod name>

VMOP가 VirtualMachineService를 성공적으로 조정하지 못한 경우 VM Operator 로그를 확인합니다.

NCP에서 NSX-T 리소스를 생성하는 데 문제가 있는 경우 NCP 로그를 확인합니다.

제어부가 제대로 초기화되지 않은 경우 VM IP를 확인합니다. 상태에 VM IP가 포함되어야 합니다. 
kubectl get virtualmachine -n <namespace> <TKC-name>-control-plane-0 -o yaml
ssh vmware-system-user@<vm-ip> -i tkc-cluster-ssh
kubeadm이 오류를 기록했는지 확인합니다. 
cat /var/log/cloud-init-output.log | less

프로비저닝된 TKG 클러스터가 "생성" 단계에서 멈춤

다음 명령을 실행하여 클러스터 상태를 확인합니다.

kubectl get tkc -n <namespace>
kubectl get cluster -n <namespace> 
kubectl get machines -n <namespace>
KubeadmConfig가 있었지만 CAPI에서 찾을 수 없었습니다. vmware-system-capv의 토큰에 kubeadmconfig를 쿼리할 수 있는 올바른 사용 권한이 있는지 확인했습니다. 
$kubectl --token=__TOKEN__ auth can-i get kubeadmconfig 
yes
controller-runtime 캐시가 업데이트되지 않았을 수 있습니다. CAPI 감시 캐시가 오래되어 새 개체를 선택하지 않을 수 있습니다. 필요한 경우 capi-controller-manager를 다시 시작하여 문제를 해결합니다. 
kubectl rollout restart deployment capi-controller-manager -n vmware-system-capv

vSphere 네임스페이스가 "종료" 단계에서 멈춤

TKR, 감독자 및 vCenter가 버전 호환성 관점에서 동기화되어 있는지 확인합니다.

네임스페이스는 네임스페이스 아래의 모든 리소스가 차례로 삭제된 경우에만 삭제할 수 있습니다. 
kubectl describe namespace NAME

다음 오류가 발견되었습니다. "서버 오류(Kubernetes 배포를 찾을 수 없음): admission webhook “version.mutating.tanzukubernetescluster.run.tanzu.vmware.com” denied the request: Kubernetes 배포를 찾을 수 없음"

vCenter에서 가상 시스템 이미지를 확인합니다. 
kubectl get virtualmachineimages -A