워크로드 아이덴티티 클러스터 인증

이 문서에서는 베어메탈용 Google Distributed Cloud (소프트웨어 전용)의 워크로드 아이덴티티 클러스터 인증을 설정하고 사용하는 방법을 설명합니다. 워크로드 아이덴티티 클러스터 인증은 서비스 계정 키 대신 단기 토큰과 워크로드 아이덴티티 제휴를 사용하여 클러스터를 만들고 보호합니다. 서비스 계정의 단기 사용자 인증 정보는 OAuth 2.0 액세스 토큰 형태로 제공됩니다. 액세스 토큰은 기본적으로 1시간 후에 만료됩니다. 마찬가지로 이미지 가져오기 토큰도 기본적으로 1시간 후에 만료됩니다.

반면 클러스터 생성 및 보호를 위한 표준 방법인 키 모드는 다운로드된 서비스 계정 키를 사용합니다. 자체 관리형(관리자, 하이브리드 또는 독립형) 클러스터를 만들 때 다운로드한 키의 경로를 지정합니다. 그러면 키가 클러스터 및 관리 사용자 클러스터에 보안 비밀로 저장됩니다. 기본적으로 서비스 계정 키는 만료되지 않으며 올바르게 관리되지 않으면 보안 위험이 발생합니다. 서비스 계정 키의 만료 시간을 설정하는 방법에 대한 자세한 내용은 사용자 관리 키의 만료 시간을 참고하세요.

워크로드 아이덴티티 클러스터 인증은 서비스 계정 키를 사용하는 것보다 다음과 같은 두 가지 주요 이점이 있습니다.

  • 보안 개선: 서비스 계정 키를 올바르게 관리하지 않으면 보안 위험이 발생할 수 있습니다. OAuth 2.0 토큰과 워크로드 아이덴티티 제휴는 서비스 계정 키의 권장 대안으로 간주됩니다. 서비스 계정 토큰에 관한 자세한 내용은 단기 서비스 계정 사용자 인증 정보를 참조하세요. 워크로드 아이덴티티 제휴에 관한 자세한 내용은 워크로드 아이덴티티 제휴를 참조하세요.

  • 유지보수 감소: 서비스 계정 키는 더 많은 유지보수가 필요합니다. 이러한 키를 정기적으로 순환하고 보호하는 것은 상당한 관리 부담이 될 수 있습니다.

워크로드 아이덴티티 클러스터 인증은 출시 1.30에서 프리뷰로 도입되었으며 출시 1.33 이상에서 정식 버전으로 제공됩니다. 워크로드 아이덴티티 클러스터 인증은 새 클러스터를 만들 때만 사용 설정할 수 있습니다. 업데이트 또는 업그레이드 중에 워크로드 아이덴티티 클러스터 인증을 사용하도록 기존 클러스터를 구성할 수는 없습니다. 추가 제한사항은 제한사항을 참고하세요.

이 페이지는 기본 기술 인프라의 수명 주기를 설정, 모니터링, 관리하는 관리자, 설계자, 운영자를 위해 작성되었습니다.Google Cloud 콘텐츠에서 참조하는 일반적인 역할 및 예시 태스크에 대해 자세히 알아보려면 일반 GKE 사용자 역할 및 태스크를 참조하세요.

시작하기 전에

다음 섹션에서는 서비스 계정을 만들고 워크로드 아이덴티티 클러스터 인증에 필요한 역할을 부여합니다. 이 문서의 설정 안내는 Google Cloud리소스 설정의 안내를 대체하는 것이 아니라 표준 Google Distributed Cloud 소프트웨어 전용 설치 기본 요건에 더하여 부가적으로 필요합니다. 워크로드 아이덴티티 클러스터 인증에 필요한 서비스 계정은 Google Cloud 리소스 설정에 설명된 서비스 계정과 유사하지만 고유한 이름이 지정되어 있으므로 기본 서비스 계정 키를 사용하는 클러스터를 방해하지 않습니다.

워크로드 아이덴티티 클러스터 인증에 필요한 서비스 계정은 다음 표에 설명된 대로 프리뷰 및 정식 버전 서비스에 따라 다릅니다.

1.33 이상

서비스 계정 목적 역할
admin-sa 이 서비스 계정을 사용하여 토큰을 생성합니다. 각 토큰에는 서비스 계정 역할과 연결된 권한이 있습니다. roles/gkehub.admin
roles/iam.serviceAccountAdmin
roles/iam.serviceAccountTokenCreator
roles/logging.admin
roles/monitoring.admin
roles/resourcemanager.projectIamAdmin
baremetal-gcr Google Distributed Cloud는 이 서비스 계정을 사용하여 Artifact Registry에서 컨테이너 이미지를 다운로드합니다. 없음

1.30-1.32

서비스 계정 목적 역할
admin-sa 이 서비스 계정을 사용하여 토큰을 생성합니다. 각 토큰에는 서비스 계정 역할과 연결된 권한이 있습니다. roles/gkehub.admin
roles/iam.serviceAccountAdmin
roles/iam.serviceAccountTokenCreator
roles/logging.admin
roles/monitoring.admin
baremetal-controller Connect Agent는 이 서비스 계정을 사용하여 클러스터와 Google Cloud 간의 연결을 유지하고, 클러스터를 Fleet에 등록합니다. 이 서비스 계정은 baremetal-gcr 서비스 계정의 토큰도 새로고침합니다. roles/gkehub.admin
roles/monitoring.dashboardEditor
roles/serviceusage.serviceUsageViewer
baremetal-cloud-ops Stackdriver Agent는 이 서비스 계정을 사용하여 클러스터의 로그와 측정항목을 Cloud Logging 및 Cloud Monitoring으로 내보냅니다. roles/kubernetesmetadata.publisher
roles/logging.logWriter
roles/monitoring.dashboardEditor
roles/monitoring.metricWriter
roles/monitoring.viewer
roles/opsconfigmonitoring.resourceMetadata.writer
roles/serviceusage.serviceUsageViewer
roles/stackdriver.resourceMetadata.writer
baremetal-gcr Google Distributed Cloud는 이 서비스 계정을 사용하여 Artifact Registry에서 컨테이너 이미지를 다운로드합니다. 없음

서비스 계정 설정

다음 섹션에는 필요한 서비스 계정을 만들고 워크로드 아이덴티티 클러스터 인증에 필요한 역할을 부여하는 안내가 포함되어 있습니다. 서비스 계정 및 필요한 역할의 목록은 이전 섹션의 표를 참조하세요.

서비스 계정 만들기

워크로드 아이덴티티 클러스터 인증의 서비스 계정을 만들려면 다음 단계를 따르세요.

  1. 관리자 워크스테이션에서 Google Cloud CLI에 로그인합니다.

    gcloud auth login

  2. 워크로드 아이덴티티 클러스터 인증에 필요한 서비스 계정을 만듭니다.

    admin-sa 서비스 계정 이름은 임의로 지정할 수 있습니다. 이름이 프로젝트에서 충돌을 일으키는 경우 이름을 변경할 수 있습니다. 워크로드 아이덴티티 클러스터 인증의 다른 서비스 계정에는 사전 지정된 이름이 있으며, 원하는 경우 맞춤설정할 수 있습니다.

    1.33 이상 

    gcloud iam service-accounts create admin-sa \
    --project=PROJECT_ID

gcloud iam service-accounts create baremetal-gcr \
    --project=PROJECT_ID

    PROJECT_ID를Google Cloud 프로젝트 ID로 바꿉니다.

    1.30-1.32 

    gcloud iam service-accounts create admin-sa \
    --project=PROJECT_ID

gcloud iam service-accounts create baremetal-controller \
    --project=PROJECT_ID

gcloud iam service-accounts create baremetal-cloud-ops \
    --project=PROJECT_ID

gcloud iam service-accounts create baremetal-gcr \
    --project=PROJECT_ID

    PROJECT_ID를Google Cloud 프로젝트 ID로 바꿉니다.

서비스 계정에 ID 및 액세스 관리 정책 바인딩 추가

다음 단계에 따라 필요한 ID 및 액세스 관리 정책 바인딩을 새 서비스 계정에 적용합니다.

1.33 이상

  1. admin-sa 서비스 계정에 필요한 역할의 IAM 정책 바인딩을 추가합니다.

    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:admin-sa@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/gkehub.admin

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:admin-sa@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/iam.serviceAccountAdmin

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:admin-sa@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/iam.serviceAccountTokenCreator

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:admin-sa@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/logging.admin

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:admin-sa@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/monitoring.admin

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:admin-sa@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/resourcemanager.projectIamAdmin

1.30-1.32

  1. admin-sa 서비스 계정에 필요한 역할의 IAM 정책 바인딩을 추가합니다.

    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:admin-sa@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/gkehub.admin

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:admin-sa@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/iam.serviceAccountAdmin

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:admin-sa@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/iam.serviceAccountTokenCreator

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:admin-sa@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/logging.admin

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:admin-sa@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/monitoring.admin

  2. baremetal-controller 서비스 계정에 필요한 역할의 IAM 정책 바인딩을 추가합니다.

    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:baremetal-controller@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/gkehub.admin

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:baremetal-controller@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/monitoring.dashboardEditor

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:baremetal-controller@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/serviceusage.serviceUsageViewer

  3. baremetal-cloud-ops 서비스 계정에 필요한 역할의 IAM 정책 바인딩을 추가합니다.

    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:baremetal-cloud-ops@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/kubernetesmetadata.publisher

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:baremetal-cloud-ops@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/logging.logWriter

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:baremetal-cloud-ops@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/monitoring.dashboardEditor

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:baremetal-cloud-ops@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/monitoring.metricWriter

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:baremetal-cloud-ops@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/monitoring.viewer

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:baremetal-cloud-ops@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/opsconfigmonitoring.resourceMetadata.writer

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:baremetal-cloud-ops@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/serviceusage.serviceUsageViewer

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:baremetal-cloud-ops@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/stackdriver.resourceMetadata.writer

  4. baremetal-controller 서비스 계정에 baremetal-gcr 서비스 계정을 대신하여 액세스 토큰을 생성할 수 있는 권한을 부여합니다.

    gcloud iam service-accounts add-iam-policy-binding \
    baremetal-gcr@PROJECT_ID.iam.gserviceaccount.com \
    --member=serviceAccount:baremetal-controller@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/iam.serviceAccountTokenCreator

인증 설정

다음 단계에서는 클러스터 작업을 인증하는 데 단기 토큰을 사용하는 인증 흐름을 설정합니다.

  1. 관리자 워크스테이션에서 Google Cloud CLI에 로그인합니다.

    gcloud auth login

  2. 관리자 워크스테이션에서 admin-sa 서비스 계정의 키를 만들고 다운로드합니다.

    이 키는 admin-sa 서비스 계정의 액세스 권한을 승인하는 데 필요합니다.

    gcloud iam service-accounts keys create TMP_KEY_FILE_PATH \
    --iam-account=admin-sa@PROJECT_ID.iam.gserviceaccount.com

    TMP_KEY_FILE_PATH을 다운로드한 키 파일의 경로(파일 이름 포함)로 바꿉니다.

  3. 관리자 워크스테이션에서 다운로드한 서비스 계정 키 값을 사용하여 GOOGLE_APPLICATION_CREDENTIALS 환경 변수를 만듭니다.

    export GOOGLE_APPLICATION_CREDENTIALS=TMP_KEY_FILE_PATH

  4. 관리자 워크스테이션에서 admin-sa 서비스 계정으로 만든 액세스 토큰 값을 사용하여 GCP_ACCESS_TOKEN 환경 변수를 만듭니다.

    export GCP_ACCESS_TOKEN=$(gcloud auth application-default print-access-token)

    기본적으로 액세스 토큰의 수명은 1시간입니다.

  5. admin-sa 서비스 계정에서 올바른 만료일로 토큰을 생성했는지 확인합니다.

    curl "https://oauth2.googleapis.com/tokeninfo?access_token=$GCP_ACCESS_TOKEN"

    응답에는 다음과 유사한 줄이 포함되어 있어야 합니다.

    ...
"exp": "1759512810",
"expires_in": "3589",
...

    만료 값은 초 단위이며 3600보다 작아야 합니다. 이는 토큰이 1시간 이내에 만료됨을 나타냅니다.

클러스터에 워크로드 아이덴티티 제휴 구성

GKE용 워크로드 아이덴티티 제휴를 사용하여 Google Cloud 액세스 권한을 제공하려면 애플리케이션 ID에 해당하는 주 구성원에게 특정Google Cloud 리소스에 대한 액세스 권한을 부여하는 IAM 허용 정책을 만듭니다. 이 경우 워크로드 아이덴티티 제휴는 클러스터의 특정 운영자에게 액세스 권한을 부여합니다. GKE용 워크로드 아이덴티티 제휴에 관한 자세한 내용은 IAM 문서의 워크로드 아이덴티티 제휴를 참고하세요.

1.33 이상

워크로드 아이덴티티 클러스터 인증이 정식 버전인 클러스터 버전의 경우 bmctl configure projects 명령어를 사용하여 클러스터의 워크로드 아이덴티티 제휴를 구성합니다. 이 명령어는 관리자 클러스터 만들기 및 사용자 클러스터 만들기 단계에 통합되어 있습니다.

1.30-1.32

워크로드 아이덴티티 클러스터 인증이 프리뷰 상태인 클러스터 버전의 경우 다음 섹션에 설명된 대로 클러스터에 워크로드 아이덴티티 제휴를 수동으로 구성해야 합니다.

클러스터 운영자에 IAM 정책 바인딩 추가

다음 명령어는 anthos-cluster-operator Kubernetes 서비스 계정에 baremetal-controller 서비스 계정을 가장하고 클러스터를 대신하여 Google Cloud 리소스와 상호작용할 수 있는 권한을 부여합니다.

  1. 워크로드 아이덴티티 클러스터 인증을 사용하도록 구성된(또는 워크로드 아이덴티티 클러스터 인증을 사용할 계획인) 각 클러스터(부트스트랩 클러스터 포함)의 경우 클러스터의 anthos-cluster-operator에 baremetal-controller 서비스 계정을 가장할 수 있는 권한을 부여합니다.

    다음 명령어에서 principalSet는 워크로드 ID 풀과 kube-system 네임스페이스의 Kubernetes 서비스 계정 anthos-cluster-operator로 구성됩니다.

    gcloud iam service-accounts add-iam-policy-binding \
    baremetal-controller@PROJECT_ID.iam.gserviceaccount.com \
    --member=principalSet://iam.googleapis.com/projects/PROJECT_NUM/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/attribute.fleetclusteridentity/projects/PROJECT_ID/locations/REGION/memberships/CLUSTER_NAME/ns/kube-system/sa/anthos-cluster-operator \
    --role=roles/iam.workloadIdentityUser \
    --project=PROJECT_ID

    다음을 바꿉니다.

    • PROJECT_NUM: 자동으로 생성되는 프로젝트의 고유 식별자

    • REGION: 클러스터의 Fleet 멤버십 위치. 기본값은 global입니다. 자세한 내용은 Fleet 멤버십 위치를 참조하세요.

    • CLUSTER_NAME: 클러스터의 이름. 기본적으로 부트스트랩 클러스터 이름은 bmctl-MACHINE_NAME입니다.

  2. baremetal-controller 서비스 계정의 정책 바인딩을 확인합니다.

    gcloud iam service-accounts get-iam-policy \
    baremetal-controller@PROJECT_ID.iam.gserviceaccount.com

    응답은 다음과 비슷하게 표시됩니다.

    bindings:
- members:
  - principalSet://iam.googleapis.com/projects/112233445566/locations/global/workloadIdentityPools/my-project.svc.id.goog/attribute.fleetclusteridentity/bmctl-admin-ws/kube-system/anthos-cluster-operator
  - principalSet://iam.googleapis.com/projects/112233445566/locations/global/workloadIdentityPools/my-project.svc.id.goog/attribute.fleetclusteridentity/admin-cluster/kube-system/anthos-cluster-operator
  - principalSet://iam.googleapis.com/projects/112233445566/locations/global/workloadIdentityPools/my-project.svc.id.goog/attribute.fleetclusteridentity/user-cluster/kube-system/anthos-cluster-operator
  role: roles/iam.workloadIdentityUser
etag: BwYoN3QLig0=
version: 1

Google Cloud Observability 운영자에 IAM 정책 바인딩 추가

다음 명령어는 다음 Google Cloud Observability Kubernetes 서비스 계정에 baremetal-cloud-ops 서비스 계정을 가장하고 클러스터를 대신하여 Google Cloud 리소스와 상호작용할 수 있는 권한을 부여합니다.

  • cloud-audit-logging
  • gke-metrics-agent
  • kubestore-collector
  • metadata-agent
  • stackdriver-log-forwarder

  1. 워크로드 아이덴티티 클러스터 인증을 사용하도록 구성된(또는 워크로드 아이덴티티 클러스터 인증을 사용할 계획인) 각 클러스터(부트스트랩 클러스터 포함)의 경우 클러스터의 Google Cloud Observability 운영자에게 baremetal-cloud-ops 서비스 계정을 가장할 수 있는 권한을 부여합니다.

    다음 명령어에서 principalSet는 워크로드 아이덴티티 풀과 kube-system 네임스페이스의 Kubernetes 서비스 계정(예: cloud-audit-logging)으로 구성됩니다.

    gcloud iam service-accounts add-iam-policy-binding \
    baremetal-cloud-ops@PROJECT_ID.iam.gserviceaccount.com \
    --member=principalSet://iam.googleapis.com/projects/PROJECT_NUM/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/attribute.fleetclusteridentity/projects/PROJECT_ID/locations/REGION/memberships/CLUSTER_NAME/ns/kube-system/sa/cloud-audit-logging \
    --role=roles/iam.workloadIdentityUser \
    --project=PROJECT_ID

gcloud iam service-accounts add-iam-policy-binding \
    baremetal-cloud-ops@PROJECT_ID.iam.gserviceaccount.com \
    --member=principalSet://iam.googleapis.com/projects/PROJECT_NUM/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/attribute.fleetclusteridentity/projects/PROJECT_ID/locations/REGION/memberships/CLUSTER_NAME/ns/kube-system/sa/gke-metrics-agent \
    --role=roles/iam.workloadIdentityUser \
    --project=PROJECT_ID

gcloud iam service-accounts add-iam-policy-binding \
    baremetal-cloud-ops@PROJECT_ID.iam.gserviceaccount.com \
    --member=principalSet://iam.googleapis.com/projects/PROJECT_NUM/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/attribute.fleetclusteridentity/projects/PROJECT_ID/locations/REGION/memberships/CLUSTER_NAME/ns/kube-system/sa/kubestore-collector \
    --role=roles/iam.workloadIdentityUser \
    --project=PROJECT_ID

gcloud iam service-accounts add-iam-policy-binding \
    baremetal-cloud-ops@PROJECT_ID.iam.gserviceaccount.com \
    --member=principalSet://iam.googleapis.com/projects/PROJECT_NUM/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/attribute.fleetclusteridentity/projects/PROJECT_ID/locations/REGION/memberships/CLUSTER_NAME/ns/kube-system/sa/metadata-agent \
    --role=roles/iam.workloadIdentityUser \
    --project=PROJECT_ID

gcloud iam service-accounts add-iam-policy-binding \
    baremetal-cloud-ops@PROJECT_ID.iam.gserviceaccount.com \
    --member=principalSet://iam.googleapis.com/projects/PROJECT_NUM/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/attribute.fleetclusteridentity/projects/PROJECT_ID/locations/REGION/memberships/CLUSTER_NAME/ns/kube-system/sa/stackdriver-log-forwarder \
    --role=roles/iam.workloadIdentityUser \
    --project=PROJECT_ID

  2. baremetal-cloud-ops 서비스 계정의 정책 바인딩을 확인합니다.

    gcloud iam service-accounts get-iam-policy \
    baremetal-cloud-ops@PROJECT_ID.iam.gserviceaccount.com

    응답은 다음과 비슷하게 표시됩니다.

    bindings:
- members:
  - principalSet://iam.googleapis.com/projects/112233445566/locations/global/workloadIdentityPools/my-project.svc.id.goog/attribute.fleetclusteridentity/bmctl-admin-ws/kube-system/cloud-audit-logging
  - principalSet://iam.googleapis.com/projects/112233445566/locations/global/workloadIdentityPools/my-project.svc.id.goog/attribute.fleetclusteridentity/bmctl-admin-ws/kube-system/gke-metrics-agent
  - principalSet://iam.googleapis.com/projects/112233445566/locations/global/workloadIdentityPools/my-project.svc.id.goog/attribute.fleetclusteridentity/bmctl-admin-ws/kube-system/kubestore-collector
  - principalSet://iam.googleapis.com/projects/112233445566/locations/global/workloadIdentityPools/my-project.svc.id.goog/attribute.fleetclusteridentity/bmctl-admin-ws/kube-system/metadata-agent
  - principalSet://iam.googleapis.com/projects/112233445566/locations/global/workloadIdentityPools/my-project.svc.id.goog/attribute.fleetclusteridentity/bmctl-admin-ws/kube-system/stackdriver-log-forwarder
  - principalSet://iam.googleapis.com/projects/112233445566/locations/global/workloadIdentityPools/my-project.svc.id.goog/attribute.fleetclusteridentity/admin-cluster/kube-system/cloud-audit-logging
  - principalSet://iam.googleapis.com/projects/112233445566/locations/global/workloadIdentityPools/my-project.svc.id.goog/attribute.fleetclusteridentity/admin-cluster/kube-system/gke-metrics-agent
  - principalSet://iam.googleapis.com/projects/112233445566/locations/global/workloadIdentityPools/my-project.svc.id.goog/attribute.fleetclusteridentity/admin-cluster/kube-system/kubestore-collector
  - principalSet://iam.googleapis.com/projects/112233445566/locations/global/workloadIdentityPools/my-project.svc.id.goog/attribute.fleetclusteridentity/admin-cluster/kube-system/metadata-agent
  - principalSet://iam.googleapis.com/projects/112233445566/locations/global/workloadIdentityPools/my-project.svc.id.goog/attribute.fleetclusteridentity/admin-cluster/kube-system/stackdriver-log-forwarder
  - principalSet://iam.googleapis.com/projects/112233445566/locations/global/workloadIdentityPools/my-project.svc.id.goog/attribute.fleetclusteridentity/user-cluster/kube-system/cloud-audit-logging
  - principalSet://iam.googleapis.com/projects/112233445566/locations/global/workloadIdentityPools/my-project.svc.id.goog/attribute.fleetclusteridentity/user-cluster/kube-system/gke-metrics-agent
  - principalSet://iam.googleapis.com/projects/112233445566/locations/global/workloadIdentityPools/my-project.svc.id.goog/attribute.fleetclusteridentity/user-cluster/kube-system/kubestore-collector
  - principalSet://iam.googleapis.com/projects/112233445566/locations/global/workloadIdentityPools/my-project.svc.id.goog/attribute.fleetclusteridentity/user-cluster/kube-system/metadata-agent
  - principalSet://iam.googleapis.com/projects/112233445566/locations/global/workloadIdentityPools/my-project.svc.id.goog/attribute.fleetclusteridentity/user-cluster/kube-system/stackdriver-log-forwarder
  role: roles/iam.workloadIdentityUser
etag: BwYhT4gL-dY=
version: 1

관리자 클러스터 만들기

관리자 클러스터를 만드는 단계는 미리보기 (버전 1.30~1.32)와 정식 버전(버전 1.33 이상) 제품에 따라 약간 다릅니다. GA 단계에서는 bmctl configure projects 명령어를 사용하여 클러스터에 워크로드 아이덴티티 제휴를 구성합니다.

1.33 이상

워크로드 아이덴티티 클러스터 인증을 사용하는 클러스터의 가장 명백한 클러스터 구성 차이점은 다운로드된 서비스 계정 키의 경로를 지정하지 않는다는 점입니다.

  1. 구성 파일에서 클러스터 설정을 입력할 때는 다음 예와 같이 사용자 인증 정보 섹션의 서비스 계정 키 경로를 비워 둡니다.

    gcrKeyPath:
sshPrivateKeyPath: /home/USERNAME/.ssh/id_rsa
gkeConnectAgentServiceAccountKeyPath:
gkeConnectRegisterServiceAccountKeyPath:
cloudOperationsServiceAccountKeyPath:
---
apiVersion: v1
kind: Namespace
metadata:
  name: cluster-ADMIN_CLUSTER_NAME
---
apiVersion: baremetal.cluster.gke.io/v1
kind: Cluster
metadata:
  name: ADMIN_CLUSTER_NAME
  namespace: cluster-ADMIN_CLUSTER_NAME
spec:
  type: admin
  profile: default
  anthosBareMetalVersion: 1.33.0-gke.799
  ...

  2. baremetal.cluster.gke.io/enable-workload-identity-cluster-authentication: "true" 주석을 클러스터 구성 파일에 추가합니다.

    gcrKeyPath:
sshPrivateKeyPath: /home/USERNAME/.ssh/id_rsa
gkeConnectAgentServiceAccountKeyPath:
gkeConnectRegisterServiceAccountKeyPath:
cloudOperationsServiceAccountKeyPath:
---
apiVersion: v1
kind: Namespace
metadata:
  name: cluster-ADMIN_CLUSTER_NAME
---
apiVersion: baremetal.cluster.gke.io/v1
kind: Cluster
metadata:
  name: ADMIN_CLUSTER_NAME
  namespace: cluster-ADMIN_CLUSTER_NAME
  annotations:
    baremetal.cluster.gke.io/enable-workload-identity-cluster-authentication: "true"
spec:
  type: admin
  profile: default
  anthosBareMetalVersion: 1.33.0-gke.799
  ...

  3. 관리자 워크스테이션에서 새로 가져온 액세스 토큰으로 GCP_ACCESS_TOKEN 환경 변수를 업데이트합니다.

    export GCP_ACCESS_TOKEN=$(gcloud auth application-default print-access-token)

    기본적으로 액세스 토큰의 수명은 3, 600초 (1시간)입니다. 워크로드 아이덴티티 클러스터 인증을 사용하는 경우 bmctl는 토큰 만료 시간을 확인합니다. 토큰 만료가 1,800초 (30분) 이내인 경우 bmctl는 오류를 보고하고 종료됩니다.

  4. 생성 중인 클러스터에 워크로드 아이덴티티 제휴를 구성합니다.

    bmctl configure projects --project-id=PROJECT_ID \
    --admin-cluster=ADMIN_CLUSTER_NAME

  5. bmctl create cluster 명령어를 실행하여 관리자 클러스터를 만듭니다.

1.30-1.32

워크로드 아이덴티티 클러스터 인증을 사용하는 클러스터의 가장 명백한 클러스터 구성 차이점은 다운로드된 서비스 계정 키의 경로를 지정하지 않는다는 점입니다.

  1. 구성 파일에서 클러스터 설정을 입력할 때는 다음 예와 같이 사용자 인증 정보 섹션의 서비스 계정 키 경로를 비워 둡니다.

    gcrKeyPath:
sshPrivateKeyPath: /home/USERNAME/.ssh/id_rsa
gkeConnectAgentServiceAccountKeyPath:
gkeConnectRegisterServiceAccountKeyPath:
cloudOperationsServiceAccountKeyPath:
---
apiVersion: v1
kind: Namespace
metadata:
  name: cluster-ADMIN_CLUSTER_NAME
---
apiVersion: baremetal.cluster.gke.io/v1
kind: Cluster
metadata:
  name: ADMIN_CLUSTER_NAME
  namespace: cluster-ADMIN_CLUSTER_NAME
spec:
  type: admin
  profile: default
  anthosBareMetalVersion: 1.33.0-gke.799
  ...

  2. 관리자 워크스테이션에서 admin-sa 서비스 계정의 키를 만들고 다운로드합니다.

    이 키는 admin-sa 서비스 계정의 액세스 권한을 승인하는 데 필요하며 서비스 계정이 승인된 후에는 즉시 삭제합니다.

    gcloud iam service-accounts keys create TMP_KEY_FILE_PATH \
    --iam-account=admin-sa@PROJECT_ID.iam.gserviceaccount.com

    TMP_KEY_FILE_PATH을 다운로드한 키 파일의 경로(파일 이름 포함)로 바꿉니다.

  3. admin-sa 서비스 계정으로 Google Cloud 에 대한 액세스 권한을 승인합니다.

    gcloud auth activate-service-account admin-sa@PROJECT_ID.iam.gserviceaccount.com \
    --key-file=TMP_KEY_FILE_PATH

  4. 다운로드한 JSON 키 파일을 삭제합니다.

    rm TMP_KEY_FILE_PATH

    액세스 토큰은 수명이 짧으므로 클러스터 생성, 업그레이드, 재설정과 같은 클러스터 작업을 위해 bmctl 명령어를 실행하기 전에 일반적으로 재생성해야 합니다.

  5. 관리자 워크스테이션에서 admin-sa 서비스 계정으로 만든 액세스 토큰 값을 사용하여 GCP_ACCESS_TOKEN 환경 변수를 만듭니다.

    export GCP_ACCESS_TOKEN=$(gcloud auth print-access-token \
    --impersonate-service-account=admin-sa@PROJECT_ID.iam.gserviceaccount.com)

    기본적으로 액세스 토큰의 수명은 3, 600초 (1시간)입니다.

  6. bmctl create cluster 명령어를 실행하여 관리자 클러스터를 만듭니다.

사용자 클러스터 만들기

관리자 클러스터를 만드는 단계는 미리보기 (버전 1.30~1.32)와 정식 버전(버전 1.33 이상) 제품에 따라 약간 다릅니다. GA 단계에서는 bmctl configure projects 명령어를 사용하여 클러스터에 워크로드 아이덴티티 제휴를 구성합니다.

1.33 이상

  1. baremetal.cluster.gke.io/enable-workload-identity-cluster-authentication: "true" 주석을 클러스터 구성 파일에 추가합니다.

    apiVersion: v1
kind: Namespace
metadata:
  name: cluster-USER_CLUSTER_NAME
---
apiVersion: baremetal.cluster.gke.io/v1
kind: Cluster
metadata:
  name: USER_CLUSTER_NAME
  namespace: cluster-USER_CLUSTER_NAME
  annotations:
    baremetal.cluster.gke.io/enable-workload-identity-cluster-authentication: "true"
spec:
  type: admin
  profile: default
  anthosBareMetalVersion: 1.33.0-gke.799
  ...

    액세스 토큰은 수명이 짧으므로 클러스터 생성, 업그레이드, 재설정과 같은 클러스터 작업을 위해 bmctl 명령어를 실행하기 전에 재생성해야 합니다.

  2. 관리자 워크스테이션에서 새로 가져온 액세스 토큰으로 GCP_ACCESS_TOKEN 환경 변수를 업데이트합니다.

    export GCP_ACCESS_TOKEN=$(gcloud auth application-default print-access-token)

    기본적으로 액세스 토큰의 수명은 3, 600초 (1시간)입니다.

  3. 생성 중인 클러스터에 워크로드 아이덴티티 제휴를 구성합니다.

    bmctl configure projects --project-id=PROJECT_ID \
    --user-clusters=USER_CLUSTER_NAME

  4. kubectl을 사용하여 사용자 클러스터 매니페스트를 배포합니다.

    kubectl apply -f USER_CLUSTER_CONFIG \
    --kubeconfig ADMIN_KUBECONFIG

다음을 바꿉니다.

  • USER_CLUSTER_CONFIG: 사용자 클러스터 구성 파일의 경로입니다.

  • ADMIN_KUBECONFIG: 관리자 클러스터의 kubeconfig 파일 경로입니다.

1.30-1.32

  1. 관리자 워크스테이션에서 admin-sa 서비스 계정의 키를 만들고 다운로드합니다.

    이 키는 admin-sa 서비스 계정의 액세스 권한을 승인하는 데 필요하며 서비스 계정이 승인된 후에는 즉시 삭제합니다.

    gcloud iam service-accounts keys create TMP_KEY_FILE_PATH \
    --iam-account=admin-sa@PROJECT_ID.iam.gserviceaccount.com

    TMP_KEY_FILE_PATH을 다운로드한 키 파일의 경로(파일 이름 포함)로 바꿉니다.

  2. admin-sa 서비스 계정으로 Google Cloud 에 대한 액세스 권한을 승인합니다.

    gcloud auth activate-service-account admin-sa@PROJECT_ID.iam.gserviceaccount.com \
    --key-file=TMP_KEY_FILE_PATH

  3. 다운로드한 JSON 키 파일을 삭제합니다.

    rm TMP_KEY_FILE_PATH

    액세스 토큰은 수명이 짧으므로 클러스터 생성, 업그레이드, 재설정과 같은 클러스터 작업을 위해 bmctl 명령어를 실행하기 전에 일반적으로 재생성해야 합니다.

  4. 관리자 워크스테이션에서 admin-sa 서비스 계정으로 만든 액세스 토큰 값을 사용하여 GCP_ACCESS_TOKEN 환경 변수를 만듭니다.

    export GCP_ACCESS_TOKEN=$(gcloud auth print-access-token \
    --impersonate-service-account=admin-sa@PROJECT_ID.iam.gserviceaccount.com)

    기본적으로 액세스 토큰의 수명은 3, 600초 (1시간)입니다.

  5. bmctl create cluster 명령어를 실행하여 사용자 클러스터를 만듭니다.

기타 클러스터 작업

워크로드 아이덴티티 클러스터 인증을 사용하는 클러스터의 경우 다음 bmctl 명령어를 실행하려면 GCP_ACCESS_TOKEN 환경 변수를 유효하고 활성 상태인 액세스 토큰으로 설정해야 합니다.

  • bmctl configure projects
  • bmctl create cluster
  • bmctl reset cluster
  • bmctl upgrade cluster

bmctl가 GCP_ACCESS_TOKEN 환경 변수가 설정되었음을 감지하면 토큰 유효성 검사를 실행합니다.

  • 토큰이 유효하면 bmctl에서 클러스터 작업에 이를 사용합니다.

  • 토큰이 유효하지 않으면 새 토큰을 가져옵니다.

    액세스 토큰은 수명이 짧으므로 클러스터 생성, 업그레이드, 재설정과 같은 클러스터 작업을 위해 bmctl 명령어를 실행하기 전에 재생성해야 합니다. 관리자 워크스테이션에서 새로 가져온 액세스 토큰으로 GCP_ACCESS_TOKEN 환경 변수를 업데이트합니다.

    1.33 이상 

    export GCP_ACCESS_TOKEN=$(gcloud auth application-default print-access-token)

    1.30-1.32 

    export GCP_ACCESS_TOKEN=$(gcloud auth print-access-token \
    --impersonate-service-account=admin-sa@PROJECT_ID.iam.gserviceaccount.com)

    기본적으로 액세스 토큰의 수명은 3, 600초 (1시간)입니다. 워크로드 아이덴티티 클러스터 인증을 사용하는 경우 bmctl는 토큰 만료 시간을 확인합니다. 토큰 만료가 1,800초 (30분) 이내인 경우 bmctl는 오류를 보고하고 종료됩니다.

맞춤설정

필요한 역할에 바인딩이 있는 한 워크로드 아이덴티티 클러스터 인증에 고유한 이름의 서비스 계정을 사용할 수 있습니다.

1.33 이상

기본적으로 버전 1.33 이상 클러스터의 워크로드 아이덴티티 클러스터 인증은 baremetal-gcr 서비스 계정만 사용합니다. 따라서 맞춤설정할 수 있는 서비스 계정은 이것뿐입니다.

  1. 사용하려는 서비스 계정에 시작하기 전에의 표에 명시된 역할이 있는지 확인합니다.

  2. 워크로드 아이덴티티 클러스터 인증 서비스 계정의 맞춤 이름을 지정하도록 클러스터 구성 파일에 주석을 추가합니다.

    apiVersion: baremetal.cluster.gke.io/v1
kind: Cluster
metadata:
  name: my-cluster
  namespace: cluster-my-cluster
  annotations:
    ...
    baremetal.cluster.gke.io/gcr-service-account: "CUSTOM_AR_GSA"
spec:
  type: admin
  profile: default
  anthosBareMetalVersion: 1.33.0-gke.799
  ...

CUSTOM_AR_GSA을 Google Distributed Cloud에서 Artifact Registry에서 컨테이너 이미지를 다운로드하는 데 사용하는 서비스 계정의 이메일 이름으로 바꿉니다.

1.30-1.32

  1. 사용하려는 서비스 계정에 시작하기 전에의 표에 명시된 역할이 있는지 확인합니다.

  2. 워크로드 아이덴티티 클러스터 인증 서비스 계정의 맞춤 이름을 지정하도록 클러스터 구성 파일에 주석을 추가합니다.

    맞춤 이름을 지정하면 기존 서비스 계정을 사용할 수 있습니다. 지정한 맞춤 서비스 계정 이름이 서로 다른지 확인합니다. 단일 서비스 계정을 사용하여 두 개 이상의 기본 서비스 계정을 대체하는 것은 지원되지 않습니다.

    apiVersion: baremetal.cluster.gke.io/v1
kind: Cluster
metadata:
  name: my-cluster
  namespace: cluster-my-cluster
  annotations:
    ...
    baremetal.cluster.gke.io/controller-service-account: "CUSTOM_CONTROLLER_GSA"
    baremetal.cluster.gke.io/cloud-ops-service-account: "CUSTOM_CLOUD_OPS_GSA"
    baremetal.cluster.gke.io/gcr-service-account: "CUSTOM_AR_GSA"
spec:
  type: admin
  profile: default
  anthosBareMetalVersion: 1.30.0-gke.1930
  ...

다음을 바꿉니다.

  • CUSTOM_CONTROLLER_GSA: Connect Agent가 클러스터와 Google Cloud간의 연결을 유지하고 클러스터를 등록하는 데 사용하는 서비스 계정의 이메일 이름

  • CUSTOM_CLOUD_OPS_GSA: Stackdriver Agent가 클러스터의 로그와 측정항목을 Cloud Logging 및 Cloud Monitoring으로 내보내는 데 사용하는 서비스 계정의 이메일 이름

  • CUSTOM_AR_GSA: Google Distributed Cloud가 Artifact Registry에서 컨테이너 이미지를 다운로드하는 데 사용하는 서비스 계정의 이메일 이름

제한사항

베어메탈용 Google Distributed Cloud (소프트웨어 전용)에 워크로드 아이덴티티 클러스터 인증을 사용하는 경우 다음 기능과 기능은 지원되지 않습니다.

  • 프록시 서버 사용
  • VPC 서비스 제어
  • 워크로드 아이덴티티 클러스터 인증을 사용하도록 기존 키 모드 클러스터 업데이트
  • GKE On-Prem API 클라이언트(예: Google Cloud CLI, Terraform 또는 Google Cloud 콘솔)를 사용한 클러스터 수명 주기 관리

다음 단계