error: the server doesn't have a resource type "services"와 같은 오류는 클러스터에 실행 중인 노드 풀이 없거나 Connect 게이트웨이가 노드 풀에 연결할 수 없을 때 발생할 수 있습니다. 노드 풀의 상태를 확인하려면 다음 명령어를 실행하세요.
출력에는 클러스터의 노드 풀 상태가 포함됩니다. 만일 노드 풀이 나열되지 않으면 노드 풀을 만드세요.
금지된 사용자
사용자 이름에 클러스터에 대한 관리자 액세스 권한이 없으면 다음 오류가 발생합니다.
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 게이트웨이를 사용하고 있으며 클러스터에 연결할 수 없으면 다음 단계를 수행해 봅니다.
출력에 클러스터에 대한 관리자 액세스 권한이 있는 사용자 이름이 포함됩니다.
예를 들면 다음과 같습니다.
{'username': 'administrator@example.com'}
현재 Google Cloud CLI로 인증된 사용자 이름을 가져옵니다.
gcloudconfigget-valueaccount
출력에는 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 배포가 클러스터의 노드 풀에서 실행되어야 합니다.
자세한 진단 정보를 보려면 다음 명령어를 실행합니다.
kubectlcluster-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 게이트웨이를 사용 설정했는지 확인합니다.
gcloudservicesenableconnectgateway.googleapis.com
Kubernetes 버전이 1.25 이전인 클러스터의 경우 하나 이상의 Linux 노드 풀이 실행 중이고 gke-connect-agent가 실행 중인지 확인하세요.
자세한 내용은 클러스터 연결 문제 해결을 참조하세요.
Kubernetes 버전이 1.25 이상인 클러스터의 경우 Cloud Logging을 사용하여 gke-connect-agent 로그를 확인하세요.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-08-07(UTC)"],[],[],null,["# Troubleshoot common issues\n==========================\n\nThis page shows you how to resolve common issues with GKE on Azure.\nIf you need additional assistance, reach out to [Cloud Customer Care](/kubernetes-engine/multi-cloud/docs/azure/getting-support).\n\nCommon error messages\n---------------------\n\nThe following sections explain the causes and resolutions for some common\nerror messages.\n\n### Server doesn't have a resource\n\nErrors such as `error: the server doesn't have a resource type \"services\"` can\nhappen when a cluster has no running node pools, or Connect gateway cannot\nconnect to a node pool. To check the status of your node pools, run the\nfollowing command: \n\n gcloud container azure node-pools list \\\n --cluster-name \u003cvar translate=\"no\"\u003eCLUSTER_NAME\u003c/var\u003e \\\n --location \u003cvar translate=\"no\"\u003eLOCATION\u003c/var\u003e\n\nReplace the following:\n\n- \u003cvar translate=\"no\"\u003eCLUSTER_NAME\u003c/var\u003e: your cluster's name\n- \u003cvar translate=\"no\"\u003eLOCATION\u003c/var\u003e: the Google Cloud location that manages your cluster\n\nThe output includes the status of your cluster's node pools. If you don't have\na node pool listed, [Create a node pool](/kubernetes-engine/multi-cloud/docs/azure/how-to/create-node-pool).\n\n### Forbidden user\n\nThe following error occurs when your username does not have administrator access\nto your cluster: \n\n Error from server (Forbidden): users \"administrator@example.com\" is forbidden:\n User \"system:serviceaccount:gke-connect:connect-agent-sa\" cannot impersonate\n resource \"users\" in API group \"\" at the cluster scope\n\nYou can configure additional users by passing the\n[`--admin-users`](/sdk/gcloud/reference/container/azure/clusters/create#--admin-users)\nflag when you create a cluster.\n\nIf you use Connect gateway and can't connect to your cluster, try the following\nsteps:\n\n1. Get the authorized users for your cluster.\n\n gcloud container azure clusters describe \u003cvar translate=\"no\"\u003eCLUSTER_NAME\u003c/var\u003e \\\n --format 'value(authorization.admin_users)'\n\n Replace \u003cvar translate=\"no\"\u003eCLUSTER_NAME\u003c/var\u003e with your cluster's name.\n\n The output includes the usernames with administrator access to the cluster.\n For example: \n\n {'username': 'administrator@example.com'}\n\n2. Get the username currently authenticated with the Google Cloud CLI.\n\n gcloud config get-value account\n\n The output includes the account authenticated with the Google Cloud CLI. If\n the output of the `gcloud containers azure clusters describe` and `gcloud\n config get-value account` don't match, run `gcloud auth login` and\n authenticate as the username with administrative access to the cluster.\n\nIssues with kubectl commands\n----------------------------\n\nThe following sections provide guidance on how to resolve issues with\nunresponsive or failing `kubectl` commands.\n\n### kubectl commands stop responding\n\nIf your cluster runs a Kubernetes version earlier than 1.25 and `kubectl`\ncommands are unresponsive or time out, the most common reason is that you have\nnot yet created a node pool. By default, GKE on Azure generates\n`kubeconfig` files that use Connect gateway as an internet-reachable endpoint.\nFor this to work, the `gke-connect-agent` Deployment needs to be running in\na node pool on the cluster.\n\nFor more diagnostic information, run the following command: \n\n kubectl cluster-info -v=9\n\nIf there are no running node pools, you see requests to\n`connectgateway.googleapis.com` fail with a 404\n`cannot find active connections for cluster` error.\n\nFor clusters with a Kubernetes version of 1.25 or later, the `gke-connect-agent`\nruns on the control plane, and a node pool is not required. If the `kubectl` command\nis unresponsive, check the control plane component logs with\n[Cloud Logging](/kubernetes-engine/multi-cloud/docs/azure/how-to/cloud-logging#control_plane_logs).\n\n### kubectl exec, attach, and port-forward commands fail\n\nThe `kubectl exec`, `kubectl attach`, and `kubectl port-forward` commands might\nfail with the message `error: unable to upgrade connection` when using\nConnect gateway. This is a limitation when using Connect gateway as your\nKubernetes API Server endpoint.\n\nTo work around this, use a `kubeconfig` that specifies the cluster's\nprivate endpoint. For instructions on accessing the cluster through its\nprivate endpoint, see\n[Configure cluster access for kubectl](/kubernetes-engine/multi-cloud/docs/azure/how-to/configure-cluster-access-for-kubectl).\n\n### Generic kubectl troubleshooting\n\nIf you use Connect gateway:\n\n- Ensure you have enabled Connect gateway in your Google Cloud project:\n\n gcloud services enable connectgateway.googleapis.com\n\n- For clusters with a Kubernetes version earlier than 1.25, ensure that you have at\n least one Linux node pool running and that the `gke-connect-agent` is running.\n For details, see\n [Troubleshoot cluster connections](/anthos/fleet-management/docs/troubleshooting).\n\n- For clusters with a Kubernetes version of 1.25 or later, check the `gke-connect-agent`\n logs with [Cloud Logging](/kubernetes-engine/multi-cloud/docs/azure/how-to/cloud-logging#control_plane_logs).\n\nWhat's next\n-----------\n\n- If you need additional assistance, reach out to [Cloud Customer Care](/kubernetes-engine/multi-cloud/docs/azure/getting-support)."]]
