문제해결

Connect Agent 로그 수집

Connect Agent는 클러스터를 Google에 연결하는 gke-connect-agent 배포입니다. 일반적으로 네임스페이스 gke-connect의 클러스터에 설치됩니다. 이 Connect Agent의 로그를 수집하면 문제해결에 유용할 수 있습니다.

다음 명령어를 실행하면 에이전트의 로그를 검색할 수 있습니다.

for ns in $(kubectl get ns -o jsonpath={.items..metadata.name} -l hub.gke.io/project); do
  echo "======= Logs $ns ======="
  kubectl logs -n $ns -l app=gke-connect-agent
done

프로젝트 클러스터에서 실행 중인 모든 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

오류 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 Console의 서비스 계정 세부정보 페이지에서 '키 만료 날짜'를 확인하세요. 경우에 따라 프로젝트/조직에 기본적으로 서비스 계정의 수명이 짧을 수 있는 특수 정책이 있을 수 있습니다.

해결 방법

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

왜곡된 시스템 시계 오류

증상

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

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

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

해결 방법

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

Cloud Console에서 워크로드를 확인할 수 없음

증상

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 네트워킹 문제를 나타냅니다.

해결 방법

이 클러스터의 Pod 워크로드가 확인되고 포트 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 인스턴스).

해결 방법

T3 무제한을 사용 설정하거나 노드 풀에 더 많은 리소스가 포함된 인스턴스 유형을 사용합니다.

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

증상

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

ERROR: (gcloud.container.hub.memberships.register) failed to initialize Default Feature
"authorizer", the Hub service account may not have access to your project
가능한 원인

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

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

gcloud

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

gcloud projects get-iam-policy PROJECT_NAME

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

콘솔

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

해결 방법

허브 서비스 에이전트 역할 결합을 삭제했으면 다음 명령어를 실행하여 역할 결합을 복원합니다.

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

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

증상

허브 프로젝트와 다른 프로젝트에서 GKE 클러스터를 등록할 때 다음과 유사한 오류가 발생할 수 있습니다.

ERROR: (gcloud.container.hub.memberships.register) hub default service account
does not have access to the GKE cluster project for //container.googleapis.com/v1/projects/my-project/zones/zone-a/clusters/my-cluster
가능한 원인

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

해결 방법

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

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

증상

Hub 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 수준의 기능을 확인하려면 다음 안내를 따르세요.

gcloud 및 cURL

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

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

Cloud Console

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

해결 방법

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

이 작업을 완료한 후 모든 Fleet 수준 기능을 사용 중지합니다. 현재 이 작업은 Hub 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 역할을 계정에 부여합니다.

추가 도움 받기

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

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