Google Cloud의 GKE 클러스터 기본 요건

Google Cloud에서 GKE 클러스터를 등록하는 경우에는 선택한 등록 옵션에 따라 클러스터를 등록하기 전 다음 중 하나 이상을 수행해야 할 수 있습니다. 이 가이드에서는 클러스터 등록을 위한 일반 기본 요건을 이미 완료했다고 가정합니다.

GKE용 워크로드 아이덴티티 제휴 사용 설정

클러스터의 애플리케이션에서 일관된 Google Cloud API 및 서비스 인증 방법을 제공하도록 Fleet 워크로드 아이덴티티 제휴가 사용 설정된 GKE 클러스터를 등록하는 것이 좋습니다. Fleet 워크로드 아이덴티티 제휴를 사용 설정할 때의 이점은 Fleet 워크로드 아이덴티티 제휴 사용을 참조하세요.

이 기능을 사용하려면 등록하기 전에 클러스터에 GKE용 워크로드 아이덴티티 제휴가 사용 설정되어 있는지 확인해야 합니다. 클러스터에서 GKE용 워크로드 아이덴티티 제휴를 사용 설정하지 않고 Fleet 워크로드 아이덴티티 제휴를 사용하여 GKE 클러스터를 등록하면 클러스터에서 워크로드로 ID가 어설션되는 방식에 불일치가 발생할 수 있으며, 지원되는 구성이 아닙니다. Autopilot 클러스터에는 기본적으로 GKE용 워크로드 아이덴티티 제휴가 사용 설정되어 있습니다.

gcloud

클러스터에 GKE용 워크로드 아이덴티티 제휴가 사용 설정되었는지 확인하려면 다음 명령어를 실행하여 클러스터의 워크로드 아이덴티티 풀을 나열합니다. gcloud의 기본 영역 또는 리전을 아직 지정하지 않았으면 이 명령어를 실행할 때 --region 또는 --zone 플래그를 지정해야 합니다.

gcloud container clusters describe CLUSTER_NAME --format="value(workloadIdentityConfig.workloadPool)"

다음을 바꿉니다.

CLUSTER_NAME: GKE 클러스터의 name

다음과 유사한 결과가 표시되면 클러스터에 GKE용 워크로드 아이덴티티 제휴가 이미 사용 설정된 것입니다.

GKE_PROJECT_ID.svc.id.goog

결과가 없으면 GKE용 워크로드 아이덴티티 제휴가 사용 설정되지 않은 것입니다. GKE용 워크로드 아이덴티티 제휴 사용 설정의 안내를 따릅니다.

Console

클러스터에 GKE용 워크로드 아이덴티티 제휴가 사용 설정되었는지 확인하려면 다음 안내를 따르세요.

Google Cloud 콘솔에서 Google Kubernetes Engine 페이지로 이동합니다.

Google Kubernetes Engine으로 이동
클러스터 목록에서 클러스터 이름을 클릭합니다.
클러스터 세부정보 페이지의 보안 섹션에서 워크로드 아이덴티티가 사용 설정됨으로 나열되었는지 확인합니다.

워크로드 아이덴티티가 사용 중지됨이고 이 기능을 사용 설정하려면 다음 안내를 따르세요.

클러스터 세부정보 페이지에서 워크로드 아이덴티티 수정을 클릭합니다.
워크로드 아이덴티티 수정 대화상자에서 워크로드 아이덴티티 사용 설정 체크박스를 선택합니다.
변경사항 저장을 클릭합니다.

다른 프로젝트에 클러스터 등록을 위한 권한 부여

고유 프로젝트에 있는 fleet에 GKE 클러스터를 등록할 때는 액세스 권한 부여에 설명된 것 이상의 특별한 권한이 필요하지 않습니다. 고유 프로젝트(GKE_PROJECT)에서 다른 프로젝트(FLEET_HOST_PROJECT)의 Fleet에 GKE 클러스터를 등록하려면 FLEET_HOST_PROJECT 서비스 에이전트 계정 gcp-sa-gkehub에 GKE_PROJECT 프로젝트의 gkehub.serviceAgent 역할이 있어야 합니다. 이 역할은 서비스 계정에 해당 프로젝트의 클러스터 리소스 관리 권한을 부여합니다.

다음과 같이 gcloud CLI 또는 Google Cloud Console을 사용하여 Fleet 호스트 프로젝트 gcp-sa-gkehub 서비스 계정에 클러스터 프로젝트의 필수 역할이 포함되었는지 확인할 수 있습니다.

gcloud

다음 명령어를 실행합니다.

gcloud projects get-iam-policy GKE_PROJECT_ID | grep gcp-sa-gkehub

여기서 GKE_PROJECT_ID는 클러스터 프로젝트의 ID입니다.

Fleet 호스트 프로젝트 gcp-sa-gkehub에 클러스터 프로젝트의 필수 역할이 있으면 service-[FLEET_HOST-PROJECT-NUMBER]@gcp-sa-gkehub.iam.gserviceaccount.com 형식의 출력에 표시됩니다. 예를 들면 다음과 같습니다.

- members:
  - serviceAccount:service-1234567890@gcp-sa-gkehub.iam.gserviceaccount.com
  role: roles/gkehub.serviceAgent

콘솔

클러스터 프로젝트가 선택된 상태로 Google Cloud Console에서 IAM 및 관리자 페이지로 이동합니다.

IAM 및 관리자 페이지로 이동
Google 제공 역할 부여 포함 체크박스를 선택하여 서비스 에이전트를 포함한 전체 허용 정책을 확인합니다.

Fleet 호스트 프로젝트 서비스 계정 gcp-sa-gkehub에 클러스터 프로젝트의 필수 역할이 있으면 service-[FLEET_HOST-PROJECT-NUMBER]@gcp-sa-gkehub.iam.gserviceaccount.com 형식의 이 목록에 표시됩니다.

프로젝트의 IAM 허용 정책에 서비스 에이전트가 나열되지 않았으면 다음을 수행하여 필요한 권한을 업데이트합니다.

gcloud

gcp-sa-gkehub에 gkehub.serviceAgent 역할을 부여하려면 먼저 이 서비스 계정이 Fleet 호스트 프로젝트에 있는지 확인합니다. 이전에 이 Fleet 프로젝트의 클러스터를 등록한 경우 이 서비스 계정이 이미 있어야 합니다. Fleet 호스트 프로젝트의 IAM 허용 정책을 통해 확인할 수 있습니다.
```
gcloud projects get-iam-policy FLEET_HOST_PROJECT_ID | grep gcp-sa-gkehub
```

gcp-sa-gkehub 서비스 계정을 만들어야 하면 다음 명령어를 실행합니다.

gcloud beta services identity create --service=gkehub.googleapis.com --project=FLEET_HOST_PROJECT_ID

이 명령어는 다음을 출력합니다.

Service identity created: service-[FLEET_HOST_PROJECT_NUMBER]@gcp-sa-gkehub.iam.gserviceaccount.com

다음 명령어를 실행하여 서비스 계정에 두 프로젝트 모두에서 roles/gkehub.serviceAgent 역할, 클러스터 프로젝트에서 roles/gkehub.crossProjectServiceAgent 역할을 부여합니다.

GKE_PROJECT_ID=GKE_PROJECT_ID
FLEET_HOST_PROJECT_ID=FLEET_HOST_PROJECT_ID
FLEET_HOST_PROJECT_NUMBER=$(gcloud projects describe "${FLEET_HOST_PROJECT_ID}" --format "value(projectNumber)")
gcloud projects add-iam-policy-binding "${FLEET_HOST_PROJECT_ID}" \
  --member "serviceAccount:service-${FLEET_HOST_PROJECT_NUMBER}@gcp-sa-gkehub.iam.gserviceaccount.com" \
  --role roles/gkehub.serviceAgent
gcloud projects add-iam-policy-binding "${GKE_PROJECT_ID}" \
  --member "serviceAccount:service-${FLEET_HOST_PROJECT_NUMBER}@gcp-sa-gkehub.iam.gserviceaccount.com" \
  --role roles/gkehub.serviceAgent
gcloud projects add-iam-policy-binding "${GKE_PROJECT_ID}" \
  --member "serviceAccount:service-${FLEET_HOST_PROJECT_NUMBER}@gcp-sa-gkehub.iam.gserviceaccount.com" \
  --role roles/gkehub.crossProjectServiceAgent

각 매개변수는 다음과 같습니다.

GKE_PROJECT_ID는 GKE 클러스터의 Google Cloud 프로젝트 ID입니다.
FLEET_HOST_PROJECT_ID는 클러스터를 등록할 Google Cloud 프로젝트 ID입니다. 이 값을 찾는 방법을 알아보세요.

역할 결합이 부여되었는지 확인하려면 다음 명령어를 다시 실행합니다.

gcloud projects get-iam-policy GKE_PROJECT_ID

gkehub.serviceAgent 및 gkehub.crossProjectServiceAgent 역할과 함께 서비스 계정 이름이 표시되면 역할 바인딩이 부여된 것입니다. 예를 들면 다음과 같습니다.

- members:
  - serviceAccount:service-[FLEET_HOST_PROJECT_NUMBER]@gcp-sa-gkehub.iam.gserviceaccount.com
  role: roles/gkehub.serviceAgent
- members:
  - serviceAccount:service-[FLEET_HOST_PROJECT_NUMBER]@gcp-sa-gkehub.iam.gserviceaccount.com
  role: roles/gkehub.crossProjectServiceAgent

Terraform용 서비스 계정 구성

Terraform을 사용하여 Google Kubernetes Engine 클러스터를 등록하려면 Terraform이 멤버십을 생성하기 위해 Fleet API에 액세스하는 데 사용할 수 있는 서비스 계정을 만들어야 합니다.

gcloud

다음과 같이 서비스 계정을 만듭니다.

gcloud iam service-accounts create SERVICE_ACCOUNT_NAME --project=FLEET_HOST_PROJECT_ID

Terraform이 Fleet API에 사용할 수 있도록 gkehub.admin IAM 역할을 서비스 계정에 결합합니다.
```
FLEET_HOST_PROJECT_ID=FLEET_HOST_PROJECT_ID
gcloud projects add-iam-policy-binding ${FLEET_HOST_PROJECT_ID} \
   --member="serviceAccount:SERVICE_ACCOUNT_NAME@${FLEET_HOST_PROJECT_ID}.iam.gserviceaccount.com" \
   --role="roles/gkehub.admin"
```
Terraform으로 새 클러스터를 만든 후 이를 등록하려면 또한 Terraform이 서비스 계정을 사용하여 클러스터를 만들기 위해 GKE API에 액세스할 수 있도록 서비스 계정에 roles/container.admin 역할을 결합해야 합니다.
```
FLEET_HOST_PROJECT_ID=FLEET_HOST_PROJECT_ID
gcloud projects add-iam-policy-binding ${FLEET_HOST_PROJECT_ID} \
   --member="serviceAccount:SERVICE_ACCOUNT_NAME@${FLEET_HOST_PROJECT_ID}.iam.gserviceaccount.com" \
   --role="roles/container.admin"
```
다음을 바꿉니다.
- FLEET_HOST_PROJECT_ID는 클러스터를 등록할 Google Cloud 프로젝트 ID입니다. 이 값을 찾는 방법을 알아보세요.
- SERVICE_ACCOUNT_NAME은 [서비스 계정]에 선택한 표시 이름입니다.
gcloud를 사용하여 Google Cloud 서비스 계정 만들기에 설명된 대로 서비스 계정의 비공개 키 JSON 파일을 다운로드합니다. Terraform을 사용하여 클러스터를 만들고 등록하려면 이 파일이 필요합니다.

Config Connector를 위한 서비스 계정 구성

Config Connector를 사용하여 GKE 클러스터를 등록하려면 다음을 수행합니다.

gcloud

Config Connector 부가기능이 설치되었는지 확인합니다. Config Connector 버전이 1.47.0 이후여야 합니다.
Config Connector 안내에 따라 서비스 계정을 만듭니다.
Config Connector가 이 서비스 계정을 사용하여 Fleet API에 액세스할 수 있도록 gkehub.admin IAM 역할을 이 서비스 계정에 결합합니다.
```
FLEET_HOST_PROJECT_ID=FLEET_HOST_PROJECT_ID
gcloud projects add-iam-policy-binding ${FLEET_HOST_PROJECT_ID} \
   --member="serviceAccount:SERVICE_ACCOUNT_NAME@${FLEET_HOST_PROJECT_ID}.iam.gserviceaccount.com" \
   --role="roles/gkehub.admin"
```
구성 커넥터로 새 클러스터를 만든 후 이를 등록하려면 또한 구성 커넥터 컨트롤러가 이 서비스 계정을 사용하여 클러스터를 만들기 위해 GKE API에 액세스할 수 있도록 서비스 계정에 roles/container.admin 역할을 binding해야 합니다.
```
FLEET_HOST_PROJECT_ID=FLEET_HOST_PROJECT_ID
gcloud projects add-iam-policy-binding ${FLEET_HOST_PROJECT_ID} \
   --member="serviceAccount:SERVICE_ACCOUNT_NAME@${FLEET_HOST_PROJECT_ID}.iam.gserviceaccount.com" \
   --role="roles/container.admin"
```
다음을 바꿉니다.
- FLEET_HOST_PROJECT_ID는 클러스터를 등록할 Google Cloud 프로젝트 ID입니다. 이 값을 찾는 방법을 알아보세요.
- SERVICE_ACCOUNT_NAME은 [서비스 계정]에 선택한 표시 이름입니다.
구성 커넥터 안내에 따라 이 서비스 계정으로 구성 커넥터를 구성합니다.

다음 단계

안내에 따라 클러스터 등록하기