이 주제에서는 AKS 및 EKS 플랫폼에서 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)에 액세스할 수 있도록 이 기능을 사용 설정해야 합니다.
워크로드 아이덴티티 제휴를 사용하도록 클러스터 구성
-
다음 명령어를 사용하여 현재
gcloud
구성이 Google Cloud 프로젝트 ID로 설정되었는지 확인합니다.gcloud config get project
-
보안 토큰 서비스 API를 사용 설정합니다.
다음 명령어를 사용하여 보안 토큰 서비스 API가 사용 설정되어 있는지 확인합니다.
gcloud services list --enabled --project PROJECT_ID | grep sts.googleapis.com
API가 사용 설정되지 않은 경우에는 다음 안내를 따르세요.
콘솔
Enable the Security Token Service API.
명령줄
다음 명령어를 사용하여 API를 사용 설정합니다.
gcloud services enable sts.googleapis.com --project PROJECT_ID
-
워크로드 아이덴티티 풀과 제공업체를 만듭니다.
필요한 역할
워크로드 아이덴티티 제휴를 구성하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.
-
워크로드 아이덴티티 풀 관리자(
roles/iam.workloadIdentityPoolAdmin
) -
서비스 계정 관리자(
roles/iam.serviceAccountAdmin
)
역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.
커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.
또는 IAM 소유자(roles/owner
) 기본 역할에는 ID 제휴를 구성할 수 있는 권한도 포함됩니다. 프로덕션 환경에서는 기본 역할을 부여하지 말아야 하지만 개발 환경이나 테스트 환경에서는 부여할 수 있습니다.워크로드 아이덴티티 풀과 공급업체를 만들려면 다음을 수행합니다.
-
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
-
Kubernetes 클러스터에 연결하고 `kubectl`을 사용하여 클러스터 발급기관 URL을 확인합니다.
kubectl get --raw /.well-known/openid-configuration | jq -r .issuer
다음 단계 중 하나에서 발급기관 URL이 필요합니다.
-
선택사항: OIDC 발급자가 공개적으로 액세스할 수 없으면 클러스터의 JSON 웹 키 집합(JWKS)을 다운로드합니다.
kubectl get --raw /openid/v1/jwks > cluster-jwks.json
OIDC 제공업체를 공개적으로 사용할 수 있는지 확인하려면 CURL 명령어로 제공업체 URL에 액세스하여 200 응답을 수신할 수 있어야 합니다.
-
새 워크로드 아이덴티티 풀을 만듭니다.
gcloud iam workload-identity-pools create POOL_ID \ --location="global" \ --description="DESCRIPTION" \ --display-name="DISPLAY_NAME"
다음을 바꿉니다.
POOL_ID
: 풀의 고유 IDDISPLAY_NAME
: (선택사항) 풀 이름DESCRIPTION
: (선택사항) 선택한 풀에 대한 설명. 이 설명은 풀 ID에 대한 액세스 권한을 부여할 때 표시됩니다.
예를 들면 다음과 같습니다.
gcloud iam workload-identity-pools create my-wi-pool --display-name="My workload pool" --description="My workload pool description"
-
클러스터를 워크로드 아이덴티티 풀 제공업체로 추가합니다. 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
: 선택한 고유 워크로드 아이덴티티 풀 제공업체 IDPOOL_ID
: 앞에서 만든 워크로드 아이덴티티 풀 ID-
ISSUER
: 앞에서 확인한 발급기관 URL을 발급기관 URI로 사용합니다.
attribute-mapping="google.subject=assertion.sub"
는 Kubernetes 주체를 IAM 주체에 매핑합니다.
-
워크로드 아이덴티티 풀 관리자(
필요한 경우 현재 gcloud
구성을 설정합니다.
gcloud config set project PROJECT_ID
사용자 인증 정보 구성 파일 만들기
Google Cloud 리소스에 액세스할 수 있는 Kubernetes 워크로드를 배포하려면 먼저 IAM 서비스 계정마다 사용자 인증 정보 구성 파일을 만들어야 합니다.
-
다음 명령어를 사용하여 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
-
이전 목록에 있는 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 구성
-
각 출력 파일(
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/
-
클러스터의 재정의 파일을 다음과 같이 전역적으로 변경합니다.
코드
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
입니다. -
워크로드 아이덴티티 제휴를 사용하여 각 구성요소에 대한 재정의를 구성합니다. 설치에 따라 인증서 파일, 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 보안 비밀
-
각 사용자 인증 정보 구성 파일의 사용자 인증 정보 소스 파일을 사용하여 새로운 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"
-
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
를 참조하세요. -
각 사용자 인증 정보 구성 파일의 사용자 인증 정보 소스 파일을 사용하여 새로운 Kubernetes 보안 비밀을 만듭니다.
-
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_NAME 및 ENV_NAME을 바꿉니다.helm upgrade $ENV_RELEASE_NAME apigee-env/ \ --namespace APIGEE_NAMESPACE \ --atomic \ --set env=$ENV_NAME \ -f overrides.yaml
구성요소 및 해당 차트 목록은 Apigee Hybrid Helm 참조를 확인하세요.
Kubernetes 서비스 계정에 대한 액세스 권한 부여
-
다음 명령어를 사용하여 Kubernetes 서비스 계정을 표시합니다.
kubectl get sa -n APIGEE_NAMESPACE
-
다음 표와 같이 연결된 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_SUBJECT
는system:serviceaccount:default:my-kubernetes-serviceaccount
입니다.
워크로드 아이덴티티 제휴 및 권장사항에 대한 자세한 내용은 워크로드 아이덴티티 제휴 사용 권장사항을 참조하세요.
-