AKS 및 EKS에서 워크로드 아이덴티티 제휴 사용 설정

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

GKE에 설치하는 경우 GKE에서 워크로드 아이덴티티 사용 설정의 안내를 따르세요.

개요

워크로드 아이덴티티 제휴를 사용하면 Google Cloud 외부에서 실행되는 애플리케이션이 외부 ID 공급업체의 사용자 인증 정보를 사용하여 Google Cloud Platform 서비스 계정을 가장할 수 있습니다.

워크로드 아이덴티티 제휴를 사용하면 외부 환경에서 제공되는 인증 메커니즘을 애플리케이션에 사용함으로써 보안을 향상시키는 데 도움이 될 수 있고 서비스 계정 키 교체가 가능합니다.

개요는 워크로드 아이덴티티 제휴 사용 권장사항을 참조하세요.

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

Apigee Hybrid에서 워크로드 아이덴티티 제휴를 사용하려면 먼저 클러스터를 구성한 후 Apigee Hybrid 설치에 기능을 적용합니다.

시작하기 전에

이 안내에서는 이미 Apigee Hybrid 설치를 설정했다고 가정합니다. IAM 서비스 계정과 Kubernetes 서비스 계정은 초기 설치 중에 생성됩니다. Apigee Hybrid 설치 개요는 개요를 참조하세요.

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

워크로드 아이덴티티 제휴를 사용하도록 클러스터 구성

  1. 다음 명령어를 사용하여 현재 gcloud 구성이 Google Cloud 프로젝트 ID로 설정되었는지 확인합니다.
    gcloud config get project
  2. 필요한 경우 현재 gcloud 구성을 설정합니다.

    gcloud config set project PROJECT_ID
  3. 보안 토큰 서비스 API를 사용 설정합니다.

    다음 명령어를 사용하여 보안 토큰 서비스 API가 사용 설정되어 있는지 확인합니다.

    gcloud services list --enabled --project PROJECT_ID | grep sts.googleapis.com

    API가 사용 설정되지 않은 경우에는 다음 안내를 따르세요.

    콘솔

    Enable the Security Token Service API.

    Enable the API

    명령줄

    다음 명령어를 사용하여 API를 사용 설정합니다.

    gcloud services enable sts.googleapis.com --project PROJECT_ID
  4. 워크로드 아이덴티티 풀과 제공업체를 만듭니다.

    필요한 역할

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

    역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

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

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

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

    1. AKS 클러스터의 발급기관 URL을 확인합니다.

      AKS

      az aks show -n NAME -g RESOURCE_GROUP --query "oidcIssuerProfile.issuerUrl" -otsv

      다음을 바꿉니다.

      • NAME: 클러스터의 이름입니다.
      • RESOURCE_GROUP: 클러스터의 리소스 그룹입니다.

      이 명령어는 발급기관 URL을 출력합니다. 다음 단계 중 하나에서 발급기관 URL이 필요합니다.

      명령어에서 발급기관 URL을 반환하지 않으면 OIDC 발급기관 기능을 사용 설정했는지 확인합니다.

      EKS

      aws eks describe-cluster --name NAME --query "cluster.identity.oidc.issuer" --output text
      

      NAME을 클러스터 이름으로 바꿉니다.

      이 명령어는 발급기관 URL을 출력합니다. 다음 단계 중 하나에서 발급기관 URL이 필요합니다.

      기타 Kubernetes

      1. Kubernetes 클러스터에 연결하고 `kubectl`을 사용하여 클러스터 발급기관 URL을 확인합니다.
        kubectl get --raw /.well-known/openid-configuration | jq -r .issuer
        

        다음 단계 중 하나에서 발급기관 URL이 필요합니다.

    2. 선택사항: OIDC 발급자가 공개적으로 액세스할 수 없으면 클러스터의 JSON 웹 키 집합(JWKS)을 다운로드합니다.
      kubectl get --raw /openid/v1/jwks > cluster-jwks.json
      

      OIDC 제공업체를 공개적으로 사용할 수 있는지 확인하려면 CURL 명령어로 제공업체 URL에 액세스하여 200 응답을 수신할 수 있어야 합니다.

    3. 새 워크로드 아이덴티티 풀을 만듭니다.
      gcloud iam workload-identity-pools create POOL_ID \
        --location="global" \
        --description="DESCRIPTION" \
        --display-name="DISPLAY_NAME"
                  

      다음을 바꿉니다.

      • POOL_ID: 풀의 고유 ID
      • DISPLAY_NAME: (선택사항) 풀 이름
      • DESCRIPTION: (선택사항) 선택한 풀에 대한 설명. 이 설명은 풀 ID에 대한 액세스 권한을 부여할 때 표시됩니다.

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

      gcloud iam workload-identity-pools create my-wi-pool --display-name="My workload pool" --description="My workload pool description"
    4. 클러스터를 워크로드 아이덴티티 풀 제공업체로 추가합니다. OIDC 발급기관에 공개적으로 액세스 가능한지 또는 공개적으로 액세스 불가능한지에 따라 제공업체를 만드는 명령어를 선택합니다.

      공개적으로 액세스 가능

      OIDC 발급기관에 공개적으로 액세스할 수 있으면 다음 명령어를 사용하여 제공업체를 만듭니다.

      gcloud iam workload-identity-pools providers create-oidc WORKLOAD_PROVIDER_ID \
        --location="global" \
        --workload-identity-pool="POOL_ID" \
        --issuer-uri="ISSUER" \
        --attribute-mapping="google.subject=assertion.sub"

      공개적으로 액세스 불가능

      OIDC 발급기관에 공개적으로 액세스할 수 없으면 다음 명령어를 사용하여 제공업체를 만듭니다.

        gcloud iam workload-identity-pools providers create-oidc WORKLOAD_PROVIDER_ID \
        --location="global" \
        --workload-identity-pool="POOL_ID" \
        --issuer-uri="ISSUER" \
        --jwks-file="cluster-jwks.json" \
        --attribute-mapping="google.subject=assertion.sub"

      다음을 바꿉니다.

      • WORKLOAD_PROVIDER_ID: 선택한 고유 워크로드 아이덴티티 풀 제공업체 ID
      • POOL_ID: 앞에서 만든 워크로드 아이덴티티 풀 ID
      • ISSUER: 앞에서 확인한 발급기관 URL을 발급기관 URI로 사용합니다.

      attribute-mapping="google.subject=assertion.sub"는 Kubernetes 주체를 IAM 주체에 매핑합니다.

사용자 인증 정보 구성 파일 만들기

Google Cloud 리소스에 액세스할 수 있는 Kubernetes 워크로드를 배포하려면 먼저 IAM 서비스 계정마다 사용자 인증 정보 구성 파일을 만들어야 합니다.

  1. 다음 명령어를 사용하여 IAM 서비스 계정('Google 서비스 계정'이라고도 함)을 표시합니다.
    gcloud iam service-accounts list --project PROJECT_ID

    다음 IAM 서비스 계정의 사용자 인증 정보 구성 파일을 만들어야 합니다.

    프로덕션

    프로덕션 환경의 경우:

    DISPLAY NAME         EMAIL                                                      DISABLED
    apigee-cassandra     apigee-cassandra@my_project_id.iam.gserviceaccount.com     False
    apigee-mart          apigee-mart@my_project_id.iam.gserviceaccount.com          False
    apigee-metrics       apigee-metrics@my_project_id.iam.gserviceaccount.com       False
    apigee-runtime       apigee-runtime@my_project_id.iam.gserviceaccount.com       False
    apigee-synchronizer  apigee-synchronizer@my_project_id.iam.gserviceaccount.com  False
    apigee-udca          apigee-udca@my_project_id.iam.gserviceaccount.com          False
    apigee-watcher       apigee-watcher@my_project_id.iam.gserviceaccount.com       False
    

    비프로덕션

    비프로덕션 환경의 경우:

    DISPLAY NAME         EMAIL                                                      DISABLED
    apigee-non-prod      apigee-non-prod@my_project_id.iam.gserviceaccount.com      False
    
  2. 이전 목록에 있는 IAM 서비스 계정마다 사용자 인증 정보 구성 파일을 만듭니다. Apigee Hybrid에서 워크로드 아이덴티티 제휴를 사용하도록 구성하려면 다음 사용자 인증 정보 구성 파일이 필요합니다.

    코드

    gcloud iam workload-identity-pools create-cred-config \
      projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/WORKLOAD_PROVIDER_ID \
      --service-account=SERVICE_ACCOUNT_EMAIL \
      --credential-source-file=/var/
      --credential-source-type=text \
      --output-file=SERVICE_ACCOUNT_NAME-credential-configuration.json
      

    gcloud iam workload-identity-pools create-cred-config \
      projects/123123123123/locations/global/workloadIdentityPools/my-wi-pool/providers/my-wi-provider \
      --service-account=apigee-cassandra@myhybridporg.iam.gserviceaccount.com \
      --credential-source-file=/var/
      --credential-source-type=text \
      --output-file=apigee-cassandra-credential-configuration.json
      

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

    • PROJECT_NUMBER: 워크로드 아이덴티티 풀이 포함된 프로젝트의 프로젝트 번호. 프로젝트 ID가 아닌 프로젝트 번호여야 합니다.
    • POOL_ID: 워크로드 아이덴티티 풀의 ID
    • WORKLOAD_PROVIDER_ID: 워크로드 아이덴티티 풀 공급업체의 ID
    • SERVICE_ACCOUNT_EMAIL: Kubernetes ServiceAccount에서 IAM 서비스 계정 가장을 사용하도록 구성한 경우 서비스 계정의 이메일 주소

    사용자 인증 정보 구성 파일을 사용하면 [Cloud 클라이언트 라이브러리](/apis/docs/cloud-client-libraries), gcloud CLI, Terraform에서 다음을 확인할 수 있습니다.

    • 외부 사용자 인증 정보를 가져올 위치
    • 사용할 워크로드 아이덴티티 풀 및 공급업체
    • 가장할 서비스 계정

    워크로드 아이덴티티 제휴를 사용하도록 Apigee Hybrid 구성

    1. 각 출력 파일(SERVICE_ACCOUNT_NAME-credential-configuration.json)을 다음 차트 디렉터리(또는 하위 디렉터리)에 복사하거나 이동합니다. 이 파일은 사용자 인증 정보 구성 파일 만들기 단계에서 만든 파일입니다.

      프로덕션

      서비스 계정 Apigee Helm 차트 디렉터리
      apigee-cassandra apigee-datastore/
      apigee-mart apigee-org/
      apigee-metrics apigee-telemetry/
      apigee-runtime apigee-env/
      apigee-synchronizer apigee-env/
      apigee-udca apigee-org/
      apigee-env/
      apigee-watcher apigee-org/

      비프로덕션

      서비스 계정 Apigee Helm 차트
      apigee-non-prod apigee-datastore/
      apigee-telemetry/
      apigee-org/
      apigee-env/
    2. 클러스터의 재정의 파일을 다음과 같이 전역적으로 변경합니다.

      코드

      gcp:
        workloadIdentity:
          enabled: false # must be set to false to use Workload Identity Federation
        federatedWorkloadIdentity:
          enabled: true
          audience: "AUDIENCE"
          credentialSourceFile: "/var/run/service-account/token"
      

      gcp:
        workloadIdentity:
          enabled: false
        federatedWorkloadIdentity:
          enabled: true
          audience: "//iam.googleapis.com/projects/123123123123/locations/global/workloadIdentityPools/my-wi-pool/providers/my-wi-provider"
          credentialSourceFile: "/var/run/service-account/token"
      

      여기서 AUDIENCE는 워크로드 아이덴티티 제공업체의 허용된 대상입니다. 사용자 인증 정보 구성 파일에서 audience: 용어를 검색하여 값을 찾을 수 있습니다. 대상 값은 사용자 인증 정보 구성 파일마다 동일합니다.

      예를 들어 다음 샘플 apigee-udca-credential-configuration.json 파일의 대상 값은 다음과 같습니다.

      {
        "universe_domain": "googleapis.com",
        "type": "external_account:,"
        "audience": "//iam.googleapis.com/projects/123123123123/locations/global/workloadIdentityPools/my-wi-pool/providers/my-wi-provider",
        "subject_token_type": "urn:ietf:params:oauth: token-type:jwt",
        "token_url": "https://sts.googleapis.com/v1/token",
        "service
        "impersonation_url": "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/apigee-udca@myhybridproject.iam.gserviceaccount.com:generateAccessToken",
        "credential_source": {
          "file": "/var/run/service-account/token",
          "format": {
            "type": "text"
          }
        }
      }

      대상 값은 //iam.googleapis.com/projects/123123123123/locations/global/workloadIdentityPools/my-wi-pool/providers/my-wi-provider입니다.

    3. 워크로드 아이덴티티 제휴를 사용하여 각 구성요소에 대한 재정의를 구성합니다. 설치에 따라 인증서 파일, Kubernetes 보안 비밀, Vault 안내를 선택합니다.

      인증서 파일

      serviceAccountPath 값을 해당 IAM 서비스 계정의 사용자 인증 정보 소스 파일로 바꿉니다. 이 경로는 차트 디렉터리의 상대 경로여야 합니다. 예를 들면 다음과 같습니다.

      envs:
      - name: ENVIRONMENT_NAME
        serviceAccountPaths:
          synchronizer: apigee-synchronizer-credential-configuration.json
          runtime: apigee-runtime-credential-configuration.json
          udca: apigee-udca-credential-configuration.json
      
      mart:
        serviceAccountPath: apigee-mart-credential-configuration.json
      
      connectAgent:
        serviceAccountPath: apigee-mart-credential-configuration.json
      
      metrics:
        serviceAccountPath: apigee-metrics-credential-configuration.json
      
      udca:
        serviceAccountPath: apigee-udca-credential-configuration.json
      
      watcher:
        serviceAccountPath: apigee-watcher-credential-configuration.json
      

      K8s 보안 비밀

      1. 각 사용자 인증 정보 구성 파일의 사용자 인증 정보 소스 파일을 사용하여 새로운 Kubernetes 보안 비밀을 만듭니다.
        kubectl create secret -n APIGEE_NAMESPACE generic SECRET_NAME --from-file="client_secret.json=CREDENTIAL_CONFIGURATION_FILE"

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

        kubectl create secret -n apigee generic udca-workoad-identity-secret --from-file="client_secret.json=./apigee-udca-credential-configuration.json"
      2. serviceAccountRef의 값을 새 보안 비밀로 바꿉니다. 예를 들면 다음과 같습니다.
        udca:
          serviceAccountRef: udca-workoad-identity-secret
        

      Vault

      해당 사용자 인증 정보 소스 파일을 사용하여 Vault에서 각 서비스 계정의 서비스 계정 키 SAKEY를 업데이트합니다. 절차는 모든 구성요소에서 유사합니다. 예를 들어 UDCA의 경우는 다음과 같습니다.

      SAKEY=$(cat .apigee-udca-credential-configuration.json); kubectl -n APIGEE_NAMESPACE exec vault-0 -- vault kv patch secret/apigee/orgsakeys udca="$SAKEY"

      자세한 내용은 Storing service account keys in Hashicorp Vault를 참조하세요.

    4. helm upgrade 명령어로 영향을 받는 각 구성요소에 변경사항을 적용합니다.

      Vault 서비스 계정 키를 업데이트한 경우 apigee-operator 차트를 업데이트합니다.

      helm upgrade operator apigee-operator/ \
        --namespace APIGEE_NAMESPACE \
        --atomic \
        -f overrides.yaml
      

      영향을 받는 나머지 차트는 다음 순서로 업데이트합니다.

      helm upgrade datastore apigee-datastore/ \
        --namespace APIGEE_NAMESPACE \
        --atomic \
        -f overrides.yaml
      
      helm upgrade telemetry apigee-telemetry/ \
        --namespace APIGEE_NAMESPACE \
        --atomic \
        -f overrides.yaml
      
      helm upgrade $ORG_NAME apigee-org/ \
        --namespace APIGEE_NAMESPACE \
        --atomic \
        -f overrides.yaml
      

      각 환경의 apigee-env 차트를 업데이트하여 매번 $ENV_RELEASE_NAMEENV_NAME을 바꿉니다.

      helm upgrade $ENV_RELEASE_NAME apigee-env/ \
        --namespace APIGEE_NAMESPACE \
        --atomic \
        --set env=$ENV_NAME \
        -f overrides.yaml
      

      구성요소 및 해당 차트 목록은 Apigee Hybrid Helm 참조를 확인하세요.

    Kubernetes 서비스 계정에 대한 액세스 권한 부여

    1. 다음 명령어를 사용하여 Kubernetes 서비스 계정을 표시합니다.
      kubectl get sa -n APIGEE_NAMESPACE
    2. 다음 표와 같이 연결된 IAM 서비스 계정을 가장할 수 있는 액세스 권한을 Kubernetes 서비스 계정에 부여합니다. 표에서는 기본 Apigee IAM 서비스 계정 이름이 나와 있습니다. 커스텀 서비스 계정 이름을 사용하는 경우 해당 IAM 서비스 계정을 사용합니다.
      Kubernetes 서비스 계정 IAM 서비스 계정
      조직 수준 Kubernetes 서비스 계정
      apigee-connect-agent-ORG_NAME-ORG_HASH_ID apigee-mart
      apigee-mart-ORG_NAME-ORG_HASH_ID apigee-mart
      apigee-metrics-apigee-telemetry apigee-metrics
      apigee-open-telemetry-collector-apigee-telemetry apigee-metrics
      apigee-udca-ORG_NAME-ORG_HASH_ID apigee-udca
      apigee-watcher-ORG_NAME-ORG_HASH_ID apigee-watcher
      환경 수준 Kubernetes 서비스 계정
      apigee-runtime-ORG_NAME-ENV_NAME-ENV_HASH_ID apigee-runtime
      apigee-synchronizer-ORG_NAME-ENV_NAME-ENV_HASH_ID apigee-synchronizer
      Cassandra 백업 및 복원(사용 설정된 경우)
      apigee-cassandra-backup-sa apigee-cassandra
      apigee-cassandra-restore-sa apigee-cassandra

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

      • ORG_NAME: 조직 이름의 처음 15자입니다.
      • ORG_HASH_ID: 전체 조직 이름의 고유한 해시 ID입니다.
      • ENV_NAME: 환경 이름의 처음 15자입니다.
      • ENV_HASH_ID: 조직 이름과 환경 이름의 고유한 해시 ID입니다.

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

      • apigee-connect-agent-myhybridorg-123abcd
      • apigee-runtime-myhybridorg-prodenv-234bcde

      다음 명령어를 사용하여 적절한 IAM 서비스 계정을 가장할 수 있는 액세스 권한을 각 Kubernetes 서비스 계정에 부여합니다.

      gcloud iam service-accounts add-iam-policy-binding \
        IAM_SA_NAME@PROJECT_ID.iam.gserviceaccount.com \
          --member="principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/MAPPED_SUBJECT" \
          --role=roles/iam.workloadIdentityUser

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

      • IAM_SA_NAME: 서비스 계정의 이름입니다.
      • PROJECT_ID: Apigee 조직과 연결된 프로젝트의 ID입니다.
      • PROJECT_NUMBER: 워크로드 아이덴티티 풀을 만든 프로젝트의 프로젝트 번호입니다.
      • POOL_ID: 워크로드 아이덴티티 풀 ID입니다.
      • MAPPED_SUBJECT: google.subject에 매핑한 ID 토큰의 클레임에서 가져온 Kubernetes ServiceAccount입니다. 예를 들어 google.subject=assertions.sub를 매핑했고 ID 토큰에 "sub": "system:serviceaccount:default:my-kubernetes-serviceaccount"가 포함되어 있으면 MAPPED_SUBJECTsystem:serviceaccount:default:my-kubernetes-serviceaccount입니다.

    워크로드 아이덴티티 제휴 및 권장사항에 대한 자세한 내용은 워크로드 아이덴티티 제휴 사용 권장사항을 참조하세요.