에이전트 워크로드에는 다른 유형의 워크로드와 다른 방어 조치, 액세스 제어, 인증 워크플로가 필요한 경우가 많습니다. 에이전트 ID를 사용하여 각 에이전트에 증명된 단기 수명의 포드별 ID를 부여할 수 있습니다. 이 ID를 사용하면 에이전트 워크로드를 식별하고 Google Cloud에서 이러한 워크로드가 수행하는 작업을 추적하고 관리할 수 있습니다. 이 문서에서는 Google Kubernetes Engine(GKE)에서 에이전트 ID가 작동하는 방식(다른Google Cloud 제품과의 통합 방법, 에이전트가 사용할 수 있는 인증 유형, 이러한 ID를 사용하여 워크로드를 관리하는 방법 포함)을 설명합니다.
이 문서는 Google Cloud 제품 및 서비스와 에이전트를 통합하면서 GKE 클러스터에서 실행되는 에이전트의 보안을 개선하려는 플랫폼 관리자 및 보안 엔지니어를 대상으로 합니다.
다음 주제에 익숙해야 합니다.
상담사 ID란 무엇인가요?
Google Cloud 는 워크로드에 다양한 ID 유형을 제공하며, 각 ID 유형은 특정 사용 사례 및 워크로드 유형을 위해 설계되었습니다. 에이전트 ID는 AI 에이전트 워크로드용으로 설계된 ID 유형입니다. 에이전트 아이덴티티를 사용하는 에이전트는 SPIFFE 표준을 기반으로 하는 고유한 아이덴티티를 가져옵니다. 이 ID는 에이전트의 수명 주기에 바인딩되고, 워크로드를 에이전트로 식별하며, Agent Registry, Agent Gateway와 같은 다양한 Gemini Enterprise Agent Platform 서비스에서 인식됩니다. 워크로드가 실행되는 위치와 관계없이 워크로드가 액세스하는 모든 서비스에서 에이전트 ID가 있는 워크로드를 추적하고 관리할 수 있습니다. 에이전트 ID를 사용하는 워크로드는 자체 ID를 사용하거나 최종 사용자를 대신하여 MCP 서버, Google Cloud내부 및 외부 리소스, 기타 에이전트, 엔드포인트에 인증할 수 있습니다. 에이전트 ID에 대한 자세한 내용은 에이전트 ID 개요를 참고하세요.
에이전트 ID를 사용하여 GKE 클러스터에 배포하는 AI 에이전트의 보안과 거버넌스를 개선하고 다음과 같은 에이전트의 특정 워크플로를 사용 설정할 수 있습니다.
- GKE의 에이전트를 Agent Registry, Agent Gateway와 같은 제품과 통합합니다.
- Identity and Access Management (IAM) 정책에서 프로젝트, 폴더 또는 조직 전반의 에이전트 워크로드 역할을 관리합니다.
- 손상된 에이전트가 노드와 클러스터의 다른 포드에 미치는 영향을 줄입니다.
- 에이전트 ID 인증 관리자를 사용하여 최종 사용자를 대신하는 에이전트와 같은 다양한 인증 워크플로를 설정합니다.
GKE용 워크로드 아이덴티티 제휴와의 비교
에이전트 ID와 GKE용 워크로드 아이덴티티 제휴는 모두 워크로드에 ID를 부여하는 방법을 제공합니다. 에이전트 ID는 AI 에이전트에 적용되는 위협 모델과 특정 요구사항을 위해 설계되었으며, 이로 인해 다양한 기능적 차이가 발생합니다. 다음 표에서는 이러한 차이점을 대략적으로 비교합니다.
| 에이전트 아이덴티티 | GKE용 워크로드 아이덴티티 제휴 |
|---|---|
| 에이전트 ID 액세스 토큰은 포드별 X.509 인증서에 암호화 방식으로 바인딩될 수 있습니다. 바운드 액세스 토큰에는 mTLS 연결이 필요하며 원래 포드 외부에서 사용하면 작동하지 않습니다. | 제휴 액세스 토큰은 포드 ID에 암호화 방식으로 바인딩되지 않고, mTLS가 아닌 연결을 통해 작동하며, 원래 포드 외부에서 사용할 수 있습니다. |
| OAuth 워크플로를 지원하고 수동 사용자 인증 정보 관리 없이 서드 파티 사용자 인증 정보를 사용하기 위해 에이전트 ID 인증 관리자와 통합됩니다. | 외부 도구 및 서비스에 인증할 때 OAuth 워크플로를 수동으로 구현하고 서드 파티 사용자 인증 정보를 관리해야 합니다. |
| AI 에이전트와 같은 자율 워크로드에 적합합니다. | 웹 서버, API, 일괄 작업과 같은 결정적 마이크로서비스에 적합합니다. |
| GKE 버전 1.37.0-gke.3503000 이상이 필요합니다. | 모든 GKE 버전에서 사용할 수 있습니다. |
바운드 에이전트 ID 액세스 토큰은 항상 https://www.googleapis.com/auth/cloud-platform 액세스 범위를 사용합니다.
맞춤 범위는 지원되지 않습니다. |
제휴 액세스 토큰은 맞춤 액세스 범위를 지원합니다. |
| 애플리케이션은 에이전트 ID ID 토큰을 가져와 다른 워크로드 또는 다운스트림 서비스에 직접 인증할 수 있습니다. | Kubernetes 서비스 계정이 IAM 서비스 계정을 가장하도록 구성되지 않으면 애플리케이션에서 ID 토큰을 가져올 수 없습니다. |
Agent Platform과의 통합
Gemini Enterprise Agent Platform에는 대규모로 에이전트를 빌드, 관리, 운영하도록 설계된 여러 제품과 서비스가 포함되어 있습니다. GKE에서 에이전트 워크로드를 실행하는 경우 워크로드에 에이전트 아이덴티티를 할당하고 워크로드를 에이전트 레지스트리에 에이전트로 등록하여 에이전트 플랫폼 제품을 사용할 수 있습니다. GKE 에이전트와 Agent Platform 서비스를 통합하고 사용하려면 애플리케이션 운영자가 에이전트 워크로드의 Kubernetes 사양에 주석과 라벨을 추가합니다. GKE용 워크로드 아이덴티티 제휴가 사용 설정되어 있는지 확인하는 것 외에는 클러스터 또는 노드 풀 구성을 변경할 필요가 없습니다. 그런 다음 Agent Runtime 또는 Cloud Run에서 실행되는 에이전트를 관리하는 것과 동일한 방식으로 GKE 에이전트를 관리하고 제어할 수 있습니다.
에이전트 레지스트리에 등록하면 조직 간에 프로젝트를 이동할 때 발생할 수 있는 중단을 방지하는 데도 도움이 됩니다. 프로젝트 이동 중에 Agent Registry는 이동 후 변경되는 조직 수준 트러스트 도메인을 기반으로 하는 에이전트 아이덴티티를 사용하는 에이전트가 있는지 확인합니다. 조직 수준 에이전트 ID가 사용 중이면 프로젝트 이동이 차단됩니다. 이 검사는 에이전트 레지스트리에 등록한 배포에서만 실행됩니다. 다른 워크로드 컨트롤러나 정적 포드에서는 검사가 실행되지 않습니다.
GKE에서 작동하는 방식
GKE에서 에이전트 ID는 GKE용 워크로드 아이덴티티 제휴와 마찬가지로 GKE 메타데이터 서버 및 ID 풀과 같은 개념을 사용합니다. 에이전트 ID를 사용하려면 클러스터에서 GKE용 워크로드 아이덴티티 제휴도 사용 설정해야 합니다. Google Cloud 는 프로젝트 또는 조직 수준에서 에이전트 ID 풀을 자동으로 만듭니다. 에이전트 ID 풀은 SPIFFE 트러스트 도메인이며 에이전트 ID 및 사용자 인증 정보의 신뢰할 수 있는 루트입니다. 애플리케이션 개발자는 포드 사양에 주석과 라벨을 추가하여 에이전트의 에이전트 ID를 요청할 수 있습니다. 워크로드가 클러스터에 배포되면 GKE는 워크로드에 다음 사용자 인증 정보를 할당합니다.
워크로드를 식별하는 SPIFFE ID입니다. 배포와 같은 관리 워크로드의 모든 포드는 해당 워크로드의 SPIFFE ID를 공유합니다. SPIFFE ID는 여러 Google Cloud 서비스에서 에이전트를 식별합니다. SPIFFE ID를 사용하여 포드가 에이전트로서 또는 최종 사용자를 대신하여 실행하는 모든 작업을 추적할 수 있습니다. SPIFFE ID의 구문은 다음과 같습니다.
spiffe://TRUST_DOMAIN/resources/container/projects/PROJECT_NUMBER/locations/CONTROL_PLANE_LOCATION/clusters/CLUSTER_NAME/ns/NAMESPACE/sa/SERVICEACCOUNT_NAME이 ID 문자열에는 다음과 같은 속성이 있습니다.
TRUST_DOMAIN: SPIFFE 트러스트 도메인입니다. 클러스터가 포함된 프로젝트가 조직에 있는지 여부에 따라 다음 값 중 하나를 갖습니다.- 조직에 속한 프로젝트:
agents.global.org-ORGANIZATION_ID.system.id.goog, 여기서ORGANIZATION_ID는 조직의 ID입니다. - 조직에 속하지 않는 프로젝트:
agents.global.proj-PROJECT_NUMBER.system.id.goog(여기서PROJECT_NUMBER은 클러스터 프로젝트의 프로젝트 번호임)
- 조직에 속한 프로젝트:
PROJECT_NUMBER: 클러스터 프로젝트의 프로젝트 번호입니다.CONTROL_PLANE_LOCATION: 클러스터의 컨트롤 플레인이 있는 리전 또는 영역입니다.CLUSTER_NAME: 포드가 있는 클러스터의 이름입니다.NAMESPACE: 포드가 있는 Kubernetes 네임스페이스의 이름입니다.SERVICEACCOUNT_NAME: 포드에 할당된 Kubernetes 서비스 계정의 이름입니다.
각 포드에 볼륨으로 마운트되고 Google Cloud API에 대한 mTLS 인증에 사용할 수 있는 에이전트 ID 사용자 인증 정보 번들(
x509.credential-bundle.private-key.pem) 이 파일에는 다음 사용자 인증 정보가 포함됩니다.- 에이전트 워크로드의 SPIFFE ID를 주체 대체 이름 (SAN) 매개변수로 포함하고 24시간 후에 만료되는 X.509 인증서 체인 인증서 체인은 다른 서비스에 대한 인증을 위해 바인드된 액세스 토큰과 ID 토큰을 가져오는 데 사용됩니다.
kubelet프로세스가 각 포드에 대해 자동으로 만드는 비공개 키입니다. 이 키는 암호화 방식으로 포드의 X.509 인증서를 포드에 바인딩합니다. 이 키는 요청을 한 포드가 TLS 연결을 설정하는 데 사용된 X.509 인증서를 소유하고 있음을 증명합니다.
각 포드에 볼륨으로 마운트되고 동일한 트러스트 도메인을 사용하는 에이전트 간에 mTLS 인증을 구성하는 데 사용할 수 있는 루트 CA 신뢰 번들(
TRUST_DOMAIN.spiffe-trust-bundle.pem) mTLS 핸드셰이크 중에 에이전트는 루트 CA 트러스트 번들을 사용하여 피어 에이전트가 제공하는 인증서 체인을 검증합니다.
워크로드 수준 구성
워크로드에 에이전트 ID와 포드별 사용자 인증 정보를 할당하기 위해 GKE는 포드 사양에서 다음 주석을 찾습니다.
iam.gke.io/identity: "spiffe://TRUST_DOMAIN/*": GKE는 이 주석을 사용하여 해당 트러스트 도메인에서 포드에 SPIFFE ID를 할당합니다.iam.gke.io/inject-podcertificates: "true": GKE는 이 주석을 사용하여 에이전트 ID 사용자 인증 정보 번들과 클러스터 신뢰 번들을 워크로드의 각 포드에 추가합니다. 이 주석을 생략하면 특정 포드에 바인딩된 액세스 토큰을 가져올 수 없습니다. 삽입된 사용자 인증 정보는 포드에서Google Cloud API 또는 피어 에이전트로의 mTLS 인증에 사용됩니다.
또한 에이전트 레지스트리는 다음 라벨과 주석을 사용하여 GKE 에이전트를 자동으로 등록합니다.
registry.gke.io/functional-type: "AGENT"라벨: 워크로드를 AI 에이전트로 식별하고 에이전트를 에이전트 레지스트리에 추가합니다. 이 라벨은 Deployment에서만 지원되며 Deployment 매니페스트의metadata.labels필드에 지정해야 합니다.iam.gke.io/spiffe-identity-type: "agent-identity"주석: 에이전트가 에이전트 ID를 사용함을 나타냅니다. 이 주석은 포드 사양에 지정됩니다.registry.gke.io/functional-type: "AGENT"라벨이 배포에 지정된 경우 이 주석은 포드 사양에 필요합니다.
GKE 에이전트를 Agent Platform과 통합하려면 에이전트 ID를 사용하는 것 외에도 Agent Registry에 워크로드를 등록하세요. 에이전트 워크로드 등록을 강제하거나 배포 파이프라인에서 등록을 자동화하는 것이 좋습니다.
에이전트의 액세스 토큰
GKE에서 에이전트 ID를 사용하는 각 포드는 X.509 인증서와 포드의 비공개 키가 포함된 고유한 사용자 인증 정보 번들을 가져옵니다. 이 번들은 포드를 벗어나지 않습니다. Google Cloud API 또는 외부 서비스에 액세스하려면 GKE 클러스터의 에이전트 포드가 각 노드에서 실행되는 GKE 메타데이터 서버에서 에이전트 ID 액세스 토큰을 요청합니다. 포드는 에이전트 ID 액세스 토큰을 사용하여 에이전트 ID로 인증합니다.
액세스 토큰은 다음과 같이 바인딩되거나 바인딩되지 않을 수 있습니다.
- 바운드 액세스 토큰: 포드의 X.509 인증서에 암호화 방식으로 바인딩되며 해당 X.509 인증서를 사용하여 인증된 mTLS 연결을 통해서만 사용할 수 있습니다. 페이로드에 X.509 인증서가 포함된 액세스 토큰 요청은 바인드된 토큰을 생성합니다.
- 바인드되지 않은 액세스 토큰: 특정 포드에 암호화 방식으로 바인드되지 않으며 비 mTLS 연결을 통해 사용할 수 있습니다. 바인딩되지 않은 액세스 토큰은 유출된 토큰이 다른 Pod에서 사용될 수 있으므로 토큰 재사용 공격에 더 취약합니다.
에이전트는 바인딩된 액세스 토큰 또는 바인딩되지 않은 액세스 토큰을 사용하여Google Cloud API에 대한 요청을 인증합니다. ID 관리자는 에이전트의 Google Cloud 리소스에 대한 액세스 제어에 설명된 대로 IAM 정책에서 해당 에이전트 ID 액세스 토큰의 주 구성원 식별자를 지정하여 에이전트가 갖는 액세스 권한을 제어할 수 있습니다.
포드에 iam.gke.io/inject-podcertificates: "true" 주석이 있으면 Cloud 클라이언트 라이브러리와 Google 인증 라이브러리가 애플리케이션 기본 사용자 인증 정보 (ADC)를 사용하여 포드의 바인드된 에이전트 ID 액세스 토큰을 자동으로 가져옵니다. 이 자동 프로세스는 모든 라이브러리 또는 프로그래밍 언어에서 발생하지 않을 수 있습니다. 대신 바인딩되지 않은 액세스 토큰을 요청하려면 개발자가 다음 방법 중 하나를 사용합니다.
포드 사양에서
iam.gke.io/inject-podcertificates: "true"주석을 지정하고GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN환경 변수를false값으로 설정합니다. GKE는 X.509 사용자 인증 정보 번들을 포드에 추가하지만 환경 변수로 인해 ADC가 바인드되지 않은 액세스 토큰을 가져옵니다.이 방법을 사용하면 포드가 인증서를 사용하여 다른 워크로드와 mTLS 연결을 계속 설정하면서 바인딩되지 않은 액세스 토큰을 사용하여 Google Cloud API에 액세스할 수 있습니다.
포드 사양에
iam.gke.io/inject-podcertificates: "true"주석을 지정하지 마세요. GKE는 X.509 사용자 인증 정보 번들을 포드에 추가하지 않으므로 ADC는 포드의 바인딩되지 않은 액세스 토큰을 가져옵니다.바인딩되지 않은 액세스 토큰을 반환하는 GKE 메타데이터 서버의 토큰 엔드포인트로 직접 HTTP
GET요청을 보냅니다.
상담사 인증 워크플로
비에이전트 워크로드와 달리 에이전트는 에이전트가 시도하는 작업에 따라 최종 사용자를 대신하여 또는 에이전트 자체 ID로 서비스에 인증해야 할 수 있습니다. 에이전트 ID는 다양한 사용자 인증 정보와 인증 모델을 사용하여 다음 유형의 리소스에 대한 인증을 지원합니다.
- Google Cloud API
- 외부 도구 및 서비스
- 에이전트 간 인증
Google Cloud API에 인증
에이전트는 자체 ID를 사용하여 BigQuery 또는 Agent Platform과 같은 Google Cloud API에 인증할 수 있습니다. 인증을 위해 포드는 노드의 GKE 메타데이터 서버에서 에이전트 ID 액세스 토큰을 가져옵니다. 이 액세스 토큰은 선택적으로 포드의 X.509 인증서에 바인딩될 수 있습니다. 즉, 액세스 토큰은 X.509 인증서를 사용하여 인증된 mTLS 연결을 통해서만 사용할 수 있습니다.
애플리케이션에서 google-auth Python 인증 라이브러리 버전 2.61.0 이상을 사용하는 경우 애플리케이션 기본 사용자 인증 정보 (ADC)는 에이전트 ID 사용자 인증 정보 번들이 있는 포드의 바인드된 액세스 토큰을 자동으로 요청합니다. Python용 Cloud 클라이언트 라이브러리를 사용하는 경우 google-auth 라이브러리의 버전 2.61.0 이상이 포함된 버전을 사용해야 합니다. 다른 프로그래밍 언어 또는 google-auth Python 라이브러리 버전이 2.61.0보다 이전인 경우 바인딩되지 않은 액세스 토큰을 대신 요청하세요.
바인딩된 액세스 토큰을 가져온 경우 포드의 X.509 인증서를 사용하여 대상 API의 mTLS 엔드포인트와 mTLS 연결을 설정해야 합니다. 바인드되지 않은 액세스 토큰을 가져온 경우 해당 API의 비 mTLS 엔드포인트에 대한 요청에서 해당 토큰을 사용할 수 있습니다.
이러한 메서드를 사용하여 바인딩된 액세스 토큰 또는 바인딩 해제된 액세스 토큰을 가져오도록 애플리케이션 코드를 구성하려면 GKE에서 에이전트 ID를 사용하여 인증을 참고하세요.
플랫폼 관리자 또는 보안 관리자인 경우Google Cloud API에 인증하는 에이전트에 대해 추가 인증을 구성할 필요가 없습니다. 에이전트의 Google Cloud 리소스에 대한 액세스 제어에 설명된 대로 IAM 정책을 사용하여 리소스에 대한 액세스를 제어할 수 있습니다.
외부 서비스에 대한 에이전트 인증
에이전트는 API 키 또는 OAuth 토큰과 같은 특정 사용자 인증 정보를 사용하여 외부 도구 및 서비스에 액세스해야 하는 경우가 많습니다. 에이전트는 자체 ID로 또는 최종 사용자를 대신하여 인증해야 할 수 있습니다. 에이전트 ID 인증 관리자 (미리보기)를 사용하여 에이전트에게 특정 사용자 인증 정보를 제공할 수 있습니다. 인증 관리자는 Google Cloud에서 실행하는 에이전트의 사용자 인증 정보 획득 및 인증 워크플로 구성을 중앙 집중화합니다.
인증 관리자에서 특정 인증 워크플로를 처리하도록 인증 제공업체를 구성합니다. GKE의 에이전트가 특정 사용자 인증 정보를 사용하여 인증해야 하는 경우 포드는 에이전트 ID 액세스 토큰을 사용하여 인증 관리자에 인증합니다. 그러면 인증 제공자가 추가 인증 단계를 처리하고 요청된 사용자 인증 정보를 포드에 반환합니다. 인증 관리자는 외부 사용자 인증 정보를 단기 액세스 토큰으로 교환하므로 장기 갱신 토큰과 API 비밀번호가 에이전트 컨테이너에 저장되지 않습니다.
다음 사용 사례에 인증 관리자를 사용할 수 있습니다. 각 사용 사례에는 인증 관리자와 애플리케이션 코드에서 특정 설정과 구성이 필요합니다.
- 최종 사용자를 대신하여 외부 서비스에 액세스합니다.
- 자체 ID로 외부 서비스에 액세스합니다.
- API 키를 사용하여 API에 액세스합니다.
인증 관리자가 만든 사용자 인증 정보를 모니터링하고 취소할 수 있습니다. 에이전트가 에이전트 ID 액세스 토큰을 사용하여 인증 관리자에 인증하므로 특정 에이전트가 사용하는 사용자 인증 정보를 추적할 수도 있습니다. 다음 섹션에서는 인증 관리자의 사용 사례와 해당 인증 모델을 설명합니다. 사용하는 인증 모델에 따라 사용자와 애플리케이션 개발자가 에이전트 코드와 클라이언트 측 애플리케이션을 특정 방식으로 변경해야 합니다.
최종 사용자를 대신한 외부 서비스 액세스
최종 사용자는 상담사에게 Slack 채널에 메시지를 작성하거나 GitHub 저장소에서 pull 요청을 여는 등 사용자를 대신하여 특정 작업을 수행해 달라고 요청할 수 있습니다. 이러한 시나리오에서 사용자는 상담사가 사용자를 대신하여 행동하는 데 명시적으로 동의하여 상담사에게 권한을 위임합니다. 사용자 동의 및 사용자 인증 정보 검색을 설정하려면 다음 단계가 포함된 3-legged OAuth를 사용합니다.
- 인증 제공자가 사용자를 리디렉션하여 외부 서비스에 인증합니다.
- 사용자가 로그인하여 에이전트에게 필요한 액세스를 승인합니다.
- 외부 서비스가 인증 제공자에게 사용자 인증 정보를 반환합니다.
GKE에서 실행되는 에이전트에 대해 3단계 OAuth를 구성하려면 플랫폼 관리자와 애플리케이션 개발자가 다음 단계를 따릅니다.
- 플랫폼 관리자가 인증 제공업체를 설정합니다.
- 인증 관리자에서 3-legged OAuth 인증 제공업체를 만듭니다.
- 서드 파티 승인 서버로 리디렉션하도록 인증 제공자를 구성합니다.
- 사용자 액세스 토큰을 인증 제공업체에 전송하도록 서드 파티 서비스를 구성합니다.
- 에이전트가 인증 제공업체에 액세스하도록 승인
- 애플리케이션 개발자가 애플리케이션을 수정합니다.
- 인증 제공업체를 사용하여 인증하도록 에이전트 코드를 수정합니다.
- 사용자 로그인, 리디렉션, 대화 재개를 처리하도록 클라이언트 측 애플리케이션 코드를 수정합니다.
인증 제공업체를 구성하고 에이전트 및 클라이언트 측 애플리케이션을 수정하는 방법에 대한 자세한 내용은 인증 관리자로 3-legged OAuth를 사용하여 인증을 참고하세요.
에이전트 ID로 외부 서비스에 액세스
에이전트가 에이전트의 자체 ID를 사용하여 ServiceNow 또는 Salesforce와 같은 외부 서비스에 액세스해야 할 수 있습니다. 예를 들어 인벤토리 관리 에이전트는 판매 데이터를 모니터링하고 재고를 주문하여 판매가 가장 많은 이벤트 기간에 재고 문제가 발생하지 않도록 할 수 있습니다. 이러한 시나리오에서는 다음 단계가 포함된 2단계 OAuth를 사용합니다.
- 인증 관리자가 외부 서비스에서 액세스 토큰을 요청합니다.
- 외부 서비스는 요청의 유효성을 검사하고 액세스 토큰을 인증 관리자에게 반환합니다.
GKE에서 실행되는 에이전트에 대해 2단계 OAuth를 구성하려면 다음 단계를 따르세요.
- 플랫폼 관리자가 인증 제공업체를 설정합니다.
- 외부 서비스에서 OAuth 클라이언트 ID, 클라이언트 보안 비밀번호, 토큰 엔드포인트를 가져옵니다.
- 외부 서비스의 OAuth 정보가 있는 인증 관리자에서 2-legged OAuth 인증 제공업체를 만듭니다.
- 에이전트가 인증 제공업체에 액세스하도록 승인
- 애플리케이션 개발자가 인증 제공업체를 사용하여 인증하도록 에이전트 코드를 수정합니다.
인증 제공업체를 구성하고 에이전트 코드를 수정하는 방법에 대한 자세한 내용은 인증 관리자로 2단계 OAuth를 사용하여 인증을 참고하세요.
API 키를 사용하여 API에 액세스
에이전트가 외부 API에 인증하는 데 사용할 수 있도록 인증 관리자에 API 키를 저장할 수 있습니다. Secret Manager와 같은 다른 보관소에 API 키를 저장할 수 있지만 인증 관리자 메서드를 사용하면 중앙 위치에서 API 키에 대한 에이전트 액세스를 추적하고 관리할 수 있습니다. 인증 관리자에 API 키를 저장하고 사용하려면 다음을 실행하세요.
- 플랫폼 관리자가 인증 제공업체를 설정합니다.
- 인증 관리자에서 API 키 인증 제공업체를 만듭니다.
- 인증 제공업체에서 API 키를 생성하고 저장합니다.
- 에이전트가 인증 제공업체에 액세스하도록 승인
- 인증 제공업체를 사용하여 인증하도록 에이전트 코드를 수정합니다.
자세한 내용은 인증 관리자로 API 키를 사용하여 인증을 참고하세요.
에이전트 간 인증
이 섹션에서는 고급 인증 워크플로를 설명합니다. 다음 주제에 익숙해야 합니다.
- JSON 웹 토큰 (JWT): 에이전트 ID 토큰은 서명된 JWT입니다.
- JSON 객체 서명 및 암호화 (JOSE) 헤더: ID 토큰에는 ID 토큰의 알고리즘과 서명 키를 설명하는 JOSE 헤더가 있습니다.
- JSON 웹 키 (JWK): JWK는 ID 토큰에 서명하는 데 사용됩니다. 에이전트 ID 풀의 공개 JWK는 JSON 웹 키 세트 (JWKS)로 게시됩니다. 이러한 공개 키를 사용하여 다른 에이전트로부터 수신되는 ID 토큰을 검증합니다.
멀티 에이전트 아키텍처에서 에이전트는 피어 에이전트 또는 다운스트림 서비스를 직접 호출하여 자주 공동작업합니다. GKE 메타데이터 서버에서 가져올 수 있는 서명된 JWT인 에이전트 IDID 토큰을 사용하여 에이전트 워크로드 간에 직접 통신을 설정할 수 있습니다. 에이전트 서비스 간 연결을 인증하려면 애플리케이션 개발자는 다음을 실행합니다.
- 호출 에이전트의 GKE 메타데이터 서버에서 에이전트 ID 토큰을 가져옵니다. 이 ID 토큰은
aud클레임을 수신 에이전트의 엔드포인트로 설정해야 합니다. - ID 토큰을 HTTP 요청의
Authorization: Bearer요청 헤더에 포함합니다. - 수신 에이전트에서 에이전트 ID 풀의 공개 JWK와 ID 토큰의 다양한 헤더 및 본문 매개변수를 사용하여 수신 ID 토큰을 검증합니다.
애플리케이션 코드에서 ID 토큰을 요청, 사용, 검증하는 방법에 대한 자세한 내용은 다른 에이전트에 인증을 참고하세요.
이 워크플로는 IAM 승인 확인을 우회하므로 에이전트 간 인증에는 플랫폼 관리자의 추가 Google Cloud구성이 필요하지 않습니다. 대신 에이전트가 서로 직접 통신하고 에이전트 ID를 기반으로 작업을 승인합니다.
상담사의 Google Cloud 리소스 액세스 제어
보안 관리자는 에이전트의 주 구성원 식별자를 참조하는 IAM 정책을 사용하여 에이전트가 액세스할 수 있는 리소스를 제어할 수 있습니다. GKE에서 실행되고 에이전트 ID가 있는 에이전트의 리소스 액세스를 제어하려면 IAM 정책에 다음 보안 주체 식별자 중 하나를 포함하세요.
특정 트러스트 도메인의 모든 에이전트:
principalSet://TRUST_DOMAIN/*이 식별자에서
TRUST_DOMAIN는 리소스 계층 구조의 신뢰 도메인이며, 이는 에이전트가 조직에 속한 프로젝트에 있는지 여부에 따라 달라집니다.- 조직에 속한 프로젝트:
agents.global.org-ORGANIZATION_ID.system.id.goog, 여기서ORGANIZATION_ID는 조직의 ID입니다. - 조직에 속하지 않는 프로젝트:
agents.global.proj-PROJECT_NUMBER.system.id.goog(여기서PROJECT_NUMBER은 클러스터 프로젝트의 프로젝트 번호임)
- 조직에 속한 프로젝트:
트러스트 도메인의 단일 에이전트:
principal://TRUST_DOMAIN/resources/container/projects/PROJECT_NUMBER/locations/CONTROL_PLANE_LOCATION/clusters/CLUSTER_NAME/ns/NAMESPACE_NAME/sa/SERVICEACCOUNT_NAME이 식별자에서 다음 매개변수는 특정 에이전트를 식별합니다.
PROJECT_NUMBER: 클러스터 프로젝트의 프로젝트 번호입니다.CONTROL_PLANE_LOCATION: 클러스터 컨트롤 플레인의 리전 또는 영역입니다.CLUSTER_NAME: 에이전트가 있는 클러스터의 이름입니다.NAMESPACE_NAME: 에이전트가 있는 Kubernetes 네임스페이스의 이름입니다.SERVICEACCOUNT_NAME: 에이전트 워크로드에서 사용하는 Kubernetes 서비스 계정의 이름입니다.
GKE 에이전트의 주 구성원 식별자를 찾고 액세스를 관리하는 방법에 대한 자세한 내용은 에이전트의 Google Cloud API에 대한 액세스 관리를 참고하세요.
에이전트 ID는 허용 정책, 거부 정책, 보안 주체 액세스 경계 (PAB) 정책과 같은 모든 IAM 정책 유형을 지원합니다. 에이전트 ID를 사용하는 GKE 클러스터에서 에이전트의 액세스 권한을 관리하려면 해당 정책 유형에 에이전트의 보안 주체 식별자를 포함합니다. 각 유형의 IAM 정책을 구성하는 방법에 대한 자세한 내용은 다음 주제를 참고하세요.
Google Cloud에서 에이전트 보기 및 관리
애플리케이션 개발자가 에이전트를 에이전트 레지스트리에 등록하면 Google Cloud에서 실행하는 다른 에이전트와 함께 GKE 에이전트를 볼 수 있습니다. Agent Registry에는 에이전트의 SPIFFE ID, 에이전트가 실행되는 위치, 에이전트에 관한 추가 정보가 표시됩니다. 에이전트 ID를 사용하여 인증된 모든 API 요청은 에이전트 레지스트리 감사 로그를 생성합니다. 에이전트가 사용하는 인증 워크플로에 따라 Cloud 감사 로그는 다음 정보를 제공합니다.
- 에이전트의 자체 ID를 사용한 인증: 생성된 감사 로그에는 에이전트의 주 구성원 식별자가 포함되어 있으며 이를 사용하여 에이전트의 클러스터, 네임스페이스, ServiceAccount를 찾을 수 있습니다.
- 최종 사용자를 대신한 위임된 작업: 생성된 감사 로그에는 작업을 승인한 최종 사용자 및 호출을 실행한 에이전트의 SPIFFE ID에 관한 정보가 포함됩니다. 감사 로그의 이 ID 연결은 최종 사용자가 특정 작업을 승인했는지 확인하는 데 도움이 됩니다.
Cloud 감사 로그 외에도 애플리케이션 개발자는 Google Cloud Observability에 표시되는 트레이스, 로그, 측정항목을 내보내도록 에이전트 워크로드를 구성할 수 있습니다. 워크로드를 구성하는 방법에 관한 자세한 내용은 다음 문서를 참고하세요.
GKE 에이전트의 보안 개선
보안 관리자는 에이전트 ID를 참조하여 다른 유형의 워크로드 제약 조건과 별도로 에이전트별 보안 조치를 관리할 수 있습니다. 에이전트를 실행할 때 다음 방어 조치를 고려하세요.
- 보안이 취약한 에이전트의 영향을 제한하려면 에이전트 ID에 보안 주체 액세스 경계 정책 (PAB 정책)을 구성하세요.
- 인증 관리자 인증 제공업체의 보안을 개선하려면 에이전트 ID에 대한 조직 정책을 구성하세요.
- 에이전트 관리를 중앙 집중화하고 리소스 전반에서 에이전트 작업을 추적하려면 ValidatingAdmissionPolicies 및 MutatingAdmissionPolicies와 같은 허용 컨트롤러를 사용하여 주석과 라벨로 에이전트 레지스트리 등록을 적용하세요.
- 직접 에이전트 간 트래픽의 보안을 관리하려면 다음 제어를 사용하세요.
- 동일한 클러스터의 포드 간 트래픽을 제어하려면 Kubernetes NetworkPolicies를 사용합니다.
- 침해 시 데이터 무단 반출 위험을 줄이려면 VPC 서비스 제어를 사용하세요.
- VPC 네트워크 간 및 서로 다른 환경에서 실행되는 에이전트 간의 네트워크 트래픽을 제어하려면 VPC 네트워크 방화벽 정책 및 Cloud Next Generation Firewall (Cloud NGFW)을 사용하세요.
- 에이전트 레지스트리에 등록된 에이전트 간 트래픽에 IAM 정책을 적용하려면 Agent Gateway를 사용하세요.
제한사항
- 에이전트 레지스트리에 배포만 자동으로 등록할 수 있습니다. 다른 워크로드 컨트롤러와 정적 포드는 자동 등록을 지원하지 않습니다.
- 바인드된 에이전트 ID 액세스 토큰은
https://www.googleapis.com/auth/cloud-platformOAuth 범위만 사용합니다. 바인딩된 액세스 토큰에 다른 범위를 지정할 수 없습니다. - 바인드된 액세스 토큰 또는 ID 토큰의 자동 검색은
google-auth라이브러리 버전 2.61.0 이상을 사용하는 Python 애플리케이션에서만 지원됩니다. Python용 Cloud 클라이언트 라이브러리를 사용하는 경우google-auth라이브러리 버전 2.61.0 이상이 포함된 버전을 사용해야 합니다. - 특정 Cloud 클라이언트 라이브러리는 요청을 mTLS 엔드포인트로 자동 라우팅하지 않을 수 있습니다.
- 에이전트 간 인증의 경우 바인드된 ID 토큰을 사용하여 동일한 에이전트 ID 신뢰 도메인에 있는 에이전트 간에만 인증할 수 있습니다.