Fleet 수준 설정 문제 해결

이 문서에서는 GKE Identity Service의 Fleet 수준 설정 문제를 해결하는 방법을 안내합니다.

Fleet 수준 설정 문제 해결

Fleet을 설정하는 동안에 발생할 수 있는 문제를 해결하려면 다음 안내를 따르세요.

1. GKE Identity Service가 사용 설정되어 있는지 확인하기

프로젝트에 GKE Identity Service가 사용 설정되어 있는지 확인하려면 다음 명령어를 실행합니다.

$ gcloud container fleet identity-service describe

오류가 표시되지 않으면 GKE Identity Service가 사용 설정된 것이므로 다음 안내에 따라 계속 진행할 수 있습니다.

오류: Identity Service Feature for project <your-project-id> is not enabled

이 오류가 보이면 기능을 설정할 때 GKE Identity Service가 Fleet에 맞게 올바르게 사용 설정되지 않은 것입니다.

해결책: 프로젝트에 이 기능이 사용 설정되어 있는지 확인하려면 GKE Identity Service용 클러스터 구성의 안내를 참조하세요.

2. GKE Identity Service 상태 보기

GKE ID 서비스의 현재 상태를 보려면 다음 명령어를 실행합니다.

$ gcloud container fleet identity-service describe

이 명령어의 출력에는 다음 두 가지 섹션이 포함됩니다.

  • membershipSpecs에는 Fleet에 등록된 각 클러스터에 대해 사용자가 지정한 ID 공급업체 구성이 포함됩니다. GKE Identity Service는 이러한 구성을 사용하여 각 클러스터에 구성됩니다.

  • membershipStates에는 관련 ID 공급업체 구성 및 설정 중에 발생할 수 있는 오류를 포함하여 각 클러스터의 GKE Identity Service의 현재 상태가 표시됩니다.

클러스터 문제를 해결하려면 membershipStates에서 클러스터를 검색하고 다음 필드를 찾습니다.

  • state 필드: membershipStates -> <cluster-identifier> -> identityservice -> state
  • failureReason 필드: membershipStates -> <cluster-identifier> -> identityservice -> failureReason.

예시

클러스터 2개(helloworld 및 foobar)가 Fleet에 등록된 경우 출력 구조는 다음과 같습니다.

Identity Service Feature:
  createTime: '222-11-10T23:05:6.146566392Z'
  membershipSpecs:
    projects/<your-project-number>/locations/<location>/memberships/helloworld:
      identityservice:
        authMethods:
        - name: oidc
          oidcConfig:
            clientId: id
            issuerUri: https://accounts.google.com
            ... other fields
    projects/<your-project-number>/locations/<location>/memberships/foobar:
      identityservice:
        authMethods:
        - name: oidc
          oidcConfig:
            clientId: id
            issuerUri: https://accounts.google.com
            ... other fields
  membershipStates:
    projects/<your-project-number>/location/<location>/memberships/helloworld:
      identityservice:
        failureReason: AIS feature does not support this cluster type
        memberConfig:
          authMethods:
          - name: oidc
            oidcConfig:
              clientId: id
              issuerUri: https://accounts.google.com
              ... other fields
        state: ERROR
      state:
        code: OK
        updateTime: '2022-11-11T20:39:59.556176650Z'
    projects/<your-project-number>/location/<location>/memberships/foobar:
      identityservice:
        memberConfig:
          authMethods:
          - name: oidc
            oidcConfig:
              clientId: id
              issuerUri: https://accounts.google.com
              ... other fields
        state: OK
      state:
        code: OK
        updateTime: '2022-11-11T20:39:59.556176650Z'

  name: projects/<project-number>/locations/global/features/identityservice
  updateTime: '2022-11-11T20:40:31.859321901Z'

3. 클러스터 상태 확인하기

클러스터에서 GKE Identity Service 상태를 확인하려면 다음을 확인하세요.

  • state 값이 OK인 경우: membershipSpecs에 지정된 구성으로 클러스터에 GKE Identity Service를 구성할 때 오류가 발생하지 않았음을 나타냅니다.

    문제를 해결 중인 클러스터에 대한 구성(예: helloworld)이 membershipSpecs와 membershipStates에서 다른 경우 클러스터 구성을 업데이트했을 가능성이 높습니다. GKE Identity Service가 클러스터에 변경사항을 전파할 때까지 몇 분 정도 기다린 후 다시 상태를 확인합니다.

    문제를 해결해야 하는 대상 클러스터의 구성(예: helloworld)이 membershipSpecs 및 membershipStates에서와 동일하면 GKE Identity Service가 올바르게 구성된 것입니다.

  • state 필드가 ERROR인 경우: membershipSpecs에 지정된 구성으로 클러스터에 GKE Identity Service를 구성할 때 오류가 발생했음을 나타냅니다.

    이 문제를 해결하려면 일반적인 문제 해결을 참고하세요. 필요한 문제 해결 단계를 수행한 후 몇 분 동안 기다린 후 다시 상태를 확인합니다.

일반적인 문제 해결

GKE Identity Service API가 사용 설정되지 않음

이 문제는 GKE Identity Service API가 사용 설정되지 않은 경우에 발생합니다.

오류 메시지

anthosidentityservice.googleapis.com is not enabled

해결책

API를 사용 설정하려면 다음 명령어를 실행하세요.

$ gcloud services enable anthosidentityservice.googleapis.com

지원되지 않는 클러스터 유형

이 문제는 지원되지 않는 클러스터 유형을 사용할 때 발생합니다.

오류 메시지

GKE Identity Service feature does not support this cluster type

해결책

지원되는 클러스터 유형에 대한 자세한 내용은 클러스터 유형을 참조하거나 Google Cloud 지원팀에 새 클러스터 유형 요청을 문의하세요.

구성에서 지원되지 않는 프로토콜이 발견됨

이 문제는 클러스터에 적용한 ID 구성에 지원되지 않는 프로토콜이 포함된 경우에 발생합니다.

오류 메시지

unsupported protocol found in configuration, aborting reconciliation.

해결책

GKE Identity Service의 Fleet 수준 설정은 다음을 지원합니다.

위에서 지원되는 프로토콜만 포함되도록 클러스터의 구성을 업데이트합니다. 구성을 수정하려면 다음 명령어를 실행합니다.

kubectl --kubeconfig CLUSTER_KUBECONFIG -n kube-public edit clientconfig default

CLUSTER_KUBECONFIG를 클러스터의 kubeconfig 파일 경로로 바꾸세요. kubeconfig에 여러 컨텍스트가 있으면 현재 컨텍스트가 사용됩니다. 명령어를 사용하기 전 현재 컨텍스트를 올바른 클러스터로 재설정해야 할 수 있습니다.

클러스터에 ID 구성이 없음

이 문제는 클러스터에 적용된 구성이 없으면 발생합니다.

오류 메시지

Authentication configuration is not present for this membership

해결책

클러스터 구성의 안내에 따라 ID 구성을 클러스터에 적용합니다.

GKE 허브 관리자 IAM 권한 누락

이 문제는 사용 중인 프로젝트에 gkehub.admin 역할이 없으면 발생합니다.

오류 메시지

PERMISSION_DENIED: Permission 'gkehub.memberships.list' denied on '`projects//locations//memberships`'
PERMISSION_DENIED: Permission 'gkehub.features.get' denied on '`projects//locations/global/features/identityservice`'
PERMISSION_DENIED: Permission 'gkehub.features.delete' denied on '`projects//locations/global/features/identityservice`'
PERMISSION_DENIED: Permission 'gkehub.features.create' denied on '`projects//locations/global/features/identityservice`'

해결책

ID가 project_id인 프로젝트 소유자는 다음 명령어를 실행해야 합니다.

gcloud projects add-iam-policy-binding project_id --member=user:USER_ID --role=roles/gkehub.admin

USER_ID를 Google 계정으로 바꿉니다.

ID 구성에 있는 고유하지 않은 ID 공급업체

이 문제는 클러스터의 GKE Identity Service 구성에서 여러 ID 공급업체에 대해 동일한 name 값이 있는 경우에 발생합니다.

오류 메시지

Configuration contains multiple identity providers with the same name

해결책

구성에서 중복 항목을 삭제하거나 중복 항목 이름을 바꿉니다.

ID 구성에 google 유형 제공업체가 여러 개 있음

이 문제는 ClientConfig가 google 유형의 구성 여러 개로 구성된 경우에 발생합니다.

오류 메시지

configuration contains multiple identity providers of type 'google'

해결책

구성의 spec/authentication 섹션에는 google 유형의 구성이 최대 1개 포함될 수 있습니다.

클러스터에 google 유형 구성이 두 개 이상 포함되지 않도록 클러스터의 구성을 업데이트합니다. 구성을 수정하려면 다음 명령어를 실행합니다.

kubectl --kubeconfig CLUSTER_KUBECONFIG -n kube-public edit clientconfig default

CLUSTER_KUBECONFIG를 클러스터의 kubeconfig 파일 경로로 바꾸세요. kubeconfig에 여러 컨텍스트가 있으면 현재 컨텍스트가 사용됩니다. 명령어를 사용하기 전 현재 컨텍스트를 올바른 클러스터로 재설정해야 할 수 있습니다.

ClientConfig의 커스텀 리소스 정의를 가져오는 중에 오류 발생

이 문제는 클러스터에서 ClientConfig의 커스텀 리소스 정의를 가져오는 중에 오류가 있으면 발생합니다.

오류 메시지

error fetching the ClientConfig's Custom Resource Definition: ERROR_REASON

해결책

ERROR_REASON에 표시된 세부정보를 사용하여 이 문제를 해결합니다.

GKE Identity Service ClientConfig를 업데이트하는 중에 오류 발생

이 문제는 클러스터에서 ClientConfig를 업데이트하는 도중 오류가 있으면 발생합니다.

오류 메시지

Error updating AIS ClientConfig: ERROR_REASON

해결책

ERROR_REASON>에 표시된 세부정보를 사용하여 이 문제를 해결합니다.

클러스터에 ClientConfig가 없음

이 문제는 GKE Identity Service를 설치할 때 만들어야 하는 ClientConfig가 클러스터에 없을 때 발생합니다. ClientConfig가 누락된 경우 GKE Identity Service가 클러스터에 올바르게 설치되지 않았음을 나타냅니다.

오류 메시지

ClientConfig CR not present, expected to be created when AIS was installed

해결책

클러스터의 GKE Identity Service 리소스가 실수로 삭제되었을 수 있습니다. 이 경우 새 클러스터를 만들어 볼 수 있습니다. 새 클러스터에 동일한 오류가 표시되면 클러스터 관리자 또는 Google Cloud 지원팀에 문의하세요.

GKE Identity Service 포드가 시작되지 않음

이 문제는 GKE Identity Service 포드가 pending 상태일 때 발생합니다.

오류 메시지

GKE Identity Service pod is not running (pending)

해결책

이 문제는 몇 분 후에 자동으로 해결되며 이후에 GKE Identity Service 포드가 running 상태로 전환됩니다.