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

현재 Apigee Hybrid 문서의 1.8 버전을 보고 있습니다. This version is end of life. You should upgrade to a newer version. 자세한 내용은 지원되는 버전을 참조하세요.

Version 1.8 (unsupported)

지원되는 버전:

• v1.12(최신 버전)                        
• v1.11                         
• v1.10                                        
• 지원되는 버전 목록

지원되지 않는 버전:

• v1.9                                         
• v1.8                                         
• v1.7                                         
• v1.6                                         
• v1.5                                         
• v1.4                                         
• v1.3                                         
• v1.2                                         
• v1.1                                         

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

개요

워크로드 아이덴티티는 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 Hybrid 1.4 이상을 사용하면 Apigee는 각 유형의 구성요소에 대해 Kubernetes 서비스 계정을 만들고 사용합니다. 워크로드 아이덴티티를 사용 설정하면 하이브리드 구성요소가 Kubernetes 서비스 계정과 상호작용할 수 있습니다.

기본 요건

Apigee Hybrid용 워크로드 아이덴티티를 사용 설정하려면 먼저 Apigee를 실행하는 GKE 클러스터에 워크로드 아이덴티티가 사용 설정되어 있어야 합니다.

Anthos Service Mesh(ASM)의 안내를 따랐다면 워크로드 아이덴티티는 이미 클러스터에 사용 설정되어 있을 것입니다.

다음 명령어를 실행하여 워크로드 아이덴티티가 사용 설정되었는지 확인할 수 있습니다.

gcloud container clusters describe $CLUSTER_NAME

출력이 다음과 비슷하게 표시되어야 합니다.

…
…
status: RUNNING
subnetwork: default
workloadIdentityConfig:
  workloadPool: PROJECT_ID.svc.id.goog

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

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

시작하려면 워크로드 아이덴티티 사용 설정 준비의 안내에 따라 워크로드 아이덴티티를 사용 설정하기 전에 노드 풀을 업데이트하고 변수를 초기화하세요.

그런 다음 수행하는 단계에 따라 다음 섹션 중 하나를 따릅니다.

• 새로 설치할 때 워크로드 아이덴티티 사용 설정. 새로 Apigee Hybrid를 설치하거나, Hybrid 설치에 아직 ASM을 설치하지 않은 경우 다음 안내를 따르세요.
• 워크로드 아이덴티티를 사용하도록 설치 업그레이드 다음 안내에 따라 기존 Apigee Hybrid 설치에서 워크로드 아이덴티티를 사용 설정하세요.

워크로드 아이덴티티 사용 설정 준비

설치 프로세스를 시작하기 전에 이 섹션의 단계를 따르세요.

변수 초기화

다음 변수를 초기화(또는 확인)합니다.

export PROJECT_ID=my-project-id
export ORG_NAME=$PROJECT_ID
export ENV_NAME=my-environment-name
export NAMESPACE=apigee #the namespace where apigee is installed

프로젝트를 수정 중인 프로젝트로 설정합니다.

gcloud config set project $PROJECT_ID

노드 풀 업데이트

다음 명령어를 사용하여 노드 풀별로 워크로드 아이덴티티가 사용 설정되어 있는지 확인합니다.

gcloud container node-pools update $NODE_POOL_NAME \
  --cluster=$CLUSTER_NAME \
  --workload-metadata=GKE_METADATA

새로 설치할 때 워크로드 아이덴티티 사용 설정

새 하이브리드 설치 중에 워크로드 아이덴티티를 사용 설정할 때 다음 안내를 따르세요.

1. 아래의 굵게 표시된 줄을 gcp 스탠자 아래의 overrides.yaml 파일에 추가합니다.

   gcp:
     projectID: "my-project"
     name: "my-project"
     region: "us-west1"
     workloadIdentityEnabled: true

2. Google 서비스 계정을 만듭니다. 다음과 같은 두 가지 방법을 사용할 수 있습니다.
   • create-service-account 도구를 사용하여 다음 명령어로 구성요소별로 Google 서비스 계정을 만듭니다.

     $APIGEECTL_HOME/tools/create-service-account --env prod --dir $APIGEECTL_HOME/../service-accounts

     이 명령어는 다음 서비스 계정을 만듭니다.

     • apigee-logger
     • apigee-metrics
     • apigee-cassandra
     • apigee-udca
     • apigee-synchronizer
     • apigee-mart
     • apigee-watcher
     • apigee-distributed-trace

     다음 안내에서는 create-service-account 도구를 사용하여 서비스 계정을 생성했다고 가정합니다.

   • 환경별 커스텀 이름 지정 규칙 및 서비스 계정을 정의합니다(고급 사용자용).
3. Kubernetes 서비스 계정을 만듭니다.

   조직 수준 구성요소의 경우:

   • Cassandra

     kubectl create sa -n $NAMESPACE apigee-cassandra-schema-setup-$(apigeectl encode --org $ORG_NAME)-sa \
       && kubectl label sa -n $NAMESPACE -l app=apigee-cassandra,org=$ORG_NAME \
       && kubectl annotate serviceaccount \
       --namespace $NAMESPACE apigee-cassandra-schema-setup-$(apigeectl encode --org $ORG_NAME)-sa iam.gke.io/gcp-service-account=GSA_NAME@$PROJECT_ID.iam.gserviceaccount.com

     kubectl create sa -n $NAMESPACE apigee-cassandra-user-setup-$(apigeectl encode --org $ORG_NAME)-sa \
       && kubectl label sa -n $NAMESPACE -l app=apigee-cassandra,org=$ORG_NAME \
       && kubectl annotate serviceaccount \
       --namespace $NAMESPACE apigee-cassandra-user-setup-$(apigeectl encode --org $ORG_NAME)-sa iam.gke.io/gcp-service-account=GSA_NAME@$PROJECT_ID.iam.gserviceaccount.com

   • MART

     kubectl create sa -n $NAMESPACE apigee-mart-$(apigeectl encode --org $ORG_NAME)-sa \
       && kubectl label sa -n $NAMESPACE -l app=apigee-mart,org=$ORG_NAME \
       && kubectl annotate serviceaccount \
       --namespace $NAMESPACE apigee-mart-$(apigeectl encode --org $ORG_NAME)-sa iam.gke.io/gcp-service-account=GSA_NAME@$PROJECT_ID.iam.gserviceaccount.com

   • Apigee Connect

     kubectl create sa -n $NAMESPACE apigee-connect-$(apigeectl encode --org $ORG_NAME)-sa \
       && kubectl label sa -n $NAMESPACE -l app=apigee-connect,org=$ORG_NAME \
       && kubectl annotate serviceaccount \
       --namespace $NAMESPACE apigee-connect-$(apigeectl encode --org $ORG_NAME)-sa iam.gke.io/gcp-service-account=GSA_NAME@$PROJECT_ID.iam.gserviceaccount.com
     

   • Apigee Watcher

     kubectl create sa -n $NAMESPACE apigee-watcher-$(apigeectl encode --org $ORG_NAME)-sa \
       && kubectl label sa -n $NAMESPACE -l app=apigee-watcher,org=$ORG_NAME \
       && kubectl annotate serviceaccount \
       --namespace $NAMESPACE apigee-watcher-$(apigeectl encode --org $ORG_NAME)-sa iam.gke.io/gcp-service-account=GSA_NAME@$PROJECT_ID.iam.gserviceaccount.com

   • Apigee 측정항목

     kubectl create sa -n $NAMESPACE apigee-metrics-sa \
       && kubectl label sa -n $NAMESPACE -l app=apigee-metrics,org=$ORG_NAME \
       && kubectl annotate serviceaccount \
       --namespace $NAMESPACE apigee-metrics-sa iam.gke.io/gcp-service-account=GSA_NAME@$PROJECT_ID.iam.gserviceaccount.com

   환경별로 다음을 수행합니다.

   참고: GSA_NAME이 구성요소와 일치하는지 확인하세요. 아래 안내에서 GSA_NAME은 환경 변수가 아닙니다.
   • 런타임

     kubectl create sa -n $NAMESPACE apigee-runtime-$(apigeectl encode --org $ORG_NAME --env $ENV_NAME)-sa \
       && kubectl label sa -n $NAMESPACE -l app=apigee-runtime,org=$ORG_NAME,env=$ENV_NAME \
       && kubectl annotate serviceaccount \
       --namespace $NAMESPACE apigee-runtime-$(apigeectl encode --org $ORG_NAME --env $ENV_NAME)-sa iam.gke.io/gcp-service-account=GSA_NAME@$PROJECT_ID.iam.gserviceaccount.com

   • UDCA

     kubectl create sa -n $NAMESPACE apigee-udca-$(apigeectl encode --org $ORG_NAME --env $ENV_NAME)-sa \
       && kubectl label sa -n $NAMESPACE -l app=apigee-udca,org=$ORG_NAME,emv=$ENV_NAME \
       && kubectl annotate serviceaccount \
       --namespace $NAMESPACE apigee-udca-$(apigeectl encode --org $ORG_NAME --env $ENV_NAME)-sa iam.gke.io/gcp-service-account=GSA_NAME@$PROJECT_ID.iam.gserviceaccount.com

   • 동기화 담당자

     kubectl create sa -n $NAMESPACE apigee-synchronizer-$(apigeectl encode --org $ORG_NAME --env $ENV_NAME)-sa \
       && kubectl label sa -n $NAMESPACE -l app=apigee-synchronizer,org=$ORG_NAME,env=$ENV_NAME \
       && kubectl annotate serviceaccount \
       --namespace $NAMESPACE apigee-synchronizer-$(apigeectl encode --org $ORG_NAME --env $ENV_NAME)-sa iam.gke.io/gcp-service-account=GSA_NAME@$PROJECT_ID.iam.gserviceaccount.com

4. 평소와 같이 Apigee Hybrid를 계속 설치합니다.

워크로드 아이덴티티를 사용하도록 설치 업그레이드

기존 하이브리드 설치에 워크로드 아이덴티티를 추가하려면 다음 안내를 따르세요.

다음은 Apigee용으로 생성된 Google 서비스 계정(GSA)을 보여주는 샘플입니다.

gcloud iam service-accounts list | grep apigee

apigee-connect   apigee-connect@$PROJECT_ID.iam.gserviceaccount.com    False
apigee-runtime   apigee-runtime@$PROJECT_ID.iam.gserviceaccount.com    False
apigee-metrics   apigee-metrics@$PROJECT_ID.iam.gserviceaccount.com    False
apigee-mart      apigee-mart@$PROJECT_ID.iam.gserviceaccount.com       False
apigee-watcher   apigee-watcher@$PROJECT_ID.iam.gserviceaccount.com    False
apigee-sync      apigee-sync@$PROJECT_ID.iam.gserviceaccount.com       False
apigee-udca      apigee-udca@$PROJECT_ID.iam.gserviceaccount.com       False

다음은 Apigee용으로 생성된 샘플 Kubernetes 서비스 계정(KSA)입니다(Apigee Hybrid 1.4 이상이 설치되어 있다고 가정).

kubectl get sa -n $NAMESPACE

apigee-cassandra-schema-setup-ORG_NAME-cb84b88-sa                1         xxd
apigee-cassandra-user-setup-ORG_NAME-cb84b88-sa                  1         xxd
apigee-connect-agent-ORG_NAME-cb84b88-sa                         1         xxd
apigee-init                                                        1         xxd
apigee-mart-ORG_NAME-cb84b88-sa                                  1         xxd
apigee-metrics-apigee-telemetry                                    1         xxd
apigee-runtime-ORG_NAME-ENV_NAME-1d0dc5e-sa                    1         xxd
apigee-synchronizer-ORG_NAME-ENV_NAME-1d0dc5e-sa               1         xxd
apigee-udca-ORG_NAME-ENV_NAME-1d0dc5e-sa                       1         xxd
apigee-watcher-ORG_NAME-cb84b88                                  1         xxd

각 항목의 의미: ORG_NAME 및 ENV_NAME은 조직 및 환경 이름의 짧은 버전일 수 있습니다.

1. 각 서비스 계정에 워크로드 아이덴티티 역할을 추가합니다.

   gcloud iam service-accounts add-iam-policy-binding \
     --role roles/iam.workloadIdentityUser \
     --member "serviceAccount:$PROJECT_ID.svc.id.goog[$NAMESPACE/$KSA_NAME]" \
     GSA_NAME@$PROJECT_ID.iam.gserviceaccount.com
   

   예를 들어 Apigee 동기화 담당자에 대한 권한을 설정한 경우 다음을 실행합니다.

   export KSA_NAME=$(kubectl get sa -n apigee -l app=apigee-synchronizer,env=$ENV_NAME,org=$ORG_NAME --output=jsonpath={.items..metadata.name})
   

   gcloud iam service-accounts add-iam-policy-binding --role roles/iam.workloadIdentityUser --member "serviceAccount:$PROJECT_ID.svc.id.goog[apigee/$KSA_NAME]" apigee-sync@$PROJECT_ID.iam.gserviceaccount.com
   

2. 각 KSA에 GSA 세부정보를 주석으로 추가합니다.

   kubectl annotate serviceaccount \
     --namespace $NAMESPACE \
     $KSA_NAME \
    iam.gke.io/gcp-service-account=GSA_NAME@$PROJECT_ID.iam.gserviceaccount.com
   

   예를 들어 Apigee 동기화 담당자에 대한 권한을 설정한 경우 다음을 실행합니다.

   export KSA_NAME=$(kubectl get sa -n apigee -l app=apigee-synchronizer,env=$ENV_NAME,org=$ORG_NAME --output=jsonpath={.items..metadata.name})
   

   kubectl annotate serviceaccount --namespace $NAMESPACE $KSA_NAME iam.gke.io/gcp-service-account=apigee-sync@$PROJECT_ID.iam.gserviceaccount.com
   

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

   gcloud config set project $PROJECT_ID
   

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

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

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

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

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

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

5. 로그를 확인합니다.

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