Kubernetes로 워크로드 아이덴티티 제휴 구성

이 가이드에서는 워크로드 아이덴티티 제휴를 사용하여 Azure Kubernetes Service(AKS), Amazon Elastic Kubernetes, Service, 자체 호스팅 Kubernetes 클러스터에서 실행되는 워크로드가 Google Cloud에 인증하도록 하는 방법을 설명합니다.

Kubernetes를 사용하면 워크로드가 예상 볼륨에서 Kubernetes 서비스 계정 토큰을 가져올 수 있도록 클러스터를 구성할 수 있습니다. 워크로드 아이덴티티 제휴를 설정하면 워크로드에서 이러한 Kubernetes 서비스 계정 토큰을 사용하여 Google Cloud에 인증할 수 있습니다.

GKE를 사용하는 경우 워크로드 아이덴티티 제휴를 구성하는 대신 워크로드 아이덴티티를 사용합니다.

시작하기 전에

워크로드 아이덴티티 제휴를 구성하기 전에 Kubernetes 클러스터가 다음 기준을 충족하는지 확인합니다.

AKS

클러스터가 다음 기준을 충족하는지 확인합니다.

OIDC 발급기관 기능을 사용 설정했습니다.

워크로드 아이덴티티 제휴에서 OpenID Connect 메타데이터 및 클러스터의 JSON 웹 키 집합(JWKS)에 액세스할 수 있도록 이 기능을 사용 설정해야 합니다.

EKS

EKS 구성은 변경할 필요가 없습니다.

Kubernetes

클러스터가 다음 기준을 충족하는지 확인합니다.

Kubernetes 1.20 이상이 실행되고 있습니다.

이전 버전의 Kubernetes는 이 문서의 안내와 호환되지 않는 다른 서비스 계정 토큰 형식을 사용했습니다.
ServiceAccount 토큰 볼륨 프로젝션을 지원하도록 kube-apiserver를 구성했습니다.

인터넷을 통해 클러스터에 액세스할 필요가 없습니다.

워크로드 아이덴티티 제휴 구성

Kubernetes 클러스터마다 이러한 단계를 한 번만 수행하면 됩니다. 그러면 여러 워크로드 포드와 여러 Google Cloud 프로젝트에서 같은 워크로드 아이덴티티 풀과 제공업체를 사용할 수 있습니다.

워크로드 아이덴티티 제휴 구성을 시작하려면 다음을 수행합니다.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

전용 프로젝트를 사용하여 워크로드 아이덴티티 풀과 제공업체를 관리

Make sure that billing is enabled for your Google Cloud project.

Enable the IAM, Resource Manager, Service Account Credentials, and Security Token Service APIs.

Enable the APIs

속성 매핑 및 조건 정의

Kubernetes 서비스 계정 토큰에는 다음을 포함한 여러 클레임이 있습니다.

sub: 서비스 계정의 네임스페이스와 이름을 포함합니다(예: system:serviceaccount:NAMESPACE:KSA_NAME). 여기서 NAMESPACE는 서비스 계정의 네임스페이스이고 KSA_NAME은 서비스 계정의 이름입니다.
"kubernetes.io".namespace: 서비스 계정의 네임스페이스를 포함합니다.
"kubernetes.io".serviceaccount.name: 서비스 계정의 이름을 포함합니다.
"kubernetes.io".pod.name: 포드의 이름을 포함합니다.

Google Cloud에서 sub를 주체 식별자(google.subject)로 사용하려면 다음 매핑을 사용합니다.

google.subject=assertion.sub

필요한 경우 추가 속성을 매핑할 수 있습니다. 그런 다음 리소스에 대한 액세스 권한을 부여할 때 이러한 속성을 참조할 수 있습니다. 예를 들면 다음과 같습니다.

google.subject=assertion.sub,
attribute.namespace=assertion['kubernetes.io']['namespace'],
attribute.service_account_name=assertion['kubernetes.io']['serviceaccount']['name'],
attribute.pod=assertion['kubernetes.io']['pod']['name']

선택적으로 속성 조건을 정의합니다. 속성 조건은 어설션 속성 및 대상 속성을 확인할 수 있는 CEL 표현식입니다. 어설션 조건이 특정 사용자 인증 정보에 대해 true로 평가되면 해당 사용자 인증 정보가 수락됩니다. 그렇지 않으면 사용자 인증 정보가 거부됩니다.

속성 조건을 사용하여 워크로드 아이덴티티 제휴를 사용해 단기 Google Cloud 토큰을 가져올 수 있는 Kubernetes 서비스 계정을 제한할 수 있습니다. 예를 들어 다음 조건은 backend 및 monitoring 네임스페이스에서 Kubernetes 서비스 계정에 대한 액세스를 제한합니다.

assertion['kubernetes.io']['namespace'] in ['backend', 'monitoring']

워크로드 아이덴티티 풀 및 공급업체 만들기

필요한 역할

워크로드 아이덴티티 제휴를 구성하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청합니다.

워크로드 아이덴티티 풀 관리자(roles/iam.workloadIdentityPoolAdmin)
서비스 계정 관리자(roles/iam.serviceAccountAdmin)

역할 부여에 대한 자세한 내용은 액세스 관리를 참조하세요.

커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

또는 IAM 소유자(roles/owner) 기본 역할에는 ID 제휴를 구성하는 권한도 포함됩니다. 프로덕션 환경에서는 기본 역할을 부여하지 말아야 하지만 개발 환경 또는 테스트 환경에서는 부여해도 됩니다.

워크로드 아이덴티티 풀과 제공업체를 만들려면 다음을 수행합니다.

AKS

AKS 클러스터의 발급기관 URL을 확인합니다.
```
az aks show -n NAME -g RESOURCE_GROUP --query "oidcIssuerProfile.issuerUrl" -otsv
```
다음을 바꿉니다.
- NAME: 클러스터 이름
- RESOURCE_GROUP: 클러스터의 리소스 그룹
이 명령어는 발급기관 URL을 출력합니다. 다음 단계 중 하나에서 발급기관 URL이 필요합니다.

명령어가 발급기관 URL을 반환하지 않으면 OIDC 발급기관 기능을 사용 설정했는지 확인합니다.
새 워크로드 아이덴티티 풀을 만듭니다.
```
gcloud iam workload-identity-pools create POOL_ID \
    --location="global" \
    --description="DESCRIPTION" \
    --display-name="DISPLAY_NAME"
```
다음을 바꿉니다.
- POOL_ID: 풀의 고유 ID
- DISPLAY_NAME: 풀 이름
- DESCRIPTION: 선택한 풀에 대한 설명 (이 설명은 풀 ID에 액세스 권한을 부여할 때 표시됩니다.)
AKS 클러스터를 워크로드 아이덴티티 풀 제공업체로 추가합니다.
```
gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
    --location="global" \
    --workload-identity-pool="POOL_ID" \
    --issuer-uri="ISSUER" \
    --attribute-mapping="MAPPINGS" \
    --attribute-condition="CONDITIONS"
```
다음을 바꿉니다.
- PROVIDER_ID: 선택한 고유 워크로드 아이덴티티 풀 공급업체 ID
- POOL_ID: 앞에서 만든 워크로드 아이덴티티 풀 ID
- ISSUER: 앞에서 확인한 발급기관 URI입니다.
- MAPPINGS: 이 가이드 앞부분에서 만든 쉼표로 구분된 속성 매핑의 목록
- CONDITIONS: 이 가이드 앞부분에서 만든 속성 조건(선택사항). 속성 조건이 없는 경우 매개변수를 삭제하세요.

EKS

EKS 클러스터의 발급기관 URL을 확인합니다.
```
aws eks describe-cluster --name NAME --query "cluster.identity.oidc.issuer" --output text
```
NAME을 클러스터 이름으로 바꿉니다.

이 명령어는 발급기관 URL을 출력합니다. 다음 단계 중 하나에서 발급기관 URL이 필요합니다.
새 워크로드 아이덴티티 풀을 만듭니다.
```
gcloud iam workload-identity-pools create POOL_ID \
    --location="global" \
    --description="DESCRIPTION" \
    --display-name="DISPLAY_NAME"
```
다음을 바꿉니다.
- POOL_ID: 풀의 고유 ID
- DISPLAY_NAME: 풀 이름
- DESCRIPTION: 선택한 풀에 대한 설명 (이 설명은 풀 ID에 액세스 권한을 부여할 때 표시됩니다.)
EKS 클러스터를 워크로드 아이덴티티 풀 제공업체로 추가합니다.
```
gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
    --location="global" \
    --workload-identity-pool="POOL_ID" \
    --issuer-uri="ISSUER" \
    --attribute-mapping="MAPPINGS" \
    --attribute-condition="CONDITIONS"
```
다음을 바꿉니다.
- PROVIDER_ID: 선택한 고유 워크로드 아이덴티티 풀 공급업체 ID
- POOL_ID: 앞에서 만든 워크로드 아이덴티티 풀 ID
- ISSUER: 앞에서 확인한 발급기관 URI입니다.
- MAPPINGS: 이 가이드 앞부분에서 만든 쉼표로 구분된 속성 매핑의 목록
- CONDITIONS: 이 가이드 앞부분에서 만든 속성 조건(선택사항). 속성 조건이 없는 경우 매개변수를 삭제하세요.

Kubernetes

Kubernetes 클러스터에 연결하고 kubectl을 사용하여 클러스터의 발급기관 URL을 확인합니다.
```
kubectl get --raw /.well-known/openid-configuration | jq -r .issuer
```
다음 단계 중 하나에서 발급기관 URL이 필요합니다.
클러스터의 JSON 웹 키 집합(JWKS)을 다운로드합니다.
```
kubectl get --raw /openid/v1/jwks > cluster-jwks.json
```
다음 단계 중 하나에서 워크로드 아이덴티티 제휴가 클러스터에서 발급한 Kubernetes 서비스 계정 토큰 신뢰성을 확인할 수 있도록 JWKS를 업로드합니다.
새 워크로드 아이덴티티 풀을 만듭니다.
```
gcloud iam workload-identity-pools create POOL_ID \
    --location="global" \
    --description="DESCRIPTION" \
    --display-name="DISPLAY_NAME"
```
다음을 바꿉니다.
- POOL_ID: 풀의 고유 ID
- DISPLAY_NAME: 풀 이름
- DESCRIPTION: 선택한 풀에 대한 설명 (이 설명은 풀 ID에 액세스 권한을 부여할 때 표시됩니다.)
Kubernetes 클러스터를 워크로드 아이덴티티 풀 제공업체로 추가하고 클러스터의 JWKS를 업로드합니다.
```
gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
    --location="global" \
    --workload-identity-pool="POOL_ID" \
    --issuer-uri="ISSUER" \
    --attribute-mapping="MAPPINGS" \
    --attribute-condition="CONDITIONS" \
    --jwk-json-path="cluster-jwks.json"
```
다음을 바꿉니다.
- PROVIDER_ID: 선택한 고유 워크로드 아이덴티티 풀 공급업체 ID
- POOL_ID: 앞에서 만든 워크로드 아이덴티티 풀 ID
- ISSUER: 앞에서 확인한 발급기관 URI입니다.
- MAPPINGS: 이 가이드 앞부분에서 만든 쉼표로 구분된 속성 매핑의 목록
- CONDITIONS: 이 가이드 앞부분에서 만든 속성 조건(선택사항). 속성 조건이 없는 경우 매개변수를 삭제하세요.
참고: 이 명령어는 클러스터의 JWKS 유효성을 검사하지 않습니다. JWKS의 형식이 잘못되었거나 만료되면 후속 인증 시도가 실패하고 오류 메시지 Error connecting to the given credential's issuer가 표시됩니다.

Kubernetes 워크로드 인증

이 섹션에서는 워크로드 아이덴티티 제휴를 사용하도록 Kubernetes 워크로드를 구성하는 방법을 설명합니다.

Google Cloud에 액세스해야 하는 Kubernetes 워크로드마다 이러한 단계를 한 번 수행해야 합니다.

서비스 계정 쌍 만들기

Kubernetes 워크로드가 Google Cloud에 인증하도록 하려면 서비스 계정 쌍이 필요합니다.

Kubernetes 포드에 연결하는 Kubernetes 서비스 계정입니다.
Kubernetes 워크로드에서 연결된 Kubernetes 서비스 계정을 사용하여 가장할 수 있는 IAM 서비스 계정입니다.

서비스 계정을 만들려면 다음을 수행합니다.

워크로드를 나타내는 IAM 서비스 계정을 만듭니다.

서비스 계정이 워크로드 아이덴티티 풀과 동일한 프로젝트에 있을 필요는 없습니다.
```
gcloud iam service-accounts create SA_NAME
```
다음을 바꿉니다.
- SA_NAME을 서비스 계정의 이름으로 바꿉니다.
Kubernetes 서비스 계정을 만듭니다.
```
kubectl create serviceaccount KSA_NAME --namespace NAMESPACE
```
다음을 바꿉니다.
- KSA_NAME을 서비스 계정의 이름으로 바꿉니다.
- NAMESPACE: 서비스 계정을 만들 네임스페이스입니다.
Kubernetes 워크로드에서 액세스할 리소스에 대한 IAM 서비스 계정 액세스 권한을 부여합니다.
Kubernetes 서비스 계정의 외부 ID에 대한 워크로드 아이덴티티 사용자 역할(roles/iam.workloadIdentityUser)을 부여합니다.
```
gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \
    --role=roles/iam.workloadIdentityUser \
    --member="principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT"
```
다음을 바꿉니다.
- SERVICE_ACCOUNT_EMAIL: 서비스 계정의 이메일 주소
- PROJECT_NUMBER: 워크로드 아이덴티티 풀이 포함된 프로젝트의 프로젝트 번호
- POOL_ID: 워크로드 아이덴티티 풀의 ID
- SUBJECT: google.subject에 매핑한 속성의 예상 값(예: system:serviceaccount:NAMESPACE:KSA_NAME)
참고: 구성원 식별자에 프로젝트 번호를 사용해야 합니다. 프로젝트 ID 사용은 지원되지 않습니다.

Kubernetes 워크로드 배포

이제 Kubernetes 워크로드를 배포하고 서비스 계정 쌍을 사용하도록 허용합니다.

사용자 인증 정보 구성 파일을 만듭니다.
```
gcloud iam workload-identity-pools create-cred-config \
    projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID \
    --service-account=SERVICE_ACCOUNT_EMAIL \
    --credential-source-file=/var/run/service-account/token \
    --credential-source-type=text \
    --output-file=credential-configuration.json
```
다음을 바꿉니다.
- PROJECT_NUMBER: 워크로드 아이덴티티 풀이 포함된 프로젝트의 프로젝트 번호
- POOL_ID: 워크로드 아이덴티티 풀의 ID
- PROVIDER_ID: 워크로드 아이덴티티 풀 공급업체의 ID
- SERVICE_ACCOUNT_EMAIL: 서비스 계정의 이메일 주소
사용자 인증 정보 구성 파일을 사용하면 Cloud 클라이언트 라이브러리, gcloud CLI, Terraform에서 다음을 확인할 수 있습니다.
- 외부 사용자 인증 정보를 가져올 위치
- 사용할 워크로드 아이덴티티 풀 및 공급업체
- 가장할 서비스 계정
참고: 서비스 계정 키와 달리 사용자 인증 정보 구성 파일에는 비공개 키가 포함되지 않으며 기밀로 유지할 필요가 없습니다. https://google.aip.dev/auth/4117에서 사용자 인증 정보 구성 파일에 대한 세부정보를 제공합니다.
사용자 인증 정보 구성 파일을 ConfigMap으로 가져옵니다.
```
kubectl create configmap CONFIGMAP_NAME \
  --from-file credential-configuration.json \
  --namespace NAMESPACE
```
다음을 바꿉니다.
- CONFIGMAP_NAME: ConfigMap 이름입니다.
- NAMESPACE: ConfigMap을 만들 네임스페이스입니다.
워크로드를 배포하고 Kubernetes 서비스 계정과 ConfigMap을 사용하도록 합니다.

매니페스트를 만들고 다음과 같이 구성합니다.
- 워크로드가 로컬 파일에서 Kubernetes 서비스 계정 토큰을 가져올 수 있도록 예상 토큰 볼륨을 마운트합니다. Kubernetes 서비스 계정 토큰이 워크로드 아이덴티티 제휴 풀 제공업체에서 예상하는 대상을 사용하도록 볼륨을 구성합니다.
- 워크로드가 워크로드 아이덴티티 제휴 사용을 위해 필요한 구성에 액세스할 수 있도록 사용자 인증 정보 구성 파일이 포함된 ConfigMap을 마운트합니다.
- 워크로드에서 파일을 찾을 수 있도록 사용자 인증 정보 구성 파일의 경로가 포함된 GOOGLE_APPLICATION_CREDENTIALS 환경 변수를 추가합니다.
다음은 Kubernetes 서비스 계정과 ConfigMap을 사용하여 Google Cloud CLI가 Google Cloud에 인증하도록 하는 매니페스트 예시입니다.
```
apiVersion: v1
kind: Pod
metadata:
  name: example
  namespace: NAMESPACE
spec:
  containers:
  - name: example
    image: google/cloud-sdk:alpine
    command: ["/bin/sh", "-c", "gcloud auth login --cred-file $GOOGLE_APPLICATION_CREDENTIALS && gcloud auth list && sleep 600"]
    volumeMounts:
    - name: token
      mountPath: "/var/run/service-account"
      readOnly: true
    - name: workload-identity-credential-configuration
      mountPath: "/etc/workload-identity"
      readOnly: true
    env:
    - name: GOOGLE_APPLICATION_CREDENTIALS
      value: "/etc/workload-identity/credential-configuration.json"

  serviceAccountName: KSA_NAME
  volumes:
  - name: token
    projected:
      sources:
      - serviceAccountToken:
          audience: https://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID
          expirationSeconds: 3600
          path: token
  - name: workload-identity-credential-configuration
    configMap:
      name: CONFIGMAP_NAME
```
다음 클라이언트 라이브러리 중 하나를 사용하는 도구와 워크로드에서 자동으로 사용자 인증 정보를 찾을 수 있도록 같은 방법을 사용할 수 있습니다.
C++
C++용 Google Cloud 클라이언트 라이브러리는 버전 v2.6.0부터 워크로드 아이덴티티 제휴를 지원합니다. 워크로드 아이덴티티 제휴를 사용하려면 gRPC 버전 1.36.0 이상을 사용하여 클라이언트 라이브러리를 빌드해야 합니다.
Go
Go용 클라이언트 라이브러리에서 golang.org/x/oauth2 모듈 버전 v0.0.0-20210218202405-ba52d332ba99 이상을 사용하면 ID 제휴가 지원됩니다.

클라이언트 라이브러리에서 사용하는 이 모듈 버전을 확인하려면 다음 명령어를 실행합니다.
```
cd $GOPATH/src/cloud.google.com/go
go list -m golang.org/x/oauth2
```
Java
Java용 클라이언트 라이브러리에서 com.google.auth:google-auth-library-oauth2-http 아티팩트 버전 0.24.0 이상을 사용하면 ID 제휴가 지원됩니다.

클라이언트 라이브러리에서 사용하는 이 아티팩트의 버전을 확인하려면 애플리케이션 디렉터리에서 다음 Maven 명령어를 실행합니다.
```
mvn dependency:list -DincludeArtifactIds=google-auth-library-oauth2-http
```
Node.js
Node.js용 클라이언트 라이브러리에서 google-auth-library 패키지 버전 7.0.2 이상을 사용하면 워크로드 아이덴티티 제휴가 지원됩니다.

클라이언트 라이브러리에서 사용하는 이 패키지의 버전을 확인하려면 애플리케이션 디렉터리에서 다음 명령어를 실행합니다.
```
npm list google-auth-library
```
GoogleAuth 객체를 만들 때 프로젝트 ID를 지정하거나 GoogleAuth가 프로젝트 ID를 자동으로 찾도록 허용할 수 있습니다. 프로젝트 ID를 자동으로 찾으려면 구성 파일의 서비스 계정에 프로젝트에 대한 브라우저 역할(roles/browser) 또는 동등한 권한이 있는 역할이 있어야 합니다. 자세한 내용은 google-auth-library 패키지용 README를 참조하세요.
Python
Python용 클라이언트 라이브러리에서 google-auth 패키지 버전 1.27.0 이상을 사용하면 ID 제휴가 지원됩니다.

클라이언트 라이브러리에서 사용하는 이 패키지의 버전을 확인하려면 패키지가 설치된 환경에서 다음 명령어를 실행합니다.
```
pip show google-auth
```
인증 클라이언트의 프로젝트 ID를 지정하려면 GOOGLE_CLOUD_PROJECT 환경 변수를 설정하거나 클라이언트가 프로젝트 ID를 자동으로 찾도록 허용할 수 있습니다. 프로젝트 ID를 자동으로 찾으려면 구성 파일의 서비스 계정에 프로젝트에 대한 브라우저 역할(roles/browser) 또는 동등한 권한이 있는 역할이 있어야 합니다. 자세한 내용은 google-auth 패키지 사용자 가이드를 참조하세요.
gcloud
워크로드 아이덴티티 제휴를 사용하여 인증하려면 gcloud auth login 명령어를 사용합니다.
```
gcloud auth login --cred-file=FILEPATH.json
```
FILEPATH를 사용자 인증 정보 구성 파일의 파일 경로로 바꿉니다.

gcloud CLI에서 워크로드 아이덴티티 제휴는 gcloud CLI 버전 363.0.0 이상에서 지원됩니다.
Terraform
버전 3.61.0 이상을 사용하는 경우 Google Cloud 공급업체가 워크로드 아이덴티티 제휴를 지원합니다.
```
terraform {
  required_providers {
    google = {
      source  = "hashicorp/google"
      version = "~> 3.61.0"
    }
  }
}
```
gsutil
워크로드 아이덴티티 제휴를 사용하여 인증하려면 다음 방법 중 하나를 사용합니다.

gcloud와 함께 gsutil을 사용하는 경우 평소처럼 로그인합니다.
```
gcloud auth login --cred-file=FILEPATH.json
```
gsutil을 독립형 명령줄 애플리케이션으로 사용하는 경우 다음 섹션을 포함하도록 .boto 파일을 수정합니다.
```
[Credentials]
gs_external_account_file = FILEPATH
```
두 경우 모두 FILEPATH를 사용자 인증 정보 구성 파일의 파일 경로로 바꿉니다.

gsutil에서 워크로드 아이덴티티 제휴는 gcloud CLI 버전 379.0.0 이상에서 지원됩니다.
bq
워크로드 아이덴티티 제휴를 사용하여 인증하려면 다음과 같이 gcloud auth login 명령어를 사용합니다.
```
gcloud auth login --cred-file=FILEPATH.json
```
FILEPATH를 사용자 인증 정보 구성 파일의 파일 경로로 바꿉니다.

bq에서 워크로드 아이덴티티 제휴는 gcloud CLI 버전 390.0.0 이상에서 지원됩니다.
선택적으로 다음 명령어를 실행하여 인증이 올바르게 작동하는지 확인합니다.
```
kubectl exec example --namespace NAMESPACE -- gcloud auth print-access-token
```

Kubernetes로 워크로드 아이덴티티 제휴 구성

시작하기 전에

AKS

EKS

Kubernetes

워크로드 아이덴티티 제휴 구성

속성 매핑 및 조건 정의

워크로드 아이덴티티 풀 및 공급업체 만들기

필요한 역할

AKS

EKS

Kubernetes

Kubernetes 워크로드 인증

서비스 계정 쌍 만들기

Kubernetes 워크로드 배포

C++

Go

Java

Node.js

Python

gcloud

Terraform

gsutil

bq

다음 단계