GKE에서 워크로드 아이덴티티 사용 설정

이 주제에서는 GKE에서 Apigee Hybrid의 워크로드 아이덴티티를 사용 설정하는 방법을 설명합니다.

Apigee Hybrid AKS 또는 EKS를 사용하는 경우 AKS 및 EKS에서 워크로드 아이덴티티 제휴 사용 설정의 안내를 따르세요.

개요

워크로드 아이덴티티는 GKE(Google Kubernetes Engine) 내에서 실행되는 애플리케이션이 Google Cloud 서비스에 액세스하는 방법입니다. 워크로드 아이덴티티의 개요는 다음을 참조하세요.

• 워크로드 아이덴티티 소개: GKE 애플리케이션 인증 개선
• 워크로드 아이덴티티 사용

Google Cloud IAM 서비스 계정은 애플리케이션이 Google API에 요청을 수행하는 데 사용할 수 있는 ID입니다. 문서에서는 이러한 서비스 계정을 GSA(Google 서비스 계정)라고 합니다. GSA에 대한 자세한 내용은 서비스 계정을 참조하세요.

이와 별도로 Kubernetes에는 서비스 계정 개념도 있습니다. 서비스 계정은 포드에서 실행되는 프로세스의 ID를 제공합니다. Kubernetes 서비스 계정은 Kubernetes 리소스이고 Google 서비스 계정은 Google Cloud에만 해당됩니다. Kubernetes 서비스 계정에 대한 자세한 내용은 Kubernetes 문서의 포드의 서비스 계정 구성을 참조하세요.

Apigee는 각 구성 요소 유형에 대해 Helm 차트를 처음 설치할 때 Kubernetes 서비스 계정을 만들고 사용합니다. 워크로드 아이덴티티를 사용 설정하면 하이브리드 구성요소가 Kubernetes 서비스 계정과 상호작용할 수 있습니다.

이 절차에서 사용된 환경 변수

이 단계에서는 다음 환경 변수를 사용합니다. 명령어 셸에서 이들을 설정하거나 코드 샘플에서 실제 값으로 바꿉니다.

• CLUSTER_LOCATION: Kubernetes 클러스터의 리전 또는 영역(예: us-west1)
• CLUSTER_NAME: 클러스터 이름입니다.
• ENV_NAME: Apigee 환경의 이름
• ORG_NAME: Apigee 조직의 이름
• PROJECT_ID: Google Cloud 프로젝트의 ID
• NAMESPACE: Apigee 네임스페이스(일반적으로 'apigee')

환경 변수 확인:

echo $PROJECT_ID
echo $ORG_NAME
echo $ENV_NAME
echo $NAMESPACE
echo $CLUSTER_LOCATION
echo $CLUSTER_NAME
CLUSTER_NAME

필요한 변수 초기화:

export PROJECT_ID=my-project-id
export ORG_NAME=$PROJECT_ID
export ENV_NAME=my-environment-name
export NAMESPACE=apigee
export CLUSTER_LOCATION=my-cluster-location
export CLUSTER_NAME=hybrid-base-directory/apigeectl

워크로드 아이덴티티 및 서비스 계정 키 파일

GKE에서 Apigee Hybrid를 실행할 때 표준 방식은 각 서비스 계정의 비공개 키(.json 파일)를 만들고 다운로드하는 것입니다. 워크로드 아이덴티티를 사용할 때는 서비스 계정 비공개 키를 다운로드하고 GKE 클러스터에 추가할 필요가 없습니다.

Apigee Hybrid 설치의 일부로 서비스 계정 키 파일을 다운로드한 경우 워크로드 아이덴티티를 사용 설정한 후 삭제할 수 있습니다. 대부분의 설치에서는 각 구성요소 차트의 디렉터리에 있습니다.

Apigee Hybrid용 워크로드 아이덴티티 사용 설정

안내에 따라 프로젝트에 대해 워크로드 아이덴티티를 구성합니다.

마이그레이션된 설치 및 워크로드 아이덴티티

Apigee Hybrid Helm 마이그레이션 도구를 사용하여 apigeectl 관리에서 클러스터를 마이그레이션한 경우 워크로드 아이덴티티에 대한 재정의 구문이 변경되었을 것입니다. 재정의 파일에서 다음 속성을 확인해야 합니다.

• namespace 필드는 필수 항목입니다. 예를 들면 다음과 같습니다.

  instanceID: "hybrid-instance-1"
  namespace: "apigee"
  

• gcp.workloadIdentity.enabled 속성은 gcp.workloadIdentityEnabled 속성을 대체합니다. 예를 들면 다음과 같습니다.

  gcp:
    workloadIdentity:
      enabled: true

• 프로덕션 설치의 경우 각 구성요소에 gsa 속성이 있습니다. 이러한 속성 값은 해당 구성요소의 Google IAM 서비스 계정 이메일 주소입니다. 예를 들면 다음과 같습니다.

  watcher
    gsa: apigee-watcher@my-hybrid-project.iam.gserviceaccount.com
  

• 비프로덕션 설치의 경우 gcp.workloadIdentity.gsa 속성에 단일 GSA를 제공할 수 있습니다.

  gcp
    workloadIdentity
      gsa: apigee-watcher@my-hybrid-project.iam.gserviceaccount.com
  

• Apigee Hybrid용 Helm 차트를 사용하여 워크로드 아이덴티티의 프로덕션 및 비프로덕션 GSA를 함께 설치합니다. gcp.workloadIdentity.gsa 속성에 단일 항목을 지정하고 특정 구성요소에 개별 GSA를 지정할 수 있습니다. 개별 구성요소에 대한 제공 값은 gcp.workloadIdentity.gsa에 대한 제공 값의 해당 구성요소만 재정의합니다.

워크로드 아이덴티티 구성 준비

1. 재정의 파일에서 워크로드 아이덴티티가 사용 설정되었는지 확인합니다. 재정의 파일에서 사용 설정해야 하며 다음 구성 속성에 대한 값이 있어야 합니다.
   • 모든 설치에서 gcp.workloadIdentity.enabled는 true여야 합니다. 예를 들면 다음과 같습니다.

     gcp:
       workloadIdentity:
         enabled: true

   • 프로덕션 설치:
     • connectAgent.gsa
     • envs.gsa.runtime
     • envs.gsa.synchronizer
     • envs.gsa.udca
     • logger.gsa
     • mart.gsa
     • metrics.gsa
     • udca.gsa
     • watcher.gsa
   • 비프로덕션 설치의 경우 gcp.workloadIdentity.gsa 속성에 비프로덕션 GSA의 주소(필요한 모든 IAM 역할 포함)를 제공하세요.
2. 다음 명령어를 사용하여 현재 gcloud 구성이 Google Cloud 프로젝트 ID로 설정되었는지 확인합니다.

   gcloud config get project

필요한 경우 현재 gcloud 구성을 설정합니다.

gcloud config set project $PROJECT_ID

3. GKE 클러스터에 대한 워크로드 아이덴티티가 사용 설정되었는지 확인합니다. 1단계: 클러스터 만들기에서 클러스터를 만든 경우 6단계는 워크로드 아이덴티티를 사용 설정하는 것이었습니다. 다음 명령어를 실행하여 워크로드 아이덴티티가 사용 설정되었는지 확인할 수 있습니다.

   리전 클러스터

   gcloud container clusters describe $CLUSTER_NAME \
     --region $CLUSTER_LOCATION \
     --project $PROJECT_ID \
     --flatten 'workloadIdentityConfig'

   영역 클러스터

   gcloud container clusters describe $CLUSTER_NAME \
     --zone $CLUSTER_LOCATION \
     --project $PROJECT_ID \
     --flatten 'workloadIdentityConfig'

   다음과 유사하게 출력됩니다.

     ---
   workloadPool: PROJECT_ID.svc.id.goog

   결과에 null가 대신 표시되면 다음 명령어를 실행하여 클러스터에 대해 워크로드 아이덴티티를 사용 설정합니다.

   리전 클러스터

   gcloud container clusters update $CLUSTER_NAME \
     --workload-pool=$PROJECT_ID.svc.id.goog \
     --project $PROJECT_ID \
     --region $CLUSTER_LOCATION

   영역 클러스터

   gcloud container clusters update  $CLUSTER_NAME \
     --workload-pool=$PROJECT_ID.svc.id.goog \
     --zone $CLUSTER_LOCATION \
     --project $PROJECT_ID

4. 다음 명령어를 사용해서 각 노드 풀에 대해 워크로드 아이덴티티를 사용 설정합니다. 이 작업은 각 노드에 대해 최대 30분 정도 걸릴 수 있습니다.

   리전 클러스터

   gcloud container node-pools update NODE_POOL_NAME \
     --cluster=$CLUSTER_NAME \
     --region $CLUSTER_LOCATION \
     --project $PROJECT_ID \
     --workload-metadata=GKE_METADATA

   영역 클러스터

   gcloud container node-pools update NODE_POOL_NAME \
     --cluster=$CLUSTER_NAME \
     --zone $CLUSTER_LOCATION \
     --project $PROJECT_ID \
     --workload-metadata=GKE_METADATA

   여기서 NODE_POOL_NAME는 각 노드 풀의 이름입니다. 대부분의 Apigee Hybrid 설치에서 두 기본 노드 풀의 이름은 apigee-data 및 apigee-runtime입니다.

5. 다음 명령어를 사용해서 노드 풀에서 워크로드 아이덴티티가 사용 설정되었는지 확인합니다.

   리전 클러스터

   gcloud container node-pools describe apigee-data \
     --cluster $CLUSTER_NAME \
     --region $CLUSTER_LOCATION \
     --project $PROJECT_ID \
     --flatten "config:"

   gcloud container node-pools describe apigee-runtime \
     --cluster $CLUSTER_NAME \
     --region $CLUSTER_LOCATION \
     --project $PROJECT_ID \
     --flatten "config:"

   영역 클러스터

   gcloud container node-pools describe apigee-data \
     --cluster $CLUSTER_NAME \
     --zone $CLUSTER_LOCATION \
     --project $PROJECT_ID \
     --flatten "config:"

   gcloud container node-pools describe apigee-runtime \
     --cluster $CLUSTER_NAME \
     --zone $CLUSTER_LOCATION \
     --project $PROJECT_ID \
     --flatten "config:"

   다음과 비슷한 결과가 출력됩니다.

   ---
   diskSizeGb: 100
   diskType: pd-standard
   ...
   workloadMetadataConfig:
   mode: GKE_METADATA
     

워크로드 아이덴티티 구성

다음 하이브리드 구성요소에 대해 워크로드 아이덴티티를 사용 설정하려면 다음 절차를 따르세요.

• apigee-telemetry
• apigee-org
• apigee-env

apigee-datastore, apigee-env, apigee-org, apigee-telemetry 차트에 --dry-run 플래그를 사용하여 helm upgrade를 실행하면 올바른 GSA 및 KSA 이름으로 워크로드 아이덴티티를 구성하는 데 필요한 명령어가 출력에 포함됩니다.

예를 들면 다음과 같습니다.

helm upgrade datastore apigee-datastore/ \
  --namespace $NAMESPACE \
  -f overrides.yaml \
  --dry-run

NAME: datastore
...
For C* backup GKE Workload Identity, please make sure to add the below membership to the IAM policy binding using the respective kubernetes SA (KSA).
gcloud iam service-accounts add-iam-policy-binding  \
      --role roles/iam.workloadIdentityUser \
      --member "serviceAccount:my-project.svc.id.goog[apigee/apigee-cassandra-backup-sa]" \
      --project :my-project

1. apigee-datastore에 대해 워크로드 아이덴티티를 설정하는 명령어를 가져오고 출력에서 NOTES: 아래에 있는 명령어를 실행합니다.

   helm upgrade datastore apigee-datastore/ \
     --namespace $NAMESPACE \
     -f overrides.yaml \
     --dry-run

2. apigee-telemetry에 대해 워크로드 아이덴티티를 설정하는 명령어를 가져오고 출력에서 NOTES: 아래에 있는 명령어를 실행합니다.

   helm upgrade telemetry apigee-telemetry/ \
     --namespace $NAMESPACE \
     -f overrides.yaml \
     --dry-run

3. apigee-org에 대해 워크로드 아이덴티티를 설정하는 명령어를 가져오고 출력에서 NOTES: 아래에 있는 명령어를 실행합니다.

   helm upgrade $ORG_NAME apigee-org/ \
     --namespace $NAMESPACE \
     -f overrides.yaml \
     --dry-run

4. apigee-env에 대해 워크로드 아이덴티티를 설정하는 명령어를 가져오고 출력에서 NOTES: 아래에 있는 명령어를 실행합니다.

   helm upgrade $ENV_NAME apigee-env/ \
     --namespace $NAMESPACE \
     --set env=ENV_NAME \
     -f overrides.yaml \
     --dry-run

   설치의 각 환경에서 이 단계를 반복합니다.

워크로드 아이덴티티 확인

1. 단계가 올바른지 확인합니다.

   gcloud config set project $PROJECT_ID
   

   kubectl run --rm -it --image google/cloud-sdk:slim \
     --namespace $NAMESPACE workload-identity-test\
     -- gcloud auth list

   명령어 프롬프트가 보이지 않으면 Enter를 눌러 보세요.

   단계가 올바르게 실행되었다면 다음과 같은 응답이 표시되어야 합니다.

                      Credentialed Accounts
   ACTIVE  ACCOUNT
   *       GSA@PROJECT_ID.iam.gserviceaccount.com

2. 이전 설치에서 업그레이드하는 경우 서비스 계정 비공개 키가 포함된 보안 비밀을 삭제합니다.

   kubectl delete secrets -n $NAMESPACE $(k get secrets -n $NAMESPACE | grep svc-account | awk '{print $1}')
   

3. 로그 확인:

   kubectl logs -n $NAMESPACE -l app=apigee=synchronizer,env=$ENV_NAME,org=$ORG_NAME apigee-synchronizer
   

4. (선택사항) Google Cloud console의 Kubernetes: 워크로드 개요 페이지에서 Kubernetes 서비스 계정의 상태를 확인할 수 있습니다.

   워크로드로 이동