에이전트의 Google Cloud API에 대한 액세스 관리

애플리케이션 개발자는 Google Kubernetes Engine (GKE)에서 실행되는 AI 에이전트의 에이전트 ID를 요청할 수 있습니다. 에이전트 ID는 워크로드의 각 포드에 암호화 방식으로 바인딩할 수 있는 포드별 ID입니다. 그런 다음 에이전트는 에이전트 ID를 사용하여 Google Cloud API에 인증할 수 있습니다. Identity and Access Management (IAM) 정책에 에이전트를 주 구성원으로 포함하여 에이전트가 액세스할 수 있는 리소스를 제어할 수 있습니다. 이 문서에서는 에이전트 ID를 사용하는 에이전트의 Google Cloud API 및 서비스에 대한 액세스를 관리하는 방법을 설명합니다.

이 문서는 개발자가 GKE 클러스터에 배포하는 에이전트의 승인을 관리하는 보안 관리자 및 플랫폼 관리자를 대상으로 합니다. 다음 주제에 이미 익숙해야 합니다.

시작하기 전에

시작하기 전에 다음 태스크를 수행했는지 확인합니다.

  • Google Kubernetes Engine API를 사용 설정합니다.
    • Google Kubernetes Engine API 사용 설정
  • 이 태스크에 Google Cloud CLI를 사용하려면 gcloud CLI를 설치한 후 초기화합니다. 이전에 gcloud CLI를 설치했으면 gcloud components update 명령어를 실행하여 최신 버전을 가져옵니다. 이전 gcloud CLI 버전에서는 이 문서의 명령어를 실행하지 못할 수 있습니다.
  • GKE용 워크로드 아이덴티티 제휴가 사용 설정되어 있고 GKE 버전 1.37.0-gke.3503000 이상을 실행하는 기존 Autopilot 클러스터 또는 Standard 클러스터가 있는지 확인합니다.

필요한 역할

에이전트의 Google Cloud API 액세스를 관리하는 데 필요한 권한을 얻으려면 관리자에게 Google Cloud 프로젝트에 대해 다음 IAM 역할을 부여해 달라고 요청하세요.

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

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

에이전트의 보안 주체 식별자 찾기

이 섹션에서는 에이전트의 주 구성원 식별자를 구성하는 방법을 설명합니다. IAM 정책에서 이 식별자를 사용하여 에이전트가 액세스할 수 있는 리소스를 제어할 수 있습니다.

에이전트 아이덴티티를 요청하는 에이전트 워크로드에는 해당 워크로드에 고유한 SPIFFE 아이덴티티 문자열이 부여됩니다. 애플리케이션이 Google Cloud API를 호출하면 워크로드에 에이전트 ID가 있음을 검증하는 에이전트 ID 액세스 토큰을 사용하여 호출이 인증됩니다. 이 액세스 토큰에는 에이전트 워크로드의 IAM 주 구성원 식별자가 포함되어 있으며, 이를 IAM 정책에 포함하여 에이전트가 액세스할 수 있는 리소스를 제어할 수 있습니다.

IAM 정책을 설계할 때 다음 정보를 사용하여 에이전트의 주 구성원 식별자를 구성할 수 있습니다.

  • 프로젝트의 리소스 계층 구조입니다.
  • 클러스터 이름
  • Kubernetes 네임스페이스와 해당 네임스페이스의 Kubernetes ServiceAccount입니다.

개발자가 주 구성원 식별자와 일치하는 에이전트 ID를 가져오는 에이전트를 배포하면 에이전트가 정책에 지정된 액세스 권한을 상속합니다.

정책에서 사용할 주 구성원 식별자를 찾으려면 다음 단계를 따르세요.

  1. ID의 트러스트 도메인을 식별합니다. 트러스트 도메인은 프로젝트가 조직에 있는지에 따라 다음과 같이 달라집니다.

    • 조직에 속한 프로젝트:

      agents.global.org-ORGANIZATION_ID.system.id.goog

      ORGANIZATION_ID를 조직 ID로 바꿉니다.

    • 조직에 속하지 않는 프로젝트:

      agents.global.proj-PROJECT_NUMBER.system.id.goog

      PROJECT_NUMBER를 클러스터의 프로젝트의 프로젝트 번호로 바꿉니다.

  2. 클러스터에 관한 다음 정보를 확인합니다.

    • GKE 클러스터의 이름입니다.
    • 클러스터 컨트롤 플레인의 위치입니다(예: us-central1).
    • 개발자가 워크로드를 배포하는 Kubernetes 네임스페이스입니다.
    • 개발자가 에이전트 워크로드에 사용해야 하는 Kubernetes ServiceAccount의 이름입니다.

    이 정보를 모르는 경우 플랫폼팀에 문의하세요. 플랫폼팀은 액세스 요구사항이 서로 다른 에이전트가 서로 다른 ID를 갖도록 클러스터에서 네임스페이스, ServiceAccount, RBAC 정책을 설정해야 합니다.

  3. 주 구성원 식별자를 구성합니다.

    principal://TRUST_DOMAIN/resources/container/projects/PROJECT_NUMBER/locations/CONTROL_PLANE_LOCATION/clusters/CLUSTER_NAME/ns/KUBERNETES_NAMESPACE/sa/KUBERNETES_SERVICEACCOUNT

    다음을 바꿉니다.

    • TRUST_DOMAIN: 에이전트 ID의 트러스트 도메인입니다.
    • PROJECT_NUMBER: 클러스터 프로젝트의 프로젝트 번호입니다.
    • CONTROL_PLANE_LOCATION: 클러스터 컨트롤 플레인의 리전 또는 영역입니다.
    • CLUSTER_NAME: 클러스터의 이름입니다.
    • KUBERNETES_NAMESPACE: Kubernetes 네임스페이스의 이름입니다.
    • KUBERNETES_SERVICEACCOUNT: Kubernetes 서비스 계정의 이름입니다.

정책을 사용하여 액세스 제어

이 섹션에서는 에이전트의 주 구성원 식별자를 사용하여 에이전트가 액세스할 수 있는 Google Cloud API 및 서비스를 제어하는 방법을 설명합니다. 액세스를 제어하려면 다음 IAM 정책 중 하나에 주 구성원 식별자를 포함하세요.

정책을 만들거나 업데이트한 후 에이전트 ID를 요청하고 해당 네임스페이스에서 실행되며 해당 ServiceAccount를 사용하는 모든 에이전트는 정책에 지정된 액세스 권한을 갖습니다.

상담사가 인증 관리자에 액세스하도록 승인

에이전트 ID 인증 관리자는 에이전트가 에이전트 자체의 ID로 또는 최종 사용자를 대신하여 외부 도구 및 서비스에 액세스할 사용자 인증 정보를 가져오는 데 사용할 수 있는 인증 브로커이자 사용자 인증 정보 보관소입니다. 인증 관리자에는 하나 이상의 인증 제공자가 있을 수 있으며 각 인증 제공자는 특정 서비스의 특정 인증 및 사용자 인증 정보 획득 흐름을 처리합니다. GKE 에이전트가 특정 인증 제공업체에 액세스하도록 하려면 다음 단계를 따르세요.

  1. 에이전트의 주 구성원 식별자를 찾습니다.
  2. 에이전트가 액세스해야 하는 인증 제공업체의 이름을 가져옵니다.

  3. 인증 제공업체에서 에이전트 주 구성원에게 에이전트 ID 사용자 (roles/agentidentity.user) 역할을 부여합니다.

    gcloud agent-identity auth-providers add-iam-policy-binding AUTH_PROVIDER_NAME \
    --location=AUTH_PROVIDER_LOCATION \
    --member=PRINCIPAL_IDENTIFIER \
    --role=roles/agentidentity.user

    다음을 바꿉니다.

    • AUTH_PROVIDER_NAME: 인증 제공업체의 이름입니다.
    • AUTH_PROVIDER_LOCATION: 인증 제공업체의 리전입니다.
    • PRINCIPAL_IDENTIFIER: 에이전트의 주 구성원 식별자입니다.

    또는 에이전트 등록부에 등록된 에이전트의 경우 인증 제공업체 바인딩을 만들어 인증 제공업체에 대한 액세스 권한을 관리할 수 있습니다.

다음 단계