Google Kubernetes Engine (GKE) 클러스터에 배포하는 에이전트 워크로드는 에이전트 자체 ID로 또는 최종 사용자를 대신하여 외부 도구 및 서비스에 액세스해야 하는 경우가 많습니다. 보안 관리자와 플랫폼 관리자는 배포된 에이전트가 Google Cloud서비스 전반에서 어떤 작업을 수행하는지도 알고 싶어 합니다. 이 문서에서는 포드의 에이전트 ID를 요청하여 에이전트 워크로드의 인증을 구성하는 방법을 보여줍니다. 이 에이전트 ID를 사용하면 다양한 워크플로의 사용자 인증 정보를 수동으로 관리하지 않고도 인증을 구성할 수 있으며 GKE 에이전트를 Gemini Enterprise Agent Platform과 통합할 수 있습니다. 이 문서는 GKE 클러스터에서 에이전트 워크로드를 빌드하고 실행하는 애플리케이션 개발자를 대상으로 합니다.
다음 주제에 익숙해야 합니다.
가격 책정
에이전트 ID는 GKE에서 추가 비용 없이 제공됩니다.
제한사항
- 에이전트 레지스트리에 배포만 자동으로 등록할 수 있습니다. 다른 워크로드 컨트롤러와 정적 포드는 자동 등록을 지원하지 않습니다. 모든 워크로드 유형에 대해 에이전트 아이덴티티를 요청할 수 있지만 에이전트 레지스트리에 등록하면 이러한 아이덴티티를 에이전트 플랫폼과 통합할 수 있습니다.
- 바인드된 에이전트 ID 액세스 토큰은
https://www.googleapis.com/auth/cloud-platformOAuth 범위만 사용합니다. 바인딩된 액세스 토큰에 다른 범위를 지정할 수 없습니다.
시작하기 전에
시작하기 전에 다음 태스크를 수행했는지 확인합니다.
- Google Kubernetes Engine API를 사용 설정합니다. Google Kubernetes Engine API 사용 설정
- 이 태스크에 Google Cloud CLI를 사용하려면 gcloud CLI를 설치한 후 초기화합니다. 이전에 gcloud CLI를 설치했으면
gcloud components update명령어를 실행하여 최신 버전을 가져옵니다. 이전 gcloud CLI 버전에서는 이 문서의 명령어를 실행하지 못할 수 있습니다.
아직 사용 설정되지 않은 경우 Agent Registry API를 사용 설정합니다.
API 사용 설정에 필요한 역할
API를 사용 설정하려면
serviceusage.services.enable권한이 필요합니다. 프로젝트를 만든 경우 소유자 역할 (roles/owner)을 통해 이 권한이 이미 있을 수 있습니다. 그렇지 않은 경우 서비스 사용량 관리자 역할 (roles/serviceusage.serviceUsageAdmin)을 통해 이 권한을 얻을 수 있습니다. 역할을 부여하는 방법 알아보기gcloud services enable agentregistry.googleapis.com
GKE용 워크로드 아이덴티티 제휴가 사용 설정되어 있고 GKE 버전 1.37.0-gke.3503000 이상을 실행하는 기존 Autopilot 클러스터 또는 Standard 클러스터가 있는지 확인합니다.
토큰 교환 작업을 위한 할당량이 충분한지 확인합니다. 이 할당량의 이름은 리전별 분당 워크로드 아이덴티티 토큰 교환 요청입니다. 자세한 내용은 할당량 및 한도를 참조하세요.
필요한 역할
에이전트 ID를 요청하고 워크로드를 배포하는 데 필요한 권한을 얻으려면 관리자에게 Google Cloud 프로젝트에 대한 Kubernetes Engine 개발자 (roles/container.developer) IAM 역할을 부여해 달라고 요청하세요.
역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.
커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.
워크로드의 에이전트 ID 요청
포드의 에이전트 ID를 가져오려면 포드 사양에 주석을 추가하여 워크로드의 SPIFFE ID를 요청하고 각 포드에 X.509 인증서 번들을 삽입합니다. Deployment에서 관리하는 포드의 경우 에이전트 레지스트리에 에이전트를 등록하기 위해 주석과 라벨도 추가해야 합니다. 등록은 선택사항이지만 등록된 에이전트만 Agent Gateway와 같은 Agent Platform 서비스를 사용할 수 있습니다. 특정 주석과 라벨에 대한 자세한 내용은 워크로드 수준 구성을 참고하세요.
다음 단계에서는 에이전트 ID를 요청하는 배포 예시를 만드는 방법을 보여줍니다.
조직 ID를 찾습니다. 프로젝트가 조직에 속하지 않는 경우 이 단계를 건너뛰고 대신 프로젝트 번호를 찾으세요.
gcloud projects get-ancestors PROJECT_IDPROJECT_ID를 클러스터 프로젝트 ID로 바꿉니다.출력은 다음과 비슷합니다.
ID: my-project TYPE: project ID: 811159889184 TYPE: folder ID: 301928500920 TYPE: organizationorganization리소스의ID필드 값을 기록해 둡니다.클러스터에 연결합니다.
gcloud container clusters get-credentials CLUSTER_NAME \ --location=CONTROL_PLANE_LOCATION다음을 바꿉니다.
CLUSTER_NAME: 클러스터 이름입니다.CONTROL_PLANE_LOCATION: 클러스터 컨트롤 플레인의 리전 또는 영역입니다.
예시 배포를 실행할 네임스페이스를 만듭니다.
kubectl create namespace NAMESPACE_NAMENAMESPACE_NAME을 네임스페이스 이름으로 바꿉니다.배포를 위한 Kubernetes ServiceAccount를 만듭니다.
kubectl create serviceaccount SERVICEACCOUNT_NAME \ --namespace=NAMESPACE_NAMESERVICEACCOUNT_NAME을 서비스 계정의 이름으로 바꿉니다.다음 배포 매니페스트를
agent-identity-deployment.yaml로 저장합니다.apiVersion: apps/v1 kind: Deployment metadata: name: agent-identity-deployment namespace: NAMESPACE_NAME # Add the agent to Agent Registry labels: registry.gke.io/functional-type: "AGENT" annotations: # A2A protocol metadata annotation for automated Agent Card discovery a2a-protocol.org/agent-card: | card: endpoint: /.well-known/agent-card.json protocol: HTTP port: 8080 spec: replicas: 2 selector: matchLabels: workload-type: agent template: metadata: name: agent-identity-pod annotations: iam.gke.io/identity: "spiffe://TRUST_DOMAIN/*" # The trust domain from which to assign SPIFFE IDs. iam.gke.io/inject-podcertificates: "true" # Inject X.509 certificates and per-Pod private key into each Pod. iam.gke.io/spiffe-identity-type: "agent-identity" # Required for Agent Registry registration. labels: workload-type: agent spec: serviceAccountName: SERVICEACCOUNT_NAME containers: - name: agent image: python:3.11-slim command: ["sleep","infinity"]TRUST_DOMAIN를 프로젝트의 에이전트 ID를 발급하는 트러스트 도메인으로 바꿉니다. 이 값은 프로젝트가 조직에 속해 있는지에 따라 다음 문법 중 하나를 사용해야 합니다.- 조직에 속한 프로젝트:
agents.global.org-ORGANIZATION_ID.system.id.goog, 여기서ORGANIZATION_ID는 조직의 ID입니다. - 조직에 속하지 않는 프로젝트:
agents.global.proj-PROJECT_NUMBER.system.id.goog(여기서PROJECT_NUMBER은 클러스터 프로젝트의 프로젝트 번호임)
이 배포는 워크로드의 에이전트 아이덴티티를 요청하고, 포드별 X.509 인증서를 포드에 추가하고, 에이전트를 에이전트 레지스트리에 등록합니다.
- 조직에 속한 프로젝트:
배포를 만듭니다.
kubectl apply -f agent-identity-deployment.yamlpod가 실행 중인지 확인합니다.
kubectl get pods -l workload-type=agent -n NAMESPACE_NAME
할당된 에이전트 ID 확인
에이전트 ID를 요청하는 워크로드를 배포한 후 X.509 인증서를 확인하여 ID를 확인할 수 있습니다. 인증서 삽입을 사용 중지하면 Google Cloud API 인증에 설명된 대로 GKE 메타데이터 서버에서 바인딩되지 않은 ID 토큰을 가져와 주체 필드를 확인할 수 있습니다.
포드에서 X.509 인증서를 읽으려면 다음 단계를 따르세요.
포드가 X.509 인증서와 비공개 키에 액세스할 수 있는지 확인합니다.
kubectl get pod POD_NAME -n NAMESPACE_NAME \ -o=jsonpath='{range .spec.volumes[*]}{.name}{"\n"}{end}'POD_NAME을 에이전트 ID를 사용하는 포드의 이름으로 바꿉니다.출력은 다음과 비슷합니다.
kube-api-access-bx86g gke-workload-spiffe-credentials이 출력에서
gke-workload-spiffe-credentials볼륨은 삽입된 인증서의 위치입니다. 이 볼륨이 표시되지 않으면iam.gke.io/inject-podcertificates주석이 포드 사양에서true값으로 설정되어 있는지 확인합니다.포드에서 대화형 셸 세션을 만듭니다.
kubectl exec -n NAMESPACE_NAME -it POD_NAME -- /bin/bash셸 세션에서
gke-workload-spiffe-credentials볼륨의 사용자 인증 정보를 나열합니다.ls -1 /var/run/secrets/workload-spiffe-credentials/출력은 다음과 비슷합니다.
x509.credential-bundle.private-key.pem TRUST_DOMAIN.spiffe-trust-bundle.pem출력에 다음 파일이 표시됩니다.
x509.credential-bundle.private-key.pem: 에이전트 ID 사용자 인증 정보 번들로, X.509 인증서 체인과 포드에 고유한 비공개 키가 포함됩니다. 이 사용자 인증 정보 번들은 액세스 토큰과 ID 토큰을 요청하고 mTLS를 사용하여 Google CloudAPI를 인증하는 데 사용됩니다.TRUST_DOMAIN.spiffe-trust-bundle.pem: 에이전트 ID 사용자 인증 정보의 신뢰 앵커를 형성하는 자체 서명 인증서가 포함된 루트 CA 신뢰 번들입니다. 이 신뢰 번들은 주로 mTLS 핸드셰이크 중에 다른 워크로드의 TLS 인증서를 검증하는 데 사용됩니다.
포드와 연결된 SPIFFE ID를 가져오려면 X.509 인증서를 읽으세요.
openssl x509 -in /var/run/secrets/workload-spiffe-credentials/x509.credential-bundle.private-key.pem -text -noout출력은 다음과 비슷합니다.
Certificate: Data: # Multiple lines are omitted here X509v3 extensions: # Multiple lines are omitted here X509v3 Subject Alternative Name: critical URI:spiffe://agents.global.org-301928500920.system.id.goog/resources/container/projects/729788050015/locations/us-central1/clusters/cluster-2/ns/agent-identity-ns/sa/agent-identity-sa # Multiple lines are omitted here이 출력에서
X509v3 Subject Alternative Name필드의URI필드에 있는 값은 에이전트의 SPIFFE ID입니다.
에이전트 포드에 할당된 SPIFFE ID가 있으면 에이전트 ID 요청이 성공한 것입니다. 할당된 ID를 사용하여 다양한 도구 및 서비스에 인증할 수 있습니다.