Fleet 워크로드 아이덴티티 사용

애플리케이션은 다른 서비스에 연결할 때 인증(인증 가능한 ID 제공)해야 하는 경우가 많습니다. 예를 들어 Compute Engine 또는 AI Platform API와 같은 Google Cloud API를 사용하려면 애플리케이션에서 인증해야 합니다. 이 페이지에서는 Fleet에서 호스팅되는 애플리케이션 워크로드가 Google Cloud API 및 서비스를 인증하는 데 권장되는 가장 간단한 방법인 Fleet 워크로드 아이덴티티를 사용하는 방법을 설명합니다.

Fleet 워크로드 아이덴티티란 무엇인가요?

Fleet 워크로드 아이덴티티는 GKE 워크로드 아이덴티티에 제공되는 기능을 확장하므로 클러스터의 워크로드가 Google Cloud 서비스 계정 키를 다운로드하고 수동으로 순환하지 않고도 Google에 인증할 수 있습니다. 대신 클러스터에서 생성된 단기 토큰을 사용하여 워크로드가 인증을 수행합니다. GKE 워크로드 아이덴티티가 사용 설정된 모든 클러스터는 ID를 발급할 때 프로젝트의 워크로드 아이덴티티 풀을 사용하여, Identity and Access Management가 Kubernetes 서비스 계정 사용자 인증 정보를 신뢰하고 이해할 수 있게 해줍니다. GKE 워크로드 아이덴티티에 대한 자세한 내용은 워크로드 아이덴티티 사용을 참조하세요.

Fleet를 사용하면 등록된 클러스터가 Fleet 워크로드 아이덴티티 사용에 따른 추가 이점을 얻을 수 있습니다. 해당 Fleet 멤버십에서 워크로드 아이덴티티가 사용 설정된 등록된 클러스터는 Fleet 전체의 Fleet 워크로드 아이덴티티 풀을 사용하여, 해당 Fleet 및 여러 프로젝트 간에 Google API 및 기타 서비스에 대한 인증을 더 쉽게 설정할 수 있게 해줍니다. 또한 Fleet 워크로드 아이덴티티는 일부 클러스터 유형의 Connect Agent에서 Fleet 멤버십의 일부로 Google에 인증을 수행하기 위해 사용될 수 있으며, Anthos Service Mesh와 같이 프로젝트 간에 작동하는 일부 GKE Enterprise 기능을 사용하기 위해 필요합니다.

작동 방식

Fleet은 워크로드 아이덴티티 제휴를 사용하여 각 애플리케이션에 Google Cloud 및 사용자가 개발하는 기타 서비스에 인증하는 데 사용할 수 있는 고유한 제휴 ID를 제공합니다. Fleet에서 실행되는 애플리케이션에는 다음과 같은 형식의 제휴 워크로드 아이덴티티가 적용됩니다.

serviceAccount:FLEET_PROJECT_ID.svc.id.goog[K8S_NAMESPACE/KSA_NAME]

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

FLEET_PROJECT_ID.svc.id.goog는 Fleet의 워크로드 아이덴티티 풀의 약식입니다. Fleet당 고정된 워크로드 아이덴티티 풀이 단 한 개 있으며 이는 자동으로 생성됩니다.
K8S_NAMESPACE는 Kubernetes 서비스 계정이 정의된 Kubernetes 네임스페이스입니다.
KSA_NAME은 애플리케이션에 연결된 Kubernetes 서비스 계정의 이름입니다.

Fleet에서 호스팅되는 모든 애플리케이션은 동일한 워크로드 아이덴티티 풀을 공유하여 각 애플리케이션이 호스팅되는 위치를 추상화하는 제휴 ID를 제공합니다. 이렇게 하면 애플리케이션이 Google Cloud 프로젝트 또는 여러 클라우드에 배포되더라도 Fleet 내의 애플리케이션에 리소스(예: Google Cloud API)에 대한 액세스 권한을 클러스터별이 아니라 한 번만 제공할 수 있습니다. 다른 Fleet 지원 기능과 마찬가지로 이는 서로 다른 클러스터에서 동일한 이름을 가진 Kubernetes 객체가 동일한 것으로 취급되는 동일성의 Fleet 원칙을 따릅니다. 예를 들어 동일한 Fleet의 여러 클러스터에 배포된 백엔드가 있는 애플리케이션이 있으며 Google API에 인증해야 하는 경우 '백엔드' 네임 스페이스의 모든 서비스가 해당 API에 액세스할 수 있도록 애플리케이션을 쉽게 구성할 수 있습니다. ID 동일성을 비롯하여 Fleet이 동일성을 사용하는 방법에 대한 자세한 내용은 Fleet 작동 방식을 참조하세요.

Google Cloud 외부 클러스터는 또한 Fleet 워크로드 아이덴티티를 사용하여 Google 인증을 위해 Connect Agent에 대해 ID를 제공할 수 있습니다. Fleet 워크로드 아이덴티티를 사용하는 클러스터 유형에 대한 자세한 내용은 아래 클러스터 설정 섹션을 참조하세요.

시작하기 전에

다음 명령줄 도구가 설치되었는지 확인합니다.
- 최신 버전의 Google Cloud CLI(Google Cloud와의 상호작용을 위한 명령줄 도구인 gcloud 포함).
- kubectl
Google Cloud와의 상호작용을 위해 Cloud Shell을 셸 환경으로 사용하는 경우 이러한 도구가 자동으로 설치됩니다.
프로젝트에 사용할 수 있도록 gcloud CLI를 초기화했는지 확인합니다.

클러스터 설정

Fleet의 애플리케이션이 워크로드 아이덴티티를 수신하려면 먼저 실행되는 클러스터가 Fleet에 등록되어 있어야 하며 Fleet 워크로드 아이덴티티를 사용하도록 올바르게 구성되어야 합니다. 이 작업은 클러스터 유형에 따라 달라집니다. Google Cloud 외부의 대부분의 GKE 클러스터는 생성 시 프로젝트 Fleet에 자동으로 등록됩니다. Google Cloud의 GKE 클러스터 및 연결된 클러스터는 수동으로 등록되어야 합니다.

클러스터 구성에 대한 자세한 내용은 각 클러스터 유형별 문서를 참조하세요.

GKE

Google Kubernetes Engine 클러스터에서 아직 사용 설정되지 않았으면 GKE 워크로드 아이덴티티를 사용 설정합니다.
안내에 따라 워크로드 아이덴티티를 사용하여 클러스터를 등록합니다.

Google Cloud 외부의 GKE 클러스터

VMware용 GKE, 베어메탈용 GKE, 멀티 클라우드 GKE 클러스터(AWS 및 Azure 모두)는 클러스터의 생성 시간에 프로젝트 Fleet에 자동으로 등록됩니다. GKE Enterprise 1.8부터 이러한 클러스터 유형은 등록 시 Fleet 워크로드 아이덴티티가 자동으로 사용 설정됩니다. 기존에 등록된 클러스터는 GKE Enterprise 1.8 이상으로 업그레이드되면 워크로드 아이덴티티를 사용하도록 업데이트됩니다.

연결된 클러스터

GKE Multi-Cloud API를 사용하여 등록된 EKS 및 AKS 연결 클러스터는 기본적으로 Fleet 워크로드 아이덴티티를 사용하도록 설정된 상태로 등록됩니다. 연결된 다른 클러스터는 필요한 요구사항을 충족하는 경우에만 사용 설정된 Fleet 워크로드 아이덴티티로 등록됩니다. 클러스터 등록에서 해당 클러스터 유형에 대한 안내를 따르세요.

Fleet 워크로드 아이덴티티 사용

클러스터를 등록한 후 클러스터에 배포된 워크로드는 Fleet 워크로드 아이덴티티 풀의 워크로드 아이덴티티를 사용할 수 있습니다. 이 섹션에서는 워크로드 아이덴티티가 Google Cloud API에 액세스할 수 있도록 워크로드 아이덴티티를 사용하여 Google Cloud 서비스 계정을 가장하는 방법을 보여줍니다. 서비스 계정 역할을 하는 것은 제휴 ID의 일반적인 사용 사례입니다. 이를 통해 워크로드는 서비스 계정이 액세스할 수 있는 Google Cloud API에 인증할 수 있으므로 각 워크로드의 서비스 계정 키의 유지보수와 보안을 관리해야 하는 부담이 사라집니다.

서비스 계정 가장하기

이 섹션에서는 관련 권한을 사용하여 서비스 계정을 만들고 구성하는 등 ConfigMap에 애플리케이션 기본 사용자 인증 정보 파일을 제공하여 애플리케이션의 제휴 워크로드 아이덴티티를 서비스 계정으로 가장하도록 구성하는 방법을 보여줍니다.

이 예시에서는 다음 자리표시자 값을 사용합니다.

WORKLOAD_IDENTITY_POOL은 Fleet과 연결된 워크로드 아이덴티티 풀입니다. 위에 표시된 것처럼 WORKLOAD_IDENTITY_POOL 값은 FLEET_PROJECT_ID.svc.id.goog입니다.
IDENTITY_PROVIDER는 Kubernetes 클러스터와 연결된 ID 공급업체의 이름입니다.
K8S_NAMESPACE는 Kubernetes 서비스 계정이 정의된 Kubernetes 네임스페이스입니다.
KSA_NAME은 애플리케이션에 연결된 Kubernetes 서비스 계정의 이름입니다.
GSA_NAME은 애플리케이션이 역할을 수행할 Google 서비스 계정의 이름입니다.
GSA_PROJECT_ID는 Google 서비스 계정이 정의된 프로젝트 ID입니다.

서비스 계정을 가장하도록 Fleet 워크로드 아이덴티티를 구성하려면 다음 안내를 따르세요.

위의 클러스터 설정 섹션의 단계에 따라 클러스터가 Fleet에 등록되었는지 확인합니다.
다음 명령어를 사용하여 클러스터의 Fleet 멤버십 세부정보를 검색하여 등록된 클러스터의 WORKLOAD_IDENTITY_POOL 및 IDENTITY_PROVIDER 값을 가져옵니다. MEMBERSHIP을 클러스터의 고유한 멤버십 이름으로 바꿉니다.
```
gcloud container fleet memberships describe MEMBERSHIP
```
멤버십을 설명하는 출력은 다음과 같습니다(명확성을 위해 일부 필드는 생략됨).
```
authority:
 identityProvider: IDENTITY_PROVIDER
 workloadIdentityPool: WORKLOAD_IDENTITY_POOL
name: projects/FLEET_PROJECT_ID/locations/global/memberships/MEMBERSHIP
```
Google에 인증할 때 애플리케이션에서 가장할 수 있는 Google Cloud 서비스 계정이 없는 경우 계정을 만듭니다.
```
gcloud iam service-accounts create GSA_NAME --project=GSA_PROJECT_ID
```
서비스 계정은 Fleet 호스트 프로젝트 내에 있을 필요는 없습니다. 조직의 모든 Google Cloud 서비스 계정을 사용할 수 있습니다. 서비스 계정에서 서비스 계정 및 서비스 계정의 작동 방식을 자세히 알아볼 수 있습니다.
필요한 IAM 정책 binding을 추가하여 Google Cloud API에 액세스하는 데 필요한 모든 권한을 서비스 계정에 부여했는지 확인합니다. gcloud iam service-accounts add-iam-policy-binding을 사용하거나 필요에 따라 다른 방법을 사용하여 이 작업을 수행할 수 있습니다. 각 서비스의 문서에서 Google Cloud API를 사용하는 데 필요한 권한을 알아보고 역할 이해에서 필수 권한이 있는 사전 정의된 역할의 전체 목록을 살펴보세요.
다음과 같이 IAM 정책 binding을 만들어 애플리케이션의 워크로드 아이덴티티가 서비스 계정을 가장하도록 승인합니다. 이 binding을 사용하면 애플리케이션의 제휴 워크로드 아이덴티티가 Google Cloud 서비스 계정 역할을 할 수 있습니다.
```
gcloud iam service-accounts add-iam-policy-binding \
  GSA_NAME@GSA_PROJECT_ID.iam.gserviceaccount.com \
  --role=roles/iam.workloadIdentityUser \
  --member="serviceAccount:WORKLOAD_IDENTITY_POOL[K8S_NAMESPACE/KSA_NAME]"
```
--member 필드는 애플리케이션의 제휴 워크로드 아이덴티티를 IAM에서 표현한 것입니다.
워크로드의 애플리케이션 기본 사용자 인증 정보 파일이 포함된 ConfigMap을 만듭니다. 이 파일은 워크로드에 컴파일되는 클라이언트 라이브러리에 Google에 인증하는 방법을 알려줍니다. 애플리케이션 기본 사용자 인증 정보 파일에는 관련성이 높은 워크로드 아이덴티티 풀, 서비스 계정 정보 및 다음 단계에서 컨테이너의 파일 시스템에 마운트할 예상 토큰에 대한 경로가 포함됩니다. GSA_NAME@GSA_PROJECT_ID.iam.gserviceaccount.com은 가장하려는 서비스 계정의 이메일 주소입니다.

이 구성만으로는 서비스 계정을 가장할 수 있는 액세스 권한이 부여되지 않습니다. IAM binding도 존재하지 않으면 Pod가 서비스 계정을 사용할 수 없습니다.
```
kind: ConfigMap
apiVersion: v1
metadata:
  namespace: K8S_NAMESPACE
  name: my-cloudsdk-config
data:
  config: |
    {
      "type": "external_account",
      "audience": "identitynamespace:WORKLOAD_IDENTITY_POOL:IDENTITY_PROVIDER",
      "service_account_impersonation_url": "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/GSA_NAME@GSA_PROJECT_ID.iam.gserviceaccount.com:generateAccessToken",
      "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
      "token_url": "https://sts.googleapis.com/v1/token",
      "credential_source": {
        "file": "/var/run/secrets/tokens/gcp-ksa/token"
      }
    }
```

워크로드를 구성하려면 아래 예시를 따르세요. 이전 단계의 ConfigMap은 /var/run/secrets/tokens/gcp-ksa에 예상 서비스 계정 토큰 파일과 함께 컨테이너의 파일 시스템에 google-application-credentials.json으로 마운트됩니다. 예상 토큰은 Kubernetes에 의해 발급되며 클러스터 내부의 워크로드 아이덴티티를 나타냅니다. 이러한 토큰은 Cloud 클라이언트 라이브러리에서 Google과 자동으로 교환하여 Google API로 인증할 수 있는 토큰을 얻습니다. 예상 토큰의 audience 필드는 WORKLOAD_IDENTITY_POOL 값으로 설정되어야 합니다.

kind: Namespace
apiVersion: v1
metadata:
  name:  K8S_NAMESPACE
---
kind: ServiceAccount
apiVersion: v1
metadata:
  namespace:  K8S_NAMESPACE
  name: KSA_NAME
automountServiceAccountToken: false
---
apiVersion: v1
kind: Pod
metadata:
  name: my-pod
  namespace:  K8S_NAMESPACE
spec:
  serviceAccountName: KSA_NAME
  containers:
  - name: my-container
    image: my-image
    env:
      - name: GOOGLE_APPLICATION_CREDENTIALS
        value: /var/run/secrets/tokens/gcp-ksa/google-application-credentials.json
    volumeMounts:
    - name: gcp-ksa
      mountPath: /var/run/secrets/tokens/gcp-ksa
      readOnly: true
  volumes:
  - name: gcp-ksa
    projected:
      defaultMode: 420
      sources:
      - serviceAccountToken:
          path: token
          audience: WORKLOAD_IDENTITY_POOL
          expirationSeconds: 172800
      - configMap:
          name: my-cloudsdk-config
          optional: false
          items:
            - key: "config"
              path: "google-application-credentials.json"

코드에서 인증

Cloud 클라이언트 라이브러리를 사용하여 코드에서 Google 서비스에 액세스할 때 Google Cloud에 대한 인증을 자동으로 처리합니다. 애플리케이션에서 위에 표시된 설정을 사용하려면 워크로드 아이덴티티 제휴를 지원하는 Cloud 클라이언트 라이브러리를 사용해야 합니다. 다음은 필요한 최소 Cloud 클라이언트 라이브러리 버전과 현재 버전을 확인하는 방법에 대한 안내입니다.

C++

대부분의 C++용 Google Cloud 클라이언트 라이브러리는 grpc::GoogleDefaultCredentials()를 호출하여 생성된 ChannelCredentials 객체를 사용해 ID 제휴를 지원합니다. 이 사용자 인증 정보를 초기화하려면 클라이언트 라이브러리를 gRPC 버전 1.36.0 이상으로 빌드해야 합니다.

C++용 Cloud Storage 클라이언트 라이브러리는 gRPC가 아닌 REST API를 사용하므로 ID 제휴를 지원하지 않습니다.

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

자바용 클라이언트 라이브러리에서 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 이상을 사용하면 ID 제휴가 지원됩니다.

클라이언트 라이브러리에서 사용하는 이 패키지의 버전을 확인하려면 애플리케이션 디렉터리에서 다음 명령어를 실행합니다.

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 패키지 사용자 가이드를 참조하세요.