OIDC로 GKE Identity Service용 클러스터 설정

이 문서는 개발자와 기타 사용자가 OpenID Connect(OIDC) 공급업체의 기존 ID 세부정보를 사용하여 클러스터에 로그인할 수 있도록 개별 클러스터에 GKE Identity Service를 설정하려는 클러스터 관리자 또는 애플리케이션 운영자를 대상으로 합니다.

기본 요건

  • 클러스터는 AWS 또는 Azure에 있는 GKE 클러스터 온프레미스(VMware 또는 베어메탈)여야 합니다. 연결된 클러스터 또는 GKE 클러스터에는 클러스터별 OIDC 구성이 지원되지 않습니다.
  • Google Cloud 콘솔을 통해 인증하려면 OIDC 인증을 위해 구성하려는 각 클러스터가 프로젝트 Fleet에 등록되어야 합니다.

시작하기 전에

  • 설정을 시작하기 전에 플랫폼 관리자가 GKE Identity Service를 공급업체에 등록하는 데 필요한 모든 정보(GKE Identity Service의 클라이언트 ID 및 보안 비밀 포함)를 제공했는지 확인하세요.

  • 다음 명령줄 도구가 설치되었는지 확인합니다.

    • 최신 버전의 Google Cloud CLI(Google Cloud와의 상호작용을 위한 명령줄 도구인 gcloud 포함). Google Cloud CLI를 설치해야 하는 경우 설치 가이드를 참조하세요.
    • Kubernetes 클러스터에 명령어를 실행하기 위한 kubectl. kubectl을 설치해야 하는 경우 이 안내를 따르세요.

    Google Cloud와의 상호작용을 위해 Cloud Shell을 셸 환경으로 사용하는 경우 이러한 도구가 자동으로 설치됩니다.

  • 클러스터가 등록된 프로젝트에서 사용할 수 있도록 gcloud CLI를 초기화했는지 확인합니다.

  • 배스천 호스트를 통해 현재 VPC 외부에 있는 AWS 또는 Azure GKE 클러스터의 제어 영역에 연결해야 하는 경우 이 설정 전에 배스천 호스트를 만들었고 포트 8118에서 SSH 터널을 시작했는지 확인합니다. 그런 다음 HTTPS_PROXY=http://localhost:8118로 이 가이드를 따를 때 kubectl 명령어를 추가합니다. SSH 터널을 시작할 때 다른 포트를 사용한 경우 8118을 선택된 포트로 바꿉니다.

클러스터 구성

선택한 공급업체를 사용하도록 클러스터를 구성하려면 GKE Identity Service에서 ID 공급업체에 대한 세부정보, 사용자 ID를 위해 제공하는 JWT 토큰의 정보, 클라이언트 애플리케이션으로 GKE Identity Service를 등록할 때 제공하는 기타 정보를 지정해야 합니다.

예를 들어 제공업체가 다른 필드로 ID 토큰을 만드는 경우, iss는 ID 공급업체 URI이고 sub는 사용자를 식별하며 groupList는 사용자가 속한 그룹을 나열합니다.

{
  'iss': 'https://server.example.com'
  'sub': 'u98523-4509823'
  'groupList': ['developers@example.corp', 'us-east1-cluster-admins@example.corp']
  ...
}

구성에는 다음과 같은 해당 필드가 있습니다.

issuerURI: 'https://server.example.com'
userClaim: 'sub'
groupsClaim: 'groupList'
...

플랫폼 관리자나 조직에서 ID를 관리하는 사람이 구성을 만드는 데 필요한 대부분의 정보를 제공해야 합니다.

GKE Identity Service는 클러스터 구성에 ClientConfig라는 Kubernetes 커스텀 리소스 유형(CRD)을 사용합니다. 여기에는 GKE Identity Service가 ID 공급업체와 상호작용하는 데 필요한 모든 정보 필드가 있습니다. 각 GKE 클러스터에는 아래 안내에 따라 구성 세부정보로 업데이트하는 kube-public 네임스페이스에 default라는 ClientConfig 리소스가 있습니다.

제공업체별 구성에서 많이 사용되는 공급업체의 구체적인 구성 예시를 확인할 수 있습니다.

kubectl

기본 ClientConfig를 수정하려면 kubectl을 통해 클러스터에 연결할 수 있는지 확인하고 다음 명령어를 실행합니다.

kubectl --kubeconfig=KUBECONFIG_PATH edit ClientConfigs default -n kube-public

KUBECONFIG_PATH를 클러스터의 kubeconfig 파일 경로로 바꿉니다(예: $HOME/.kube/config).

텍스트 편집기가 클러스터의 ClientConfig 리소스를 로드합니다. 아래와 같이 spec.authentication.oidc 객체를 추가합니다. 이미 작성된 기본 데이터를 수정하지 마세요.

apiVersion: authentication.gke.io/v2alpha1
kind: ClientConfig
metadata:
  name: default
  namespace: kube-public
spec:
  authentication:
  - name: NAME
    oidc:
      certificateAuthorityData: CERTIFICATE_STRING
      clientID: CLIENT_ID
      clientSecret: CLIENT_SECRET
      deployCloudConsoleProxy: PROXY_BOOLEAN
      extraParams: EXTRA_PARAMS
      groupsClaim: GROUPS_CLAIM
      groupPrefix: GROUP_PREFIX
      issuerURI: ISSUER_URI
      kubectlRedirectURI: KUBECTL_REDIRECT_URI
      scopes: SCOPES
      userClaim: USER_CLAIM
      userPrefix: USER_PREFIX
      enableAccessToken: ENABLE_ACCESS_TOKEN
    proxy: PROXY_URL

# Rest of the resource is managed by Google. DO NOT MODIFY.
...

다음 표는 ClientConfig oidc 객체의 필드를 설명합니다. 대부분의 필드는 선택사항입니다. 추가해야 하는 필드는 ID 공급업체와 GKE Identity Service 공급업체를 구성할 때 플랫폼 관리자가 선택한 설정 옵션에 따라 다릅니다.

필드 필수 설명 형식
name 예 이 구성을 식별하는 데 사용할 이름입니다(일반적으로 ID 공급업체 이름). 구성 이름은 문자로 시작해야 합니다. 이어서 최대 39자(영문 기준)의 소문자, 숫자 또는 하이픈이 와야 하며 하이픈으로 끝나서는 안 됩니다 문자열
certificateAuthorityData 아니요 플랫폼 관리자가 제공한 경우 ID 공급업체의 PEM 인코딩 인증서 문자열입니다. certificateAuthorityData에 결과 문자열을 단일 줄로 포함합니다. 문자열
clientID 예 ODIC 공급업체에 GKE Identity Service를 등록할 때 반환되는 클라이언트 ID입니다. 문자열
clientSecret 아니요 OIDC 클라이언트 애플리케이션과 OIDC 제공업체 간에 공유된 보안 비밀입니다. 문자열
deployCloudConsoleProxy 아니요 Google Cloud 콘솔이 인터넷을 통해 공개적으로 액세스할 수 없는 온프레미스 ID 공급업체에 연결할 수 있게 해주는 프록시가 배포되었는지 여부를 지정합니다. 기본적으로 false로 설정됩니다. 불리언
extraParams 아니요 쉼표로 구분된 목록으로 지정된 ID 공급업체에 전송할 추가 키-값 매개변수입니다(예: `prompt=consent,access_type=offline`). 쉼표로 구분된 목록
groupsClaim 아니요 제공업체가 계정의 보안 그룹을 반환하기 위해 사용하는 JWT 클레임(필드 이름)입니다. 문자열
groupPrefix 아니요 여러 ID 공급업체(일반적으로 제공업체 이름)에 대한 구성이 있는 경우 액세스 제어 규칙의 기존 이름과 충돌하지 않도록 보안 그룹 이름 앞에 추가하려는 프리픽스입니다. 문자열
issuerURI 예 ID 공급업체에 승인 요청이 수행된 URI입니다. URI는 HTTPS를 사용해야 하며 후행 슬래시로 끝나서는 안 됩니다. URL 문자열
kubectlRedirectURI 예리디렉션 URI: gcloud CLI에서 사용하고 플랫폼 관리자가 등록할 때 지정하는 리디렉션 URL 및 포트로, 일반적으로 http://localhost:PORT/callback 형식입니다. URL 문자열
scopes 예 OpenID 제공업체에 전송할 추가적인 범위입니다. 예를 들어 Microsoft Azure와 Okta에는 offline_access 범위가 필요합니다. 쉼표로 구분된 목록
userClaim 아니요 제공업체가 사용자 계정을 식별하는 데 사용하는 JWT 클레임(필드 이름)입니다. 여기에서 값을 지정하지 않으면 GKE ID 서비스는 다수의 공급업체에서 사용하는 사용자 ID 클레임인 '하위'를 사용합니다. OpenID 제공업체에 따라 '이메일' 또는 '이름'과 같은 다른 클레임을 선택할 수 있습니다. 'email' 이외의 클레임은 이름 충돌을 방지하기 위해 발급기관 URL이 프리픽스로 추가됩니다. 문자열
userPrefix 아니요 기본 프리픽스를 사용하지 않으려는 경우 기존 이름과 충돌을 방지하기 위해 사용자 클레임 앞에 추가되는 프리픽스입니다. 문자열
enableAccessToken 아니요 사용 설정된 경우 GKE Identity Service는 사용자가 명령줄에서 로그인할 때 ID 공급업체의 사용자 정보 엔드포인트를 사용하여 그룹 정보를 가져올 수 있습니다. 이렇게 하면 이 엔드포인트에서 그룹 클레임을 제공하는 제공업체(예: Okta)가 있을 때 승인을 위해 보안 그룹을 사용할 수 있습니다. 설정하지 않은 경우 false로 간주됩니다. 불리언
proxy 아니요 해당되는 경우 ID 공급업체에 연결하는 데 사용할 프록시 서버 주소입니다. 예를 들어 클러스터가 비공개 네트워크에 있고 공개 ID 공급업체에 연결해야 하는 경우 이를 설정해야 할 수 있습니다. 예를 들면 http://user:password@10.10.10.10:8888입니다. 문자열

ClientConfig를 완료한 후 파일을 저장합니다. 그러면 클러스터의 ClientConfig가 업데이트됩니다. 구문 오류가 발생하면 구성을 다시 수정하여 해결하라는 메시지가 표시됩니다.

제공업체별 구성

이 섹션에서는 몇 가지 많이 사용되는 OIDC 제공업체의 구성 안내를 제공하며, 여기에는 자체 세부정보로 복사하고 수정할 수 있는 구성 예시가 포함됩니다.

Azure AD

이는 Azure AD로 GKE Identity Service를 설정하는 기본 구성입니다. 이 구성을 사용하면 GKE Identity Service가 Azure AD에서 사용자 및 그룹 멤버십 정보를 가져올 수 있고 관리자나 운영자는 그룹을 기준으로 Kubernetes 역할 기반 액세스 제어(RBAC)를 설정할 수 있습니다. 그러나 이 구성을 사용하면 사용자당 약 200개 그룹을 검색하도록 제한됩니다.

사용자당 그룹을 200개 넘게 검색해야 할 경우에는 Azure AD(고급) 안내를 참조하세요.

...
spec:
  authentication:
  - name: oidc-azuread
    oidc:
      clientID: CLIENT_ID
      clientSecret: CLIENT_SECRET
      cloudConsoleRedirectURI: https://console.cloud.google.com/kubernetes/oidc
      extraParams: prompt=consent, access_type=offline
      issuerURI: https://login.microsoftonline.com/TENANT_ID/v2.0
      kubectlRedirectURI: http://localhost:PORT/callback
      scopes: openid,email,offline_access
      userClaim: email

# Rest of the resource is managed by Google. DO NOT MODIFY.
...

다음을 바꿉니다.

  • CLIENT_ID: 공급업체에 GKE Identity Service를 등록할 때 반환되는 클라이언트 ID입니다.
  • CLIENT_SECRET: OIDC 클라이언트 애플리케이션과 OIDC 제공업체 간에 공유된 보안 비밀입니다.
  • TENANT: 인증할 Azure AD 계정의 종류입니다. 지원되는 값은 테넌트 ID 또는 특정 테넌트에 속한 계정의 테넌트 이름입니다. 테넌트 이름은 기본 도메인이라고도 합니다. 이러한 값을 찾는 방법에 대한 자세한 내용은 Microsoft Azure AD 테넌트 ID 및 기본 도메인 이름 찾기를 참조하세요.
  • PORT: gcloud CLI에서 사용하는 리디렉션 URL에 대해 선택된 포트 번호이며 등록 시 플랫폼 관리자가 지정합니다.

Azure AD(고급)

이 선택적인 Azure AD 구성을 사용하면 GKE ID 서비스에서 Microsoft Graph API를 사용하여 사용자당 그룹 수에 대한 제한 없이 사용자 및 그룹 정보를 검색할 수 있습니다.

이 구성을 지원하는 플랫폼에 대한 자세한 내용은 Azure AD 고급 설정을 참조하세요.

사용자당 그룹을 200개 미만으로 검색해야 할 경우에는 ClientConfig에서 oidc 앵커를 사용하는 기본 구성을 사용하는 것이 좋습니다. 자세한 내용은 Azure AD 안내를 참조하세요.

다음 구성 예시의 모든 필드가 필수입니다.

...
spec:
  authentication:
  - name: NAME
    proxy: PROXY_URL
    azureAD:
      clientID: CLIENT_ID
      clientSecret: CLIENT_SECRET
      tenant: TENANT_ID
      kubectlRedirectURI: http://localhost:PORT/callback
      groupFormat: GROUP_FORMAT
      userClaim: USER_CLAIM

# Rest of the resource is managed by Google. DO NOT MODIFY.
...

다음을 바꿉니다.

  • NAME: 이 구성을 식별하는 데 사용할 이름입니다(일반적으로 ID 공급업체 이름). 구성 이름은 문자로 시작해야 합니다. 이어서 최대 39자(영문 기준)의 소문자, 숫자 또는 하이픈이 와야 하며 하이픈으로 끝나서는 안 됩니다
  • PROXY_URL: 해당되는 경우 ID 공급업체에 연결하는 데 사용할 프록시 서버 주소입니다. 예를 들어 클러스터가 비공개 네트워크에 있고 공개 ID 공급업체에 연결해야 하는 경우 이를 설정해야 할 수 있습니다. 예를 들면 http://user:password@10.10.10.10:8888입니다.
  • CLIENT_ID: 공급업체에 GKE Identity Service를 등록할 때 반환되는 클라이언트 ID입니다.
  • CLIENT_SECRET: OIDC 클라이언트 애플리케이션과 OIDC 제공업체 간에 공유된 보안 비밀입니다.
  • TENANT: 인증할 Azure AD 계정의 종류입니다. 지원되는 값은 테넌트 ID 또는 특정 테넌트에 속한 계정의 테넌트 이름입니다. 테넌트 이름은 기본 도메인이라고도 합니다. 이러한 값을 찾는 방법에 대한 자세한 내용은 Microsoft Azure AD 테넌트 ID 및 기본 도메인 이름 찾기를 참조하세요.
  • PORT: gcloud CLI에서 사용하는 리디렉션 URL에 대해 선택된 포트 번호이며 등록 시 플랫폼 관리자가 지정합니다.
  • GROUP_FORMAT: 그룹 정보를 검색하려는 형식입니다. 이 필드에는 사용자 그룹의 ID 또는 NAME에 해당하는 값을 사용할 수 있습니다. 이 설정은 현재 베어메탈 Google Distributed Cloud 배포의 클러스터에만 사용할 수 있습니다.
  • USER_CLAIM(선택사항): 제공업체가 계정을 식별하는 데 사용하는 JWT 클레임(필드 이름)입니다. 여기에 값을 지정하지 않으면 GKE Identity Service가 'email', 'preferred_username' 또는 'sub' 순으로 값을 사용해 사용자 세부정보를 가져옵니다. 이 속성은 GKE Enterprise 버전 1.28에서 사용할 수 있습니다.

Okta

다음은 Okta를 ID 공급업체로 사용해서 사용자와 그룹을 모두 사용하여 인증을 설정하는 방법을 보여줍니다. 이 구성을 사용하면 Anthos Identity Service가 액세스 토큰 및 Okta의 사용자 정보 엔드포인트를 사용하여 사용자 및 그룹 클레임을 검색할 수 있습니다.

...
spec:
  authentication:
  - name: okta
    oidc:
      clientID: CLIENT_ID
      clientSecret: CLIENT_SECRET
      cloudConsoleRedirectURI: https://console.cloud.google.com/kubernetes/oidc
      enableAccessToken: true
      extraParams: prompt=consent
      groupsClaim: groups
      issuerURI: https://OKTA_ISSUER_URI/
      kubectlRedirectURI: http://localhost:PORT/callback
      scopes: offline_access,email,profile,groups
      userClaim: email

# Rest of the resource is managed by Google. DO NOT MODIFY.
...

그룹 액세스 한도

Okta 사용자의 경우 Anthos Identity Service가 연결된 그룹 이름의 길이가 170,000자 미만인 사용자에 대해 그룹 정보를 검색할 수 있습니다. 이것은 Okta 그룹 길이가 최대라고 가정할 때 약 650개 그룹의 멤버십에 해당합니다. 사용자가 너무 많은 그룹의 멤버이면 인증 호출이 실패합니다.

다음 단계

구성이 적용된 후 클러스터에 대한 사용자 액세스 설정하기