클러스터 연결 문제 해결

이 페이지에서는 Google Cloud 콘솔, Google Cloud CLI를 사용하거나 Connect 게이트웨이를 통해 kubectl를 사용하여 Fleet에 클러스터를 등록하거나 Google Cloud 외부의 클러스터에 연결할 때 발생할 수 있는 일반적인 오류와 문제 해결 방법에 대해 설명합니다.

온프레미스 클러스터와 다른 퍼블릭 클라우드의 클러스터는 Connect 에이전트를 사용하여 클러스터와 Google Cloud 프로젝트 간의 연결을 설정 및 유지하고 Kubernetes 요청을 처리합니다. '연결할 수 없는 에이전트' 또는 '클러스터의 제어 영역에 연결하지 못함'과 같은 오류가 표시되면 Connect Agent에 문제가 있을 수 있습니다.

Connect Agent 로그 수집

Google Cloud 외부에서 클러스터를 등록하면 Connect Agent를 사용하여 클러스터와 Fleet 호스트 프로젝트 간의 통신을 처리합니다. Connect Agent는 일반적으로 네임스페이스 gke-connect의 클러스터에 설치되는 gke-connect-agent 배포입니다. 이 Connect Agent의 로그를 수집하면 등록 및 연결 문제를 해결하는 데 유용할 수 있습니다.

다음 명령어를 실행하여 에이전트의 로그를 검색할 수 있습니다(필요한 경우 줄 수를 조정).

kubectl logs -n gke-connect -l app=gke-connect-agent --tail=-1

프로젝트 클러스터에서 실행 중인 모든 Connect Agent에 대한 정보를 가져오려면 다음을 실행합니다.

kubectl describe deployment --all-namespaces -l app=gke-connect-agent

연결에 성공한 경우 아래 예와 비슷한 항목이 있어야 합니다.

2019/02/16 17:28:43.312056 dialer.go:244: dialer: dial: connected to gkeconnect.googleapis.com:443
2019/02/16 17:28:43.312279 tunnel.go:234: serve: opening egress stream...
2019/02/16 17:28:43.312439 tunnel.go:248: serve: registering endpoint="442223602236", shard="88d2bca5-f40a-11e8-983e-42010a8000b2" {"Params":{"GkeConnect":{"endpoint_class":1,"metadata":{"Metadata":{"Default":{"manifest_version":"234227867"}}}}}} ...
2019/02/16 17:28:43.312656 tunnel.go:259: serve: serving requests...

오류 tls: oversized record

증상

다음과 같은 오류가 발생할 수 있습니다.

... dialer: dial: connection to gkeconnect.googleapis.com:443 failed after
388.080605ms: serve: egress call failed: rpc error: code = Unauthenticated
desc = transport: oauth2: cannot fetch token: Post
https://oauth2.googleapis.com/token: proxyconnect tcp: tls: oversized record
received with length 20527
가능한 원인

Connect Agent가 HTTPS를 통해 HTTP 전용 프록시에 연결하려 합니다. Connect Agent는 CONNECT 기반 HTTP 프록시만 지원합니다.

해결 방법

프록시 환경 변수를 다음과 같이 재구성해야 합니다.

http_proxy=http://[PROXY_URL]:[PROXY_PORT]
https_proxy=http://[PROXY_URL]:[PROXY_PORT]

오류 oauth2: cannot fetch token

증상

다음과 같은 오류가 발생할 수 있습니다.

...  dialer: dial: connection to gkeconnect.googleapis.com:443 failed
after 388.080605ms: serve: egress call failed: rpc error: code =
Unauthenticated desc = transport: oauth2: cannot fetch token: Post
https://oauth2.googleapis.com/token: read tcp 192.168.1.40:5570->1.1.1.1:80
read: connection reset by peer
가능한 원인

특정 URL이 HTTP 프록시에서 허용되지 않아 업스트림 HTTP 프록시가 연결을 재설정하려 합니다. 위 예에서 1.1.1.1:80은 HTTP 프록시 주소입니다.

해결 방법

HTTP 프록시 허용 목록에 다음 URL/도메인이 포함되어 있는지 확인합니다.

gkeconnect.googleapis.com
oauth2.googleapis.com/token
www.googleapis.com/oauth2/v1/certs

Connect Agent 포드 비정상 종료 및 다시 시작 오류

증상

Google Cloud 콘솔에서 클러스터에 대해 "연결할 수 없는 에이전트" 오류가 간헐적으로 표시되거나 포드가 여러 번 다시 시작된 것을 확인할 수 있습니다.

$ kubectl get pods -n gke-connect
NAME                                                READY   STATUS    RESTARTS   AGE
gke-connect-agent-20230706-03-00-6b8f75dd58-dzwmt   1/1     Running   5          99m

이러한 동작을 문제 해결하려면 포드 세부정보를 보고 마지막 상태가 메모리가 부족하여(OOMKilled) 종료되었는지 확인합니다.

  kubectl describe pods/gke-connect-agent-20230706-03-00-6b8f75dd58-dzwmt -n gke-connect
        <some details skipped..>
        Last State:     Terminated
        Reason:       OOMKilled
가능한 원인
기본적으로 Connect Agent 포드는 256MiB RAM 한도가 있습니다. 클러스터에 설치된 워크로드가 많으면 일부 요청과 응답이 예상한 대로 처리되지 않을 수 있습니다.
해결 방법

Connect Agent 배포를 업데이트하고 다음과 같이 더 높은 메모리 한도를 부여합니다.

containers:
  name: gke-connect-agent-20230706-03-00
  resources:
    limits:
      memory: 512Mi

오류 PermissionDenied

증상

다음과 같은 오류가 발생할 수 있습니다.

tunnel.go:250: serve: recv error: rpc error: code = PermissionDenied
desc = The caller does not have permission
dialer.go:210: dialer: dial: connection to gkeconnect.googleapis.com:443
failed after 335.153278ms: serve: receive request failed: rpc error:
code = PermissionDenied desc = The caller does not have permission
dialer.go:150: dialer: connection done: serve: receive request failed:
rpc error: code = PermissionDenied desc = The caller does not have permission
dialer.go:228: dialer: backoff: 1m14.1376766s
가능한 원인

이는 Connect Agent가 Google에 연결하도록 승인하기 위해 만든 Google Cloud 서비스 계정에 필요한 Identity and Access Management (IAM) 역할을 결합하지 않았기 때문일 수 있습니다. Google Cloud 서비스 계정에는 gkehub.connect IAM 역할이 필요합니다.

이름이 같은 Google Cloud 서비스 계정을 삭제하고 다시 만든 경우에도 이 문제가 발생할 수 있습니다. 또한 이 경우 IAM 역할 결합을 삭제하고 다시 만들어야 합니다. 자세한 내용은 서비스 계정 삭제 및 다시 만들기를 참조하세요.

해결 방법

gkehub.connect 역할을 서비스 계정에 결합합니다(gkehub.admin 역할에는 연결에 적합한 권한이 없으며 서비스 계정에서 사용되지 않음).

예를 들어 이름이 my-project인 프로젝트와 gkeconnect@my-project.iam.gserviceaccount.com이라는 Google Cloud 서비스 계정의 경우 다음 명령어를 실행하여 역할을 서비스 계정에 binding합니다.

gcloud projects add-iam-policy-binding my-project --member \
serviceAccount:gkeconnect@my-project.iam.gserviceaccount.com \
--role "roles/gkehub.connect"

다음 명령어의 출력을 검사하여 서비스 계정 권한이 Google Cloud 서비스 계정에 적용되었는지 확인할 수 있습니다. 이렇게 하면 연관된 Google Cloud 서비스 계정에 binding된 role: roles/gkehub.connect가 표시됩니다.

gcloud projects get-iam-policy my-project

IAM 역할을 Google Cloud 서비스 계정에 binding할 때 발생하는 오류

증상

다음과 같은 오류가 발생할 수 있습니다.

ERROR: (gcloud.projects.add-iam-policy-binding) PERMISSION_DENIED:
Service Management API has not been used in project [PROJECT_ID] before or it
is disabled. Enable it by visiting
https://console.developers.google.com/apis/api/servicemanagement.googleapis.com/overview?project=[PROJECT_ID]
then retry. If you enabled this API recently, wait a few minutes for the
action to propagate to our systems and retry.
가능한 원인

gcloud projects add-iam-policy-binding 명령어를 실행할 수 있는 IAM 권한이 없을 수 있습니다.

해결 방법

resourcemanager.projects.setIamPolicy 권한이 있어야 합니다. Project IAM Admin, Owner 또는 Editor 역할이 있는 경우 명령어를 실행할 수 있습니다. 내부 보안 정책으로 인해 명령어를 실행할 수 없으면 관리자에게 문의하세요.

잘못된 서비스 계정 키 오류

증상

다음과 같은 오류가 발생할 수 있습니다.

2020/05/08 01:22:21.435104 environment.go:214: Got ExternalID 3770f509-b89b-48c4-96e0-860bb70b3a58 from namespace kube-system.
2020/05/08 01:22:21.437976 environment.go:485: Using gcp Service Account key
2020/05/08 01:22:21.438140 gkeconnect_agent.go:50: error creating kubernetes connect agent: failed to get tunnel config: unexpected end of JSON input
가능한 원인

이러한 로그는 Connect Agent가 설치 중에 잘못된 서비스 계정 키로 제공되었음을 나타냅니다.

해결 방법

서비스 계정 사용자 인증 정보가 포함된 JSON 파일을 새로 만든 후 클러스터 등록 단계를 다시 수행하여 Connect Agent를 다시 설치합니다.

만료된 서비스 계정 키 오류

증상

다음과 같은 오류가 발생할 수 있습니다.

2020/05/08 01:22:21.435104 dialer.go:277: dialer: dial: connection to gkeconnect.googleapis.com:443 failed after 37.901608ms:
serve: egress call failed: rpc error: code = Unauthenticated desc = transport: oauth2: cannot fetch token: 400 Bad Request
Response: {"error":"invalid_grant","error_description":"Invalid JWT Signature."}
가능한 원인

이러한 로그는 Connect Agent가 Google 승인 서비스에서 허용하지 않는 문제가 있는 서비스 계정 키로 Connect에 전화 접속했음을 나타냅니다. 서비스 계정 키 파일이 손상되었거나 키가 만료되었을 수 있습니다.

키가 만료되었는지 확인하려면 Google Cloud 콘솔의 서비스 계정 세부정보 페이지에서 '키 만료 날짜'를 확인하세요. 경우에 따라 프로젝트/조직에 기본적으로 서비스 계정의 수명이 짧을 수 있는 특수 정책이 있을 수 있습니다.

해결 방법

서비스 계정 사용자 인증 정보가 포함된 JSON 파일을 새로 만든 후 클러스터 등록 단계를 다시 수행하여 Connect Agent를 다시 설치합니다.

왜곡된 시스템 시계 오류

증상

다음과 같은 오류가 발생할 수 있습니다.

acceptCall: failed to parse token in req [rpc_id=1]: Token used before issued [rpc_id=1]
가능한 원인

로그 메시지는 일반적으로 클러스터에 클록 보정값이 있음을 나타냅니다. 클러스터 발급 토큰에 동기화되지 않은 타임스탬프가 있어 토큰이 거부됩니다.

해결 방법

시계가 올바르게 동기화되지 않았는지 확인하려면 클러스터에서 date 명령어를 실행하여 표준 시간과 비교하면 됩니다. 일반적으로 몇 초간의 드리프트로 인해 이 문제가 발생합니다. 이 문제를 해결하려면 클러스터의 시계를 다시 동기화하세요.

Google Cloud 콘솔에서 워크로드를 확인할 수 없음

증상

Connect Agent 로그에서 다음과 같은 오류를 확인할 수 있습니다.

"https://10.0.10.6:443/api/v1/nodes" YYYY-MM-DDTHH mm:ss.sssZ http.go:86: GET
"https://10.0.10.6:443/api/v1/pods" YYYY-MM-DDTHH mm:ss.sssZ http.go:139:
Response status: "403 Forbidden" YYYY-MM-DDTHH mm:ss.sssZ http.go:139:
Response status: "403 Forbidden"`
가능한 원인

이러한 로그는 등록 중에 제공한 사용자 인증 정보를 사용하여 Google Cloud가 클러스터에 액세스하려고 시도함을 나타냅니다. 403 오류는 사용자 인증 정보에 클러스터에 액세스하는 데 필요한 권한이 없음을 나타냅니다.

해결 방법

토큰 및 결합된 계정을 확인하고 클러스터에 적절한 권한이 있는지 확인합니다.

컨텍스트 기한 초과

증상

다음과 같은 오류가 발생할 수 있습니다.

2019/03/06 21:08:43.306625 dialer.go:235: dialer: dial: connecting to gkeconnect.googleapis.com:443...
2019/03/06 21:09:13.306893 dialer.go:240: dialer: dial: unable to connect to gkeconnect.googleapis.com:443: context deadline exceeded
2019/03/06 21:09:13.306943 dialer.go:183: dialer: connection done: context deadline exceeded
가능한 원인

이 오류는 Connect Agent가 gkeconnect.googleapis.com과 통신할 수 없는 하위 수준의 TCP 네트워킹 문제를 나타냅니다.

해결 방법

이 클러스터의 포드 워크로드가 확인되고 포트 443에서 gkeconnect.googleapis.com에 대한 아웃바운드 연결이 있는지 확인합니다.

에이전트 연결이 간헐적으로 실패

증상

Connect Agent 로그에서 다음과 같은 오류를 확인할 수 있습니다.

2020/10/06 18:02:34.409749 dialer.go:277: dialer: dial: connection to gkeconnect.googleapis.com:443 failed after 8m0.790286282s: serve: receive request failed: rpc error: code = Unavailable desc = transport is closing
2020/10/06 18:02:34.416618 dialer.go:207: dialer: connection done: serve: receive request failed: rpc error: code = Unavailable desc = transport is closing
2020/10/06 18:02:34.416722 dialer.go:295: dialer: backoff: 978.11948ms
2020/10/06 18:02:34.410097 tunnel.go:651: sendResponse: EOF [rpc_id=52]
2020/10/06 18:02:34.420077 tunnel.go:651: sendResponse: EOF [rpc_id=52]
2020/10/06 18:02:34.420204 tunnel.go:670: sendHalfClose: EOF [rpc_id=52]
2020/10/06 18:02:34.401412 tunnel.go:670: sendHalfClose: EOF [rpc_id=53]
가능한 원인

Connect Agent에 리소스가 부족하면 Connect에 대한 연결이 종료됩니다(예: t3.medium과 같이 더 작은 AWS EC2 인스턴스).

해결 방법

AWS 및 T3 인스턴스 유형을 사용하는 경우 T3 무제한을 사용 설정하거나 노드 풀에 대해 더 많은 리소스와 함께 인스턴스 유형을 사용합니다.

Fleet에서 프로젝트에 액세스할 수 없음

증상

일부 Fleet 작업(일반적으로 클러스터 등록) 중에 다음과 유사한 오류가 나타날 수 있습니다.

ERROR: (gcloud.container.hub.memberships.register) failed to initialize Feature
"authorizer", the fleet service account (service-PROJECT_NUMBER@gcp-sa-gkehub.iam.gserviceaccount.com) may not have access to your project
가능한 원인

Fleet의 기본 서비스 계정인 gcp-sa-gkehub이 실수로 프로젝트에서 결합 해제될 수 있습니다. Fleet 서비스 에이전트는 서비스 계정에 클러스터 리소스를 관리할 권한을 부여하는 IAM 역할입니다. 서비스 계정에서 이 역할 결합을 제거하면 기본 서비스 계정이 프로젝트에서 결합 해제되어 클러스터 등록 및 기타 클러스터 작업이 불가능해질 수 있습니다.

gcloud CLI 또는 Google Cloud 콘솔을 사용하여 프로젝트에서 서비스 계정이 삭제되었는지 확인할 수 있습니다. 명령어나 대시보드에 서비스 계정 중 gcp-sa-gkehub이 표시되지 않으면 서비스 계정이 결합 해제된 것입니다.

gcloud

다음 명령어를 실행합니다.

gcloud projects get-iam-policy PROJECT_NAME

여기서 PROJECT_NAME은 클러스터를 등록하려는 프로젝트의 이름입니다.

콘솔

Google Cloud 콘솔에서 IAM 및 관리자 페이지로 이동합니다.

해결 방법

Fleet Service Agent 역할 결합을 삭제했으면 다음 명령어를 실행하여 역할 결합을 복원합니다.

PROJECT_NUMBER=$(gcloud projects describe PROJECT_NAME --format "value(projectNumber)")
gcloud projects add-iam-policy-binding PROJECT_NAME \
  --member "serviceAccount:service-${PROJECT_NUMBER}@gcp-sa-gkehub.iam.gserviceaccount.com" \
  --role roles/gkehub.serviceAgent

역할 결합이 부여되었는지 확인하려면 다음을 실행합니다.

gcloud projects get-iam-policy PROJECT_NAME

gkehub.serviceAgent 역할과 함께 서비스 계정 이름이 표시되면 역할 결합이 부여된 것입니다. 예를 들면 다음과 같습니다.

- members:
  - serviceAccount:service-1234567890@gcp-sa-gkehub.iam.gserviceaccount.com
  role: roles/gkehub.serviceAgent

Fleet과 다른 프로젝트의 GKE 클러스터를 등록하는 중에 발생한 오류

증상

Fleet 프로젝트와 다른 프로젝트에서 GKE 클러스터를 등록할 때 gcloud CLI에서 다음과 비슷한 오류를 관찰하게 될 수 있습니다.

...
message: 'DeployPatch failed'>
detail: 'DeployPatch failed'
...

이는 다음 필터를 적용하여 로깅에서 확인할 수 있습니다.

resource.type="gke_cluster"
resource.labels.cluster_name="my-cluster"
protoPayload.methodName="google.container.v1beta1.ClusterManager.UpdateCluster"
protoPayload.status.code="13"
protoPayload.status.message="Internal error."
severity=ERROR

가능한 원인

Fleet 기본 서비스 계정에는 GKE 클러스터 프로젝트의 필수 권한이 없습니다.

해결 방법

클러스터를 등록하기 전에 Fleet 기본 서비스 계정에 필수 권한을 부여합니다.

사용자 인증 정보 순환 중에 GKE 클러스터 등록/등록 취소 또는 등록된 GKE 클러스터의 Fleet 멤버십 세부정보 업데이트 오류

증상

클러스터 사용자 인증 정보(https://cloud.google.com/kubernetes-engine/docs/how-to/credential-rotate)를 순환하는 동안 GKE 클러스터의 등록/등록 취소 또는 등록된 GKE 클러스터의 멤버십 업데이트에 오류가 발생할 수 있습니다.

ERROR: (gcloud.container.hub.memberships.unregister) "code": 13,
"message": "an internal error has occurred"
가능한 원인

클러스터 사용자 인증 정보는 Fleet 서비스가 액세스할 수 없는 중간 상태입니다.

해결 방법

클러스터를 등록/등록 취소하거나 등록된 GKE 클러스터의 멤버십을 업데이트하기 전에 순환을 완료하세요.

Fleet API를 사용 중지할 때 발생하는 오류

증상

Fleet API(gkehub.googleapis.com)를 사용 중지할 때 다음과 유사한 오류가 발생할 수 있습니다.

Not ready to deactivate the service on this project; ensure there are no more resources managed by this service.
가능한 원인

이 프로젝트에는 Google Cloud (멤버십) 또는 Fleet 수준의 기능에 사용 설정된 클러스터가 아직 있습니다. API를 사용 중지하려면 모든 멤버십 또는 기능을 등록 해제하거나 중지해야 합니다.

  • 현재 등록된 클러스터를 보려면 Fleet 구성원 보기의 안내를 따르세요.

  • 프로젝트의 모든 활성 Fleet 수준의 기능을 확인하려면 다음 안내를 따르세요.

gcloud 및 cURL

$ curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://gkehub.googleapis.com/v1alpha1/projects/PROJECT_NAME/locations/global/features

여기서 PROJECT_NAME은 Fleet API를 사용 중지하려는 프로젝트의 이름입니다.

콘솔

프로젝트에 GKE Enterprise가 사용 설정된 경우 Google Cloud 콘솔에서 기능 개요 페이지를 방문합니다. 사용 설정됨으로 표시된 기능은 활성 Fleet 수준의 기능입니다.

해결 방법

먼저 프로젝트 Fleet에 등록된 클러스터를 등록 해제합니다. 일부 기능을 사용 중지하려면 먼저 모든 클러스터를 등록 해제해야 합니다.

이 작업을 완료한 후 모든 Fleet 수준 기능을 사용 중지합니다. 현재 이 작업은 Fleet REST API에서만 가능합니다.

  1. 프로젝트에 사용 설정된 Fleet 수준 기능 사용 중지

    $ gcloud alpha container hub FEATURE_COMMAND disable
    
  2. 기본적으로 사용 설정되는 기능 승인자 및 측정을 사용 중지합니다.

    $ curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -X "DELETE" \
        https://gkehub.googleapis.com/v1alpha1/projects/PROJECT_NAME/locations/global/features/FEATURE
    

    여기서 FEATURE는 사용 중지할 기능의 이름입니다(예: authorizer 또는 metering).

클러스터 등록 시 클러스터 권한 누락

증상

사용자 계정 또는 Google Cloud 서비스 계정으로 클러스터를 등록하려고 하면 다음과 유사한 오류가 발생할 수 있습니다.

ERROR: (gcloud.container.hub.memberships.register) ResponseError: code=403, message=Required "container.clusters.get" permission(s) for "projects/my-project/zones/zone-a/clusters/my-cluster"
가능한 원인

클러스터를 등록하려는 계정에 클러스터의 필수 cluster-admin 역할 기반 액세스 제어(RBAC) 역할이 없습니다.

해결 방법:

클러스터를 등록하기 전에 cluster-admin RBAC 역할을 계정에 부여합니다.

클러스터를 등록할 때 Failed to check if the user is a cluster-admin: Unable to connect to the server 오류

증상

클러스터에 등록하는 동안 다음과 비슷한 오류가 표시될 수 있습니다.

ERROR: (gcloud.container.hub.memberships.register) Failed to check if the user is a cluster-admin: Unable to connect to the server: net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers)

또는

ERROR: (gcloud.container.hub.memberships.register) Failed to check if the user is a cluster-admin: Unable to connect to the server: dial tcp MASTER_ENDPOINT_IP:443: i/o timeout
가능한 원인

등록 gcloud 명령어를 실행하는 머신은 클러스터의 외부 엔드포인트에 연결될 수 없습니다. 이는 일반적으로 외부 액세스/IP가 중지된 비공개 클러스터가 있지만 머신의 외부 IP 주소가 허용 목록에 없는 경우에 발생합니다. gcloud 407.0.0 이후에는 GKE 클러스터 등록 시 이 요구사항이 적용되지 않습니다.

해결 방법:

gcloud 등록 명령어를 실행하려는 머신이 클러스터의 API 서버에 액세스할 수 있는지 확인합니다. 클러스터에 외부 액세스가 사용 설정되지 않았으면 Google Cloud 지원팀에 케이스를 제출합니다.

추가 도움 받기

다음 단계를 수행하여 GKE Enterprise에 대한 Google Cloud 지원으로 티켓을 제출할 수 있습니다.

  1. Google Cloud 지원팀에 케이스를 제출합니다.
  2. Connect Agent 로그 수집의 안내에 따라 Connect 로그를 저장합니다.
  3. 케이스에 Connect Agent 로그를 첨부합니다.