이 문서는 2021년 11월에 출시된 Azure용 GKE의 최신 버전을 대상으로 합니다. 자세한 정보는 출시 노트를 참조하세요.

일반적인 문제 해결

이 페이지에서는 Azure용 GKE의 일반적인 문제를 해결하는 방법을 보여줍니다.

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

일반적인 오류 메시지

다음 섹션에서는 몇 가지 일반적인 오류 메시지의 원인과 해결 방법을 설명합니다.

서버에 리소스가 없음

error: the server doesn't have a resource type "services"와 같은 오류는 클러스터에 실행 중인 노드 풀이 없거나 Connect 게이트웨이가 노드 풀에 연결할 수 없을 때 발생할 수 있습니다. 노드 풀의 상태를 확인하려면 다음 명령어를 실행하세요.

gcloud container azure node-pools list \
    --cluster-name CLUSTER_NAME \
    --location LOCATION

다음을 바꿉니다.

CLUSTER_NAME: 클러스터 이름
LOCATION: 클러스터를 관리하는 Google Cloud 위치입니다.

출력에는 클러스터의 노드 풀 상태가 포함됩니다. 만일 노드 풀이 나열되지 않으면 노드 풀을 만드세요.

금지된 사용자

사용자 이름에 클러스터에 대한 관리자 액세스 권한이 없으면 다음 오류가 발생합니다.

Error from server (Forbidden): users "administrator@example.com" is forbidden:
User "system:serviceaccount:gke-connect:connect-agent-sa" cannot impersonate
resource "users" in API group "" at the cluster scope

클러스터를 만들 때 --admin-users 플래그를 전달하여 추가 사용자를 구성할 수 있습니다.

Connect 게이트웨이를 사용하고 있으며 클러스터에 연결할 수 없으면 다음 단계를 수행해 봅니다.

클러스터의 승인된 사용자를 가져옵니다.
```
gcloud container azure clusters describe CLUSTER_NAME \
    --format 'value(authorization.admin_users)'
```
CLUSTER_NAME을 클러스터 이름으로 바꿉니다.

출력에 클러스터에 대한 관리자 액세스 권한이 있는 사용자 이름이 포함됩니다. 예를 들면 다음과 같습니다.
```
{'username': 'administrator@example.com'}
```
현재 Google Cloud CLI로 인증된 사용자 이름을 가져옵니다.
```
gcloud config get-value account
```
출력에는 Google Cloud CLI로 인증된 계정이 포함됩니다. gcloud containers azure clusters describe 및 gcloud config get-value account의 출력이 일치하지 않으면 gcloud auth login을 실행하고 클러스터에 대한 관리 액세스 권한이 있는 사용자 이름으로 인증합니다.

kubectl 명령어 관련 문제

다음 섹션에서는 응답하지 않거나 실패한 kubectl 명령어 관련 문제를 해결하는 방법을 안내합니다.

kubectl 명령어가 응답하지 않음

클러스터에서 Kubernetes 1.25 이전 버전을 실행하고 kubectl 명령어가 응답하지 않거나 타임아웃되는 경우 가장 일반적인 원인은 아직 노드 풀을 만들지 않은 것입니다. 기본적으로 Azure용 GKE에서 Connect 게이트웨이를 인터넷에 연결할 수 있는 엔드포인트로 사용하는 kubeconfig 파일을 생성합니다. 이 작업을 수행하려면 gke-connect-agent 배포가 클러스터의 노드 풀에서 실행되어야 합니다.

자세한 진단 정보를 보려면 다음 명령어를 실행합니다.

kubectl cluster-info -v=9

실행 중인 노드 풀이 없으면 404 cannot find active connections for cluster 오류가 표시되면서 connectgateway.googleapis.com 요청이 실패합니다.

Kubernetes 버전이 1.25 이상인 클러스터의 경우 gke-connect-agent가 제어 영역에서 실행되며 노드 풀이 필요하지 않습니다. kubectl 명령어가 응답하지 않으면 Cloud Logging을 사용하여 제어 영역 구성요소 로그를 확인합니다.

kubectl exec, attach, port-forward 명령어 실패

Connect 게이트웨이를 사용할 때 error: unable to upgrade connection 메시지가 표시되면서 kubectl exec, kubectl attach, kubectl port-forward 명령어가 실패할 수 있습니다. 이는 Connect 게이트웨이를 Kubernetes API 서버 엔드포인트로 사용하는 경우 적용되는 제한사항입니다.

이 문제를 해결하려면 클러스터의 비공개 엔드포인트를 지정하는 kubeconfig를 사용합니다. 비공개 엔드포인트를 통해 클러스터에 액세스하는 방법은 kubectl의 클러스터 액세스 구성을 참조하세요.

일반 kubectl 문제 해결

Connect 게이트웨이를 사용하는 경우:

Google Cloud 프로젝트에서 Connect 게이트웨이를 사용 설정했는지 확인합니다.
```
gcloud services enable connectgateway.googleapis.com
```
Kubernetes 버전이 1.25 이전인 클러스터의 경우 하나 이상의 Linux 노드 풀이 실행 중이고 gke-connect-agent가 실행 중인지 확인하세요. 자세한 내용은 클러스터 연결 문제 해결을 참조하세요.
Kubernetes 버전이 1.25 이상인 클러스터의 경우 Cloud Logging을 사용하여 gke-connect-agent 로그를 확인하세요.

다음 단계

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