GKE Identity Service 진단 유틸리티

GKE Identity Service 진단 유틸리티는 FQDN 기반 인증 문제를 해결하는 데 도움이 됩니다. 특정 OIDC 제공업체를 사용하여 클러스터에 인증하는 데 문제가 있는 경우 이 도구를 사용 설정하고 OIDC 제공업체의 로그인 흐름을 시뮬레이션하여 구성 문제를 빠르게 식별할 수 있습니다.

진단 유틸리티는 GKE Enterprise 1.32 이상을 실행하는 개별 클러스터에서만 사용 가능하며 OIDC만 지원합니다.

진단 유틸리티 사용 설정

진단 유틸리티는 기본적으로 사용 중지되어 있으며 이를 사용하여 문제를 해결하려면 먼저 사용 설정해야 합니다. 사용 설정하려면 다음 안내를 따르세요.

  1. 수정할 ClientConfig 커스텀 리소스를 엽니다.

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

    매니페스트는 다음과 유사하게 표시됩니다.

    apiVersion: authentication.gke.io/v2alpha1
kind: ClientConfig
metadata:
  name: default
  namespace: kube-public
spec:
  authentication:
  - name: oidc
    oidc:
      clientID: example-client-id
      clientSecret: example-client-secret
      cloudConsoleRedirectURI: https://console.cloud.google.com/kubernetes/oidc
      extraParams: prompt=consent, access_type=offline
      issuerURI: https://example.com
      kubectlRedirectURI: http://localhost:PORT/callback
      scopes: openid,email,offline_access
      userClaim: email

  2. 다음 예시와 같이 identityServiceOptions 섹션을 ClientConfig 매니페스트에 추가하여 진단 유틸리티 구성을 지정합니다.

    apiVersion: authentication.gke.io/v2alpha1
  kind: ClientConfig
  metadata:
    name: default
    namespace: kube-public
  spec:
    identityServiceOptions:
      diagnosticInterface:
        enabled: true
        expirationTime: TIMESTAMP
    authentication:
    - name: oidc
      oidc:
        clientID: example-client-id
        clientSecret: example-client-secret
        cloudConsoleRedirectURI: https://console.cloud.google.com/kubernetes/oidc
        extraParams: prompt=consent, access_type=offline
        issuerURI: https://example.com
        kubectlRedirectURI: http://localhost:PORT/callback
        scopes: openid,email,offline_access
        userClaim: email

    TIMESTAMP를 RFC 3339 형식의 만료 시간으로 바꿉니다. 예를 들면 2025-05-01T17:05:00Z입니다. 만료 시간은 진단 유틸리티 기능이 자동으로 사용 중지되는 시점을 결정합니다. 클러스터 액세스 권한이 있는 모든 사용자가 진단 유틸리티를 사용할 수 있으므로 만료 시간을 적절하게 설정하면 유틸리티가 필요 이상으로 사용 설정되지 않도록 할 수 있습니다. 만료 시간을 설정할 때는 향후 어느 시간으로 설정해도 괜찮지만 향후 12시간으로 설정하는 것이 좋습니다.

  3. 변경사항을 저장하고 텍스트 편집기를 종료하여 매니페스트를 클러스터에 적용합니다.

진단 유틸리티를 사용하여 로그인 시뮬레이션

진단 유틸리티를 사용 설정하면 로그인 이벤트를 시뮬레이션하고 특정 제공업체의 문제를 해결하는 데 사용할 수 있는 상응하는 진단 정보를 가져올 수 있습니다.

  1. 다음 URL로 이동하여 브라우저에서 진단 페이지를 엽니다.

    APISERVER-URL/diagnose

    APISERVER_URL을 클러스터의 정규화된 도메인 이름(FQDN)으로 바꿉니다. 예를 들면 https://apiserver.example.com입니다.

    진단 페이지에는 클러스터에 구성된 OIDC 제공업체 목록이 표시됩니다.

  2. 문제를 해결할 제공업체를 선택합니다.

  3. 평소대로 로그인합니다.

    로그인 프로세스가 종료되면 유틸리티에 문제 해결에 도움이 되는 진단 정보가 포함된 페이지가 표시됩니다.

진단 페이지를 사용하여 로그인 문제 해결

진단 페이지에는 인증 요약이 제공되며 이 요약은 다음 세 섹션으로 나뉩니다.

  • 상태: 인증 성공 여부에 따라 Success 또는 Failed가 포함됩니다.

  • ID 공급업체: 로그인하는 데 사용된 제공업체에 대한 세부정보(예: Name, Client ID, UserClaim)가 포함됩니다.

  • ID 토큰: 지정된 제공업체를 사용하는 GKE Identity Service에서 가져온 ID 토큰에 대한 정보가 포함됩니다. ID 토큰은 키-값 쌍 집합을 포함하는 JSON 객체입니다. 키에는 iss, aud, sub, email이 포함될 수 있습니다.

인증 성공 문제 해결

상태 섹션 콘텐츠에는 인증이 성공했다고 표시되지만 여전히 문제가 발생하는 경우 이는 역할 기반 액세스 제어(RBAC)가 누락되었기 때문일 수 있습니다. 추가 문제 해결 정보는 그룹의 RBAC가 OIDC 제공업체에서 작동하지 않음을 참조하세요.

인증 실패 문제 해결

상태 섹션 콘텐츠에 인증 실패가 표시되면 먼저 ID 공급업체 섹션과 ID 토큰 섹션 간에 일치하지 않는 부분이 있는지 확인합니다.

다음은 확인해야 하는 몇 가지 인증 요구사항입니다.

  • ID 공급업체의 UserClaim 필드가 비어 있으면 ID 토큰 섹션에 sub 필드가 포함되어야 합니다. sub 필드가 없으면 이는 ID 토큰에 문제가 있음을 나타냅니다.

  • ID 공급업체의 UserClaim 필드 값이 ID 토큰 섹션의 키이어야 합니다. 예를 들어 UserClaim 필드가 email로 설정된 경우 ID 토큰에 email 필드가 있어야 합니다.

  • ID 공급업체의 GroupsClaim 필드 값이 ID 토큰의 키이어야 합니다. 예를 들어 GroupsClaim 필드가 groupsList로 설정된 경우(그룹을 지원하는 제공업체의 경우) ID 토큰에 groupsList 필드가 있어야 합니다.

  • ID 공급업체의 Client ID 필드 값이 ID 토큰 섹션의 aud 필드 값 내에 포함되어야 합니다.

위 조건 중 하나라도 충족되지 않는 경우 다음 가이드 중 하나를 참조하여 GKE Identity Service로 클러스터를 올바르게 구성하는 방법에 대한 자세한 내용을 알아보세요.

추가 문제 해결을 위해 로그 사용

GKE Identity Service 포드 로그에는 추가 디버깅 정보가 포함되어 있습니다. GKE Identity Service 포드 로그를 사용하려면 다음 안내를 따르세요.

  1. GKE Identity Service 디버그 로그 사용 설정

  2. GKE Identity Service 컨테이너 로그 확인