제3자 ID로 Connect 게이트웨이 설정

이 가이드는 Google ID가 없고 Google Workspace에 속하지 않는 사용자가 포함된 프로젝트에 Connect 게이트웨이를 설정해야 하는 플랫폼 관리자를 대상으로 작성되었습니다. 이 가이드에서는 이러한 ID를 '제3자 ID'라고 합니다. 이 가이드를 읽기 전에 Connect 게이트웨이 개요에 설명된 개념을 숙지해야 합니다. 개별 Google 계정을 승인하려면 Connect 게이트웨이 설정을 참조하세요. Google 그룹스 지원은 Google 그룹스를 사용하여 Connect 게이트웨이 설정을 참조하세요.

이 가이드의 설정을 사용하면 사용자가 Google Cloud CLI, Connect 게이트웨이, Google Cloud 콘솔을 사용하여 Fleet 클러스터에 로그인할 수 있습니다.

지원되는 클러스터 유형

Connect 게이트웨이를 통해 등록된 다음 클러스터 유형에 대해 제3자 ID로 액세스 제어를 설정할 수 있습니다.

GKE 클러스터
Anthos(GKE Enterprise) 1.13 이상의 VMware 및 베어메탈의 Google Distributed Cloud(소프트웨어만 해당)
Kubernetes 버전 1.25 이상의 AWS용 GKE 및 Azure용 GKE
Anthos(GKE Enterprise) 1.16 이상의 연결된 클러스터

이 기능을 사용하기 위해 온프레미스 클러스터를 업그레이드해야 하는 경우 VMWare용 GKE Enterprise 클러스터 업그레이드와 베어메탈용 GKE Enterprise 클러스터 업그레이드를 참조하세요.

위에 나열되지 않은 GKE 클러스터 환경에 대한 사용 사례가 있으면 Cloud Customer Care 또는 Connect 게이트웨이팀에 문의하세요.

작동 방식

개요에서 설명한 대로 사용자는 Google Workspace 또는 Cloud ID가 아닌 ID 공급업체를 사용하고 있을 수 있습니다. 사용자는 직원 ID 제휴를 사용해서 Okta 또는 Azure Active Directory와 같은 제3자 ID 공급업체를 사용하여 Connect 게이트웨이를 통해 클러스터에 액세스할 수 있습니다. Google 계정과 달리 제3자 사용자는 Identity and Access Management(IAM) 주 구성원으로 표시되며 다음 형식을 따릅니다.

principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subject/SUBJECT_VALUE

WORKFORCE_POOL_ID은 관련 제3자 ID 공급업체가 포함된 직원 풀의 이름입니다.
SUBJECT_VALUE는 Google 주체에 대한 서드 파티 ID의 매핑입니다.

제3자 그룹의 경우 IAM 주 구성원은 다음 형식을 따릅니다.

principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/group/GROUP_VALUE

다음 다이어그램은 이 서비스가 사용 설정된 클러스터를 인증하고 명령어를 실행하는 서드 파티 사용자의 일반적인 흐름을 보여줍니다. 이 흐름이 성공하려면 사용자 또는 그룹의 클러스터에 역할 기반 액세스 제어(RBAC) 정책이 적용되어야 합니다.

개별 사용자의 경우 사용자의 전체 IAM 주 구성원 이름을 사용하는 RBAC 정책이 클러스터에 있어야 합니다.

그룹 기능을 사용하는 경우 전체 IAM 주 구성원 이름을 사용하는 RBAC 정책이 다음과 같은 그룹의 클러스터에 있어야 합니다.

사용자 alice@example.com을 구성원으로 포함합니다.
Alice의 Google Cloud 조직에 있는 직원 풀 내의 ID 공급업체 매핑에 포함됩니다.

게이트웨이 제3자 ID 흐름을 보여주는 다이어그램

사용자 alice@example.com은 제3자 브라우저 기반 로그인을 사용하여 제3자 ID로 gcloud에 로그인합니다. 명령줄에서 클러스터를 사용하기 위해 사용자는 Connect 게이트웨이 사용에 설명된 대로 클러스터 게이트웨이 kubeconfig를 가져옵니다.
사용자는 kubectl 명령어를 실행하거나 Google Cloud 콘솔에서 Google Kubernetes Engine 워크로드 또는 객체 브라우저 페이지를 열어 요청을 보냅니다.
Connect 게이트웨이에서 이 요청을 수신하여 직원 ID 제휴를 통해 제3자 인증을 처리합니다.
Connect 게이트웨이는 IAM에서 승인 검사를 수행합니다.
Connect 서비스는 클러스터에서 실행 중인 Connect 에이전트로 요청을 전달합니다. 이 요청은 클러스터에서 인증과 승인에 사용할 사용자 인증 정보와 함께 제공됩니다.
Connect 에이전트는 Kubernetes API 서버에 요청을 전달합니다.
Kubernetes API 서버는 GKE Identity Service로 요청을 전달하여 요청의 유효성을 검사합니다.
GKE Identity Service는 Kubernetes API 서버에 제3자 사용자 및 그룹 정보를 반환합니다. 그러면 Kubernetes API 서버가 이 정보를 사용하여 클러스터에 구성된 RBAC 정책에 따라 요청을 승인할 수 있습니다.

시작하기 전에

다음 명령줄 도구가 설치되었는지 확인합니다.
- Google Cloud와 상호작용하는 명령줄 도구인 Google Cloud CLI 최신 버전
- 클러스터와의 상호작용을 위한 Kubernetes 명령줄 도구 kubectl
Google Cloud와의 상호작용을 위해 Cloud Shell을 셸 환경으로 사용하는 경우 이러한 도구가 자동으로 설치됩니다.
프로젝트에 사용할 수 있도록 gcloud CLI를 초기화했는지 확인합니다.
이 가이드에서는 프로젝트에 roles/owner가 있다고 가정합니다. 프로젝트 소유자가 아니라면 일부 설정 단계를 수행하기 위한 추가 권한이 필요할 수 있습니다.
Google Cloud 외부 클러스터의 경우 GKE Identity Service가 클러스터에서 Google API를 호출하여 인증을 완료해야 합니다. 네트워크 정책에 프록시를 통과하기 위해 아웃바운드 트래픽이 필요한지 확인합니다.

직원 ID를 사용하여 제3자 ID 속성 매핑 설정

각자 ID 공급업체에 해당하는 안내에 따라 Google Cloud 조직에 직원 풀 및 ID 공급업체가 설정되어 있는지 확인합니다.

API 사용 설정

프로젝트에 게이트웨이를 추가하려면 Connect 게이트웨이 API 및 필수 종속 항목 API를 사용 설정합니다. 사용자가 Google Cloud 콘솔을 사용하는 클러스터에만 인증하려는 경우 connectgateway.googleapis.com을 사용 설정할 필요는 없지만 나머지 API를 사용 설정해야 합니다.

gcloud services enable --project=PROJECT_ID  \
connectgateway.googleapis.com \
anthos.googleapis.com \
gkeconnect.googleapis.com \
gkehub.googleapis.com \
cloudresourcemanager.googleapis.com

GKE Identity Service 설정

Connect 게이트웨이의 제3자 ID 지원 기능은 GKE Identity Service를 사용하여 Google에서 그룹 멤버십 정보를 가져옵니다. GKE Identity Service에 대한 자세한 내용은 GKE Identity Service 소개를 참조하세요.

게이트웨이와 함께 GKE 클러스터를 사용하는 경우 제3자 ID 지원을 사용하기 위해 GKE Identity Service를 설정할 필요가 없습니다. 대신 RBAC용 Google 그룹스 구성의 안내를 따르고 IAM 역할 부여를 계속 진행하여 게이트웨이를 통해 클러스터에 대한 액세스 권한을 부여합니다.

게이트웨이와 함께 GKE 연결 클러스터를 사용하는 경우 제3자 지원에 GKE Identity Service가 필요하지 않습니다. 선택한 클러스터 유형에 대한 안내에 따라 제3자 ID 지원을 설정합니다.

GKE Identity Service가 설치되었는지 확인

GKE ID 서비스는 버전 1.7 이상의 GKE 클러스터에 기본으로 설치되지만, 제3자 ID 지원을 위해서는 버전 1.13 이상이 필요합니다. 다음 명령어를 실행하면 클러스터에 올바르게 설치되었는지 확인할 수 있습니다.

kubectl --kubeconfig CLUSTER_KUBECONFIG get all -n anthos-identity-service

CLUSTER_KUBECONFIG를 클러스터의 kubeconfig 경로로 바꿉니다.

그룹에 제3자 ID 지원 구성하기

클러스터 또는 Fleet이 Google 그룹스 지원에 이미 구성되어 있으면 추가 단계가 없으며 제3자 사용자 및 그룹에 IAM 역할 부여로 건너뛸 수 있습니다.

VMware 또는 베어메탈용 Google Distributed Cloud를 사용하는 경우 GKE Identity Service를 설정하는 방식에 따라 서드 파티 그룹 기능을 구성해야 하는 방법이 결정됩니다.

GKE Identity Service를 처음 사용하는 경우 Fleet API를 사용하여 제3자 그룹 지원을 구성하거나(권장) kubectl을 사용할 수 있습니다.

GKE Identity Service의 최초 사용자가 아닌 경우 다음 중 하나에 주의하세요.

이미 Fleet 수준에서 다른 ID 공급업체의 GKE Identity Service를 설정한 경우 제3자 그룹 기능이 기본적으로 사용 설정됩니다. 자세한 내용과 필요한 추가 설정은 아래 Fleet 섹션을 참조하세요.
클러스터별 기준으로 다른 ID 공급업체에 대해 이미 GKE Identity Service를 설정한 경우 제3자 그룹 기능의 구성을 업데이트하는 방법은 아래의 Kubectl 섹션을 참조하세요.

Fleet

Google Cloud 콘솔 또는 명령줄을 사용하여 Fleet Feature API를 사용하는 제3자 그룹에 대한 액세스를 구성할 수 있습니다.

콘솔

이전에 Fleet에 대해 GKE Identity Service를 설정하지 않았으면 GKE Identity Service를 위한 클러스터 구성의 안내를 따르세요.

클러스터 선택 및 구성 업데이트

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

기능 관리자로 이동
ID 서비스 패널에서 세부정보를 클릭합니다. 프로젝트의 클러스터 세부정보가 표시됩니다.
Identity Service 업데이트를 클릭하여 설정 창을 엽니다.
구성할 클러스터를 선택합니다. 개별 클러스터를 선택하거나 모든 클러스터를 동일한 ID 구성으로 구성하도록 지정할 수 있습니다.
ID 공급업체 구성 섹션에서 ID 공급업체를 유지, 추가, 업데이트 또는 삭제하도록 선택할 수 있습니다.
계속을 클릭하여 다음 구성 단계로 이동합니다. 이 설정에 적격한 클러스터를 하나 이상 선택한 경우 Google 인증 섹션이 표시됩니다.
사용 설정을 선택하여 선택한 클러스터에 대해 Google 인증을 사용 설정합니다. 프록시를 통해 Google ID 공급업체에 액세스해야 하는 경우 프록시 세부정보를 입력합니다.
구성 업데이트를 클릭합니다. 이렇게 하면 선택한 클러스터에 ID 구성이 적용됩니다.

gcloud

이전에 Fleet에 대해 GKE Identity Service를 설정하지 않았으면 GKE Identity Service를 위한 클러스터 구성의 안내를 따르세요. auth-config.yaml 파일에 다음 구성만 지정합니다.

spec:
  authentication:
  - name: google-authentication-method
    google:
      disable: false

프록시를 사용하여 제3자 그룹 액세스 구성

프록시를 통해 ID 공급업체에 액세스해야 하는 경우 auth-config.yaml 파일의 proxy 필드를 사용합니다. 예를 들어 클러스터가 비공개 네트워크에 있고 공개 ID 공급업체에 연결해야 하는 경우 이를 설정해야 할 수 있습니다. 이미 다른 제공업체에 대해 GKE Identity Service를 구성한 경우에도 이 구성을 추가해야 합니다.

proxy를 구성하기 위해 기존 구성 파일 auth-config.yaml의 authentication 섹션을 업데이트하는 방법은 다음과 같습니다.

  spec:
    authentication:
    - name: authentication-method
      google:
        disable: false
      proxy: PROXY_URL

각 항목의 의미는 다음과 같습니다.

disable(선택사항)은 클러스터에 제3자 그룹 기능을 선택 또는 선택 해제할 것인지를 나타냅니다. 이 옵션은 기본적으로 false로 설정됩니다. 이 기능을 선택 해제하려면 true로 설정하세요.
PROXY_URL(선택사항)은 Google Identity에 연결할 프록시 서버 주소입니다. 예를 들면 http://user:password@10.10.10.10:8888입니다.

구성 적용

클러스터에 구성을 적용하려면 다음 명령어를 실행합니다.

gcloud container fleet identity-service apply \
--membership=CLUSTER_NAME \
--config=/path/to/auth-config.yaml

각 항목의 의미는 다음과 같습니다.

CLUSTER_NAME은 전체 Fleet에서 클러스터의 고유한 멤버십 이름입니다.

이 구성을 적용하면 GKE Identity Service 컨트롤러에서 관리합니다. GKE Identity Service 클라이언트 구성의 모든 로컬 변경사항은 컨트롤러에서 이 설정에 지정된 구성으로 다시 조정합니다.

Kubectl

제3자 그룹 기능과 함께 GKE Identity Service를 사용하도록 클러스터를 구성하려면 클러스터의 GKE Identity Service ClientConfig를 업데이트해야 합니다. 클러스터 구성에 사용되는 Kubernetes 커스텀 리소스 유형(CRD)입니다. 각 GKE Enterprise 클러스터에는 구성 세부정보로 업데이트하는 kube-public 네임스페이스에 default라는 ClientConfig 리소스가 있습니다.

구성을 수정하려면 다음 명령어를 사용합니다.

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

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

다음은 제3자 그룹 기능을 사용 설정하기 위해 google 유형 구성이 있는 새 인증 메서드로 ClientConfig를 업데이트하는 방법의 예시입니다. internalServer 필드가 비어 있으면 아래와 같이 https://kubernetes.default.svc로 설정되어 있는지 확인하세요.

spec:
  authentication:
  - google:
      audiences:
      - "CLUSTER_IDENTIFIER"
    name: google-authentication-method
    proxy: PROXY_URL
  internalServer: https://kubernetes.default.svc

각 항목의 의미는 다음과 같습니다.

CLUSTER_IDENTIFIER(필수)는 클러스터의 멤버십 세부정보를 나타냅니다. 다음 명령어를 사용하여 클러스터의 멤버십 세부정보를 검색할 수 있습니다.

kubectl --kubeconfig CLUSTER_KUBECONFIG get memberships membership -o yaml

각 항목의 의미는 다음과 같습니다.

CLUSTER_KUBECONFIG는 클러스터의 kubeconfig 파일 경로입니다. 응답에서 spec.owner.id 필드를 참조하여 클러스터의 멤버십 세부정보를 검색합니다.

다음은 클러스터의 멤버십 세부정보를 보여주는 예시 응답입니다.

id: //gkehub.googleapis.com/projects/123456789/locations/global/memberships/xy-ab12cd34ef

이는 다음 형식에 해당합니다. //gkehub.googleapis.com/projects/PROJECT_NUMBER/locations/global/memberships/MEMBERSHIP

제3자 사용자 및 그룹에 IAM 역할 부여

제3자 ID는 게이트웨이를 통해 연결된 클러스터와 상호작용하기 위해 다음과 같은 추가 Google Cloud 역할이 필요합니다.

roles/gkehub.gatewayAdmin: 이 역할을 통해 사용자는 Connect Gateway API에 액세스할 수 있습니다.
- 사용자가 연결된 클러스터에 대한 읽기 전용 액세스 권한만 필요한 경우 대신 roles/gkehub.gatewayReader를 사용할 수 있습니다.
- 사용자에게 연결된 클러스터에 대한 읽기/쓰기 액세스 권한이 필요한 경우 대신 roles/gkehub.gatewayEditor를 사용할 수 있습니다.
roles/gkehub.viewer: 이 역할을 통해 사용자는 등록된 클러스터 멤버십을 볼 수 있습니다.

다음은 개별 ID 및 매핑된 그룹에 필요한 역할을 추가하는 방법을 보여줍니다.

단일 ID

PROJECT_ID 프로젝트의 단일 ID에 필요한 역할을 부여하려면 다음 명령어를 실행합니다.

gcloud projects add-iam-policy-binding PROJECT_ID \
    --role=GATEWAY_ROLE \
    --member="principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subject/SUBJECT_VALUE"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --role=roles/gkehub.viewer \
    --member="principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subject/SUBJECT_VALUE"

각 항목의 의미는 다음과 같습니다.

PROJECT_ID: 프로젝트의 ID
GATEWAY_ROLE: roles/gkehub.gatewayAdmin, roles/gkehub.gatewayReader 또는 gkehub.gatewayEditor 중 하나
WORKFORCE_POOL_ID: 직원 ID 풀 ID
SUBJECT_VALUE: 사용자 ID

그룹

PROJECT_ID 프로젝트의 특정 그룹 내 모든 ID에 필요한 역할을 부여하려면 다음 명령어를 실행합니다.

gcloud projects add-iam-policy-binding PROJECT_ID \
    --role=GATEWAY_ROLE \
    --member="principalSet://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/group/GROUP_ID"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --role=roles/gkehub.viewer \
    --member="principalSet://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/group/GROUP_ID"

각 항목의 의미는 다음과 같습니다.

PROJECT_ID: 프로젝트의 ID
GATEWAY_ROLE: roles/gkehub.gatewayAdmin, roles/gkehub.gatewayReader 또는 gkehub.gatewayEditor 중 하나
WORKFORCE_POOL_ID: 직원 풀 ID
GROUP_ID: 매핑된 google.groups 클레임의 그룹

RBAC 정책을 적용할 때 부서 속성 지정과 같은 추가 맞춤설정은 직원 ID를 사용하여 제3자 매핑 설정하기에 나열된 ID 공급업체 설정을 참조하세요.

IAM 권한 및 역할 부여에 대한 자세한 내용은 리소스에 대한 액세스 권한 부여, 변경, 취소를 참조하세요.

역할 기반 액세스 제어(RBAC) 정책 구성

마지막으로 각 클러스터의 Kubernetes API 서버는 지정된 제3자 사용자 및 그룹에서 게이트웨이를 통해 들어오는 kubectl 명령어를 승인할 수 있어야 합니다. 각 클러스터에 대해 주체가 클러스터에 대해 가지고 있는 권한을 지정하는 RBAC 권한 정책을 추가해야 합니다.

RBAC 정책의 주체는 IAM binding과 동일한 형식을 사용해야 하며, principal://iam.googleapis.com/으로 시작하는 제3자 사용자와 principalSet://iam.googleapis.com/으로 시작하는 제3자 그룹이 필요합니다. 클러스터에 GKE Identity Service가 구성되어 있지 않으면 제3자 사용자의 역할/클러스터 역할 외에도 가장 정책이 필요합니다. 이 경우 RBAC 설정 단계를 따라 principal://iam.googleapis.com/로 시작하는 제3자 주 구성원을 사용자로 추가합니다.

다음 예시에서는 GKE Identity Service가 구성된 클러스터에서 제3자 그룹의 구성원에게 cluster-admin 권한을 부여하는 방법을 보여줍니다. 그런 다음 정책 파일을 /tmp/admin-permission.yaml로 저장하고 현재 컨텍스트와 연결된 클러스터에 적용할 수 있습니다.

cat <<EOF > /tmp/admin-permission.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: gateway-cluster-admin-group
subjects:
- kind: Group
  name: "principalSet://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/group/GROUP"
roleRef:
  kind: ClusterRole
  name: cluster-admin
  apiGroup: rbac.authorization.k8s.io
EOF
# Apply permission policy to the cluster.
kubectl apply --kubeconfig=KUBECONFIG_PATH -f /tmp/admin-permission.yaml

RBAC 권한 지정에 대한 자세한 내용은 RBAC 승인 사용을 참조하세요.

다음 단계

Connect 게이트웨이를 사용하여 명령줄에서 클러스터에 연결하는 방법 알아보기
Cloud Build와 통합 튜토리얼에서 DevOps 자동화의 일부로 Connect 게이트웨이를 사용하는 방법의 예시 참조하기