크로스 클라우드용 Agent Gateway 설정

이 가이드에서는 표준 Kubernetes 클러스터에 크로스 클라우드용 Agent Gateway를 배포하여 Gemini Enterprise Agent Platform 거버넌스를 환경으로 확장하는 방법을 설명합니다. 3계층 아키텍처에 대한 개요는 크로스 클라우드용 Agent Gateway 개요를 참조하세요.

시작하기 전에

시작하기 전에 다음 사항을 확인하세요.

  • Cloud Native Computing Foundation(CNCF) 호환 Kubernetes 클러스터
  • 클러스터에 구성된 기존 서비스 메시 또는 네트워크 스택
  • HTTPS(TCP 포트 443)를 통해 클러스터에서 Google Cloud API로의 아웃바운드 네트워크 연결
  • Google Cloud CLI 버전 591.0.0 이상이 설치되어 있어야 합니다. 최신 버전으로 업데이트하려면 gcloud components update를 실행합니다.
  • API를 사용 설정하고, 워크로드 아이덴티티 풀과 공급업체를 만들고, IAM 역할을 부여하는 데 필요한 Google Cloud 프로젝트의 Identity and Access Management(IAM) 역할

API 사용 설정 및 클러스터 등록

필요한 Google Cloud API를 사용 설정한 후 외부 클러스터를 등록합니다.

필요한 API 사용 설정

크로스 클라우드용 Agent Gateway에 필요한 API를 사용 설정하려면 다음 명령어를 실행합니다.

gcloud services enable \
    agentregistry.googleapis.com \
    apphubendpoint.googleapis.com \
    cloudresourcemanager.googleapis.com \
    cloudtrace.googleapis.com \
    iam.googleapis.com \
    iamcredentials.googleapis.com \
    iap.googleapis.com \
    logging.googleapis.com \
    modelarmor.googleapis.com \
    monitoring.googleapis.com \
    networkservices.googleapis.com \
    serviceextensions.googleapis.com \
    sts.googleapis.com \
    telemetry.googleapis.com \
    trafficdirector.googleapis.com \
    --project=PROJECT_ID

PROJECT_ID를Google Cloud 프로젝트 ID로 바꿉니다.

Kubernetes API 서버 공개 키 추출

클러스터를 등록하려면 클러스터가 서비스 계정 토큰에 서명하는 데 사용하는 공개 키가 필요합니다. 공개 키를 추출하려면 다음을 수행합니다.

  1. 현재 kubectl 컨텍스트를 등록하려는 클러스터로 설정합니다.

  2. 클러스터의 JSON 웹 키 세트(JWKS)를 가져온 후 첫 번째 RSA 키를 pubkey.pem라는 공개 키 파일로 변환합니다.

    kubectl get --raw /openid/v1/jwks > cluster-jwks.json
    
    N_HEX=$(jq -r '[.keys[] | select((.kty // "" | ascii_upcase) == "RSA" and (.n // "") != "" and (.e // "") != "")][0].n | gsub("-";"+") | gsub("_";"/") | . + ("==="[:(4 - length % 4) % 4])' cluster-jwks.json | base64 -d | od -An -tx1 | tr -d ' \n')
    E_HEX=$(jq -r '[.keys[] | select((.kty // "" | ascii_upcase) == "RSA" and (.n // "") != "" and (.e // "") != "")][0].e | gsub("-";"+") | gsub("_";"/") | . + ("==="[:(4 - length % 4) % 4])' cluster-jwks.json | base64 -d | od -An -tx1 | tr -d ' \n')
    
    openssl asn1parse -genconf <(printf "asn1=SEQUENCE:rsa_key\n[rsa_key]\nmodulus=INTEGER:0x%s\nexponent=INTEGER:0x%s\n" "$N_HEX" "$E_HEX") -noout -out /dev/stdout \
      | openssl rsa -RSAPublicKey_in -inform DER -pubout -out pubkey.pem
    

    이러한 명령어를 사용하려면 Bash 셸과 jq 및 openssl 유틸리티가 필요합니다.

클러스터 등록

클러스터를 등록하려면 다음을 수행합니다.

  1. 클러스터의 OpenID Connect(OIDC) 발급기관 URL을 검색합니다.

    kubectl get --raw /.well-known/openid-configuration | jq -r '.issuer'
    

    출력은 클러스터의 Kubernetes API 서버의 --service-account-issuer 플래그 값입니다. 이 값은 Kubernetes API 서버의 외부 URL과 다를 수 있습니다. 출력을 정확하게 복사합니다. 후행 슬래시를 추가하거나 삭제하지 마세요.

  2. 클러스터를 등록합니다.

    gcloud alpha network-services registered-clusters create CLUSTER_NAME \
        --project=PROJECT_ID \
        --location=LOCATION \
        --oidc-issuer-url=OIDC_ISSUER_URL \
        --api-server-public-key="$(cat pubkey.pem)"
    

    다음을 바꿉니다.

    • CLUSTER_NAME: 등록된 클러스터의 이름입니다.
    • PROJECT_ID: Google Cloud프로젝트의 ID
    • LOCATION: 등록된 클러스터의 Google Cloud 리전입니다(예: us-central1).
    • OIDC_ISSUER_URL: 이전 단계에서 검색한 정확한 발급기관 URL입니다. URL은 https://으로 시작해야 합니다.

실수로 인한 리소스 삭제 방지

크로스 클라우드 워크로드가 활성 상태인 동안 Google Cloud 프로젝트를 삭제하거나 등록된 클러스터를 등록 취소하면 클러스터 내 컨트롤러의 연결이 끊어지고 정책 시행이 중단됩니다. 실수로 삭제되지 않도록 Google Cloud 리소스를 보호하려면 다음 안전장치를 적용하세요.

  • 선취권으로 Google Cloud 프로젝트 보호: 등록된 클러스터, 에이전트 레지스트리, 제휴 ID 풀을 호스팅하는Google Cloud 프로젝트에 프로젝트 선취권을 적용하여 모든 크로스 클라우드 클러스터가 사용 중지될 때까지 실수로 프로젝트가 삭제되지 않도록 차단합니다.
  • 파괴적인 IAM 권한 제한: 등록된 클러스터 또는 게이트웨이 리소스(예: networkservices.registeredClusters.delete 및 networkservices.agentGateways.delete)를 삭제할 수 있는 권한을 전용 플랫폼 관리자 역할로 제한합니다.
  • Kubernetes 리소스 종료자 유지: agent-governance-cross-cloud-controller 컨트롤러에서 관리하는 클러스터 내 커스텀 리소스에서 종료자를 삭제하지 않습니다. 파이널라이저는 로컬 클러스터 리소스가 삭제되기 전에 해당 Google Cloud 컨트롤 플레인 등록이 완전히 프로비저닝 해제되도록 합니다.
  • 컨트롤러를 삭제하기 전에 커스텀 리소스 삭제: agent-governance-cross-cloud Helm 차트를 제거하거나 Kubernetes 클러스터를 삭제하기 전에 모든 GCPExtensionBinding 및 GCPAgentGateway 커스텀 리소스를 삭제하고 삭제가 완료될 때까지 기다립니다. 컨트롤러를 먼저 삭제하면 해당 Agent Gateway 리소스가 Network Services에서 분리된 상태로 유지됩니다. 분리된 게이트웨이는 에이전트 연결 템플릿과 등록된 클러스터의 삭제를 차단합니다.

워크로드 아이덴티티 제휴 구성

크로스 클라우드용 Agent Gateway의 클러스터 내 구성요소(agent-governance-cross-cloud-controller 컨트롤러, 원격 분석 수집기, 프록시)는 워크로드 아이덴티티 제휴를 사용하여Google Cloud API에 인증합니다. 각 구성요소는 Kubernetes 서비스 계정(KSA) 토큰을 제휴 액세스 토큰으로 교환합니다. 이러한 제휴 ID에 IAM 역할을 직접 부여하므로Google Cloud 서비스 계정을 만들거나 클러스터에 서비스 계정 키를 저장할 필요가 없습니다.

각 프록시와 함께 실행되는 에이전트 ID 런타임(AIR) 사이드카는 워크로드 아이덴티티 풀을 사용하여 에이전트 워크로드에 SPIFFE ID를 제공합니다. 이러한 ID는 에이전트의 에이전트 ID입니다. Model Armor 및 IAP 정책은 클러스터 내 구성요소의 제휴 ID가 아닌 에이전트 ID로 에이전트를 식별합니다. 주 구성원 형식은 에이전트 보안 주체 식별을 참조하세요.

워크로드 아이덴티티 풀 및 공급업체 만들기

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

  1. 클러스터의 OIDC 발급기관 URL에 공개적으로 연결할 수 없는 경우 클러스터의 JSON 웹 키 세트(JWKS)를 파일에 저장합니다.

    kubectl get --raw /openid/v1/jwks > cluster-jwks.json
    

    JWKS를 제공업체에 제공하면 Google Cloud 에서 클러스터의 OIDC 발급기관에 연결하지 않고도 KSA 토큰을 확인할 수 있습니다.

  2. 워크로드 아이덴티티 풀 만들기

    gcloud iam workload-identity-pools create POOL_ID \
        --project=PROJECT_ID \
        --location=global \
        --display-name="POOL_DISPLAY_NAME"
    
  3. 풀에 OIDC 공급업체를 만듭니다.

    gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
        --project=PROJECT_ID \
        --location=global \
        --workload-identity-pool=POOL_ID \
        --issuer-uri=OIDC_ISSUER_URL \
        --jwk-json-path=cluster-jwks.json \
        --attribute-mapping="google.subject=assertion.sub,attribute.namespace=assertion['kubernetes.io']['namespace'],attribute.service_account=assertion['kubernetes.io']['serviceaccount']['name']"
    

    --allowed-audiences 플래그를 지정하지 마세요. 크로스 클라우드 구성요소는 제공업체의 전체 리소스 이름인 기본 대상의 토큰을 요청합니다. //iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID

다음을 바꿉니다.

  • POOL_ID: 워크로드 아이덴티티 풀의 ID입니다.
  • PROJECT_ID: Google Cloud 프로젝트 ID입니다.
  • POOL_DISPLAY_NAME: 풀의 표시 이름입니다.
  • PROVIDER_ID: OIDC 공급업체의 ID입니다.
  • OIDC_ISSUER_URL: 클러스터를 등록할 때 검색한 정확한 OIDC 발급기관 URL입니다. 이 값은 후행 슬래시로 끝나는지 여부를 포함하여 --oidc-issuer-url에 전달한 값과 일치해야 합니다.

컨트롤 플레인 배포

제공된 Helm 차트를 사용하여 geap-system 네임스페이스에 클러스터 내 컨트롤러, agent-governance-cross-cloud-controller, 원격 분석 수집기를 배포합니다.

컨트롤러 연결 확인

클러스터 방화벽, 프록시, 이그레스 규칙, 네트워크 정책에서 다음 연결을 허용하는지 확인합니다.

  • Google Cloud API: agent-governance-cross-cloud-controller 컨트롤러 포드와 원격 분석 수집기에는 TCP 포트 443에서 *.googleapis.com로의 아웃바운드 HTTPS 및 gRPC 연결이 있어야 합니다.
  • Kubernetes API 서버: 컨트롤러 포드가 Kubernetes API 서버에 연결하여 Kubernetes 서비스, 워크로드, 커스텀 리소스를 감시할 수 있어야 합니다.
  • 모든 네임스페이스의 에이전트 워크로드: 컨트롤러 포드는 클러스터의 모든 네임스페이스에서 에이전트 및 MCP 서버 포드를 호출할 수 있어야 합니다. 컨트롤러는 각 에이전트 워크로드에서 에이전트 카드를 가져와 Agent Registry에 에이전트를 등록합니다.

컨트롤러 및 원격 분석 수집기에 IAM 역할 부여

geap-system 네임스페이스에서 실행되는 agent-governance-cross-cloud-controller 컨트롤러 및 원격 분석 수집기의 제휴 ID에 IAM 역할을 부여합니다.

  • 위성 사업자(roles/networkservices.satelliteOperator)
  • Cloud 원격 분석 작성자(roles/telemetry.writer)

역할을 부여하려면 다음 명령어를 실행합니다.

for ROLE in \
    roles/networkservices.satelliteOperator \
    roles/telemetry.writer; do
  gcloud projects add-iam-policy-binding PROJECT_ID \
      --role="${ROLE}" \
      --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.namespace/geap-system"
done

다음을 바꿉니다.

컨트롤 플레인 Helm 차트 설치

컨트롤 플레인을 설치하려면 다음을 수행합니다.

  1. geap-system 네임스페이스에 agent-governance-cross-cloud Helm 차트를 설치합니다.

    helm upgrade --install agent-governance-cross-cloud \
        oci://gcr.io/gke-release/agent-governance-cross-cloud \
        --version 0.1.1-preview \
        --namespace geap-system \
        --create-namespace \
        --set gcp.projectId=PROJECT_ID \
        --set-string gcp.projectNumber=PROJECT_NUMBER \
        --set-string gcp.orgId=ORGANIZATION_ID \
        --set gcp.location=LOCATION \
        --set gcp.registeredCluster=CLUSTER_NAME \
        --set gcp.workloadIdentityPool=POOL_ID \
        --set gcp.identityProvider=PROVIDER_ID
    

    다음을 바꿉니다.

    • PROJECT_ID: Google Cloud 프로젝트 ID입니다.
    • PROJECT_NUMBER: Google Cloud 프로젝트 번호
    • ORGANIZATION_ID:Google Cloud 조직의 ID입니다. 프로젝트가 조직과 연결되지 않은 경우 --set-string gcp.orgId 플래그를 생략합니다.
    • LOCATION: 클러스터를 등록한 리전입니다(예: us-central1).
    • CLUSTER_NAME: 등록된 클러스터의 이름입니다.
    • POOL_ID: 워크로드 아이덴티티 풀의 ID입니다.
    • PROVIDER_ID: 워크로드 아이덴티티 풀 공급업체의 ID입니다.

    클러스터 노드에 taint가 있는 경우(예: Google Cloud, AWS, Azure를 포함한 대부분의 클라우드 제공업체의 arm64 노드) k8s.tolerations Helm 값에 포드 톨러레이션을 설정합니다. 톨러레이션(toleration)은 컨트롤러, OpenTelemetry(OTel) 수집기, 컨트롤러가 만드는 게이트웨이 배포에 적용됩니다. 예를 들어 다음을 tolerations-values.yaml로 저장한 후 이전 명령어에 --values tolerations-values.yaml를 추가합니다.

    k8s:
      tolerations:
      - key: "kubernetes.io/arch"
        operator: "Equal"
        value: "arm64"
        effect: "NoSchedule"
    
  2. 컨트롤러 배포가 준비될 때까지 기다립니다.

    kubectl rollout status deployment/agent-governance-cross-cloud-controller \
        --namespace geap-system --timeout=180s
    

데이터 영역 배포

GCPAgentGateway 커스텀 리소스를 만들어 크로스 클라우드 프록시(Envoy 프록시)용 Agent Gateway를 배포합니다. 프록시는 트래픽을 검사하고 관리하는 에이전트 워크로드에 정책을 적용합니다. 각 프록시는 프록시의 워크로드 아이덴티티, 보안 비밀 검색 서비스(SDS) 인증서, 로컬 토큰 교환을 중개하는 에이전트 아이덴티티 런타임(AIR) 사이드카와 함께 실행됩니다.

에이전트 워크로드, MCP 서버 또는 기타 애플리케이션 포드가 포함되지 않은 전용 네임스페이스(예: agent-gateway-system)에 크로스 클라우드용 Agent Gateway를 배포해야 합니다. 이 전용 네임스페이스의 단일 게이트웨이는 클러스터 전반의 에이전트 워크로드에서 발생하는 아웃바운드 트래픽을 제어할 수 있습니다.

게이트웨이에 IAM 역할 부여

크로스 클라우드 프록시를 위한 Agent Gateway의 제휴 ID에 IAM 역할을 부여합니다. 바인딩은 게이트웨이 네임스페이스의 모든 KSA에 적용되므로 각 게이트웨이 네임스페이스에 다음 역할을 부여합니다.

  • Traffic Director 클라이언트(roles/trafficdirector.client)
  • App Hub 엔드포인트 뷰어(roles/apphubendpoint.viewer)
  • 에이전트 레지스트리 뷰어(roles/agentregistry.viewer)
  • 프록시가 Service Extensions 정책 콜아웃을 호출할 수 있는 Service Extensions 편집자(roles/serviceextensions.editor)

역할을 부여하려면 다음 명령어를 실행합니다.

for ROLE in \
    roles/trafficdirector.client \
    roles/apphubendpoint.viewer \
    roles/agentregistry.viewer \
    roles/serviceextensions.editor; do
  gcloud projects add-iam-policy-binding PROJECT_ID \
      --role="${ROLE}" \
      --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.namespace/GATEWAY_NAMESPACE"
done

다음을 바꿉니다.

  • PROJECT_ID: Google Cloud 프로젝트 ID입니다.
  • PROJECT_NUMBER: Google Cloud 프로젝트 번호
  • POOL_ID: 워크로드 아이덴티티 풀의 ID입니다.
  • GATEWAY_NAMESPACE: 게이트웨이의 전용 네임스페이스입니다. 이 네임스페이스에는 에이전트 워크로드가 포함되어서는 안 됩니다.

에이전트 연결 템플릿 만들기

각 게이트웨이는 등록된 클러스터를 참조하는Google Cloud 리소스인 에이전트 연결 템플릿을 참조합니다. 각 게이트웨이에 대해 별도의 템플릿을 만들 필요가 없습니다. 여러 게이트웨이를 단일 템플릿에 매핑할 수 있습니다. 동일한 클러스터에 여러 템플릿을 만들 수도 있습니다.

사용하려는 클러스터에 대한 에이전트 연결 템플릿이 이미 있는 경우 게이트웨이 만들기로 건너뜁니다.

에이전트 연결 템플릿을 만들려면 다음 단계를 따르세요.

  1. 다음 템플릿 정의를 act.yaml로 저장합니다.

    description: "Agent connectivity template for CLUSTER_NAME"
    agentCompute: K8S
    registeredCluster: "projects/PROJECT_ID/locations/LOCATION/registeredClusters/CLUSTER_NAME"
    
  2. 템플릿을 가져옵니다.

    gcloud alpha network-services agent-connectivity-templates import ACT_NAME \
        --project=PROJECT_ID \
        --location=LOCATION \
        --source=act.yaml
    

다음을 바꿉니다.

  • CLUSTER_NAME: 등록된 클러스터의 이름입니다.
  • PROJECT_ID: Google Cloud 프로젝트 ID입니다.
  • LOCATION: 클러스터를 등록한 리전입니다.
  • ACT_NAME: 에이전트 연결 템플릿의 이름입니다.

게이트웨이 만들기

게이트웨이를 만들려면 다음을 수행합니다.

  1. 게이트웨이 네임스페이스가 아직 없으면 이를 만듭니다.

    kubectl create namespace GATEWAY_NAMESPACE
    

    GATEWAY_NAMESPACE를 게이트웨이에 역할을 부여할 때 사용한 게이트웨이의 전용 네임스페이스로 바꿉니다.

  2. 다음 매니페스트를 agent-gateway.yaml로 저장합니다.

    apiVersion: networkservices.googleapis.com/v1alpha1
    kind: GCPAgentGateway
    metadata:
      name: GATEWAY_NAME
      namespace: GATEWAY_NAMESPACE
    spec:
      agentConnectivityTemplateUri: "projects/PROJECT_ID/locations/LOCATION/agentConnectivityTemplates/ACT_NAME"
    

    다음을 바꿉니다.

  3. 매니페스트를 적용합니다.

    kubectl apply -f agent-gateway.yaml
    
  4. 게이트웨이가 배포되고 준비될 때까지 기다립니다.

    kubectl wait --for=condition=Reconciled=True \
        gcpagentgateway/GATEWAY_NAME \
        -n GATEWAY_NAMESPACE \
        --timeout=300s
    

    게이트웨이가 준비되면 명령어가 gcpagentgateway.networkservices.googleapis.com/GATEWAY_NAME condition met를 반환합니다.

  5. 대규모 언어 모델(LLM), 모델 컨텍스트 프로토콜(MCP), 에이전트 간(A2A) 요청과 같은 아웃바운드 에이전트 트래픽을 게이트웨이를 통해 전달하도록 서비스 메시를 구성합니다.

기존 게이트웨이에 톨러레이션 추가

GCPAgentGateway 리소스를 만든 후 k8s.tolerations Helm 값을 추가하는 경우 컨트롤러가 새 허용 오차로 게이트웨이 배포를 다시 만들도록 다음을 수행합니다.

  1. --values tolerations-values.yaml를 사용하여 컨트롤 플레인 Helm 차트 설치에서 helm upgrade --install 명령어를 실행합니다.

  2. 기존 게이트웨이 배포를 삭제합니다.

    kubectl delete deployment GATEWAY_NAME \
        --namespace GATEWAY_NAMESPACE
    

    클러스터의 각 게이트웨이에 대해 이 단계를 반복합니다.

  3. 게이트웨이 배포를 다시 만들도록 컨트롤러를 다시 시작합니다.

    kubectl rollout restart deployment/agent-governance-cross-cloud-controller \
        --namespace geap-system
    

이 절차는 Google Cloud AgentGateway 리소스 또는 연결된 GCPExtensionBinding 리소스에 영향을 미치지 않습니다. 컨트롤러가 게이트웨이 배포를 다시 만들 때까지 게이트웨이를 통한 아웃바운드 트래픽이 중단됩니다.

Google API에 대한 아웃바운드 연결 허용

크로스 클라우드 프록시 포드의 Agent Gateway에 TCP 포트 443에서 *.googleapis.com에 대한 아웃바운드 HTTPS 및 gRPC 연결이 있는지 확인합니다.

TLS 검사 구성

크로스 클라우드용 Agent Gateway가 아웃바운드 트래픽을 검사하고 제어할 수 있도록 전송 계층 보안(TLS) 검사를 구성합니다.

TLS 검사 CA 보안 비밀 보호

크로스 클라우드용 Agent Gateway는 루트 인증 기관(CA)을 사용하여 아웃바운드 TLS 트래픽을 검사할 때 제공하는 인증서를 발급합니다. 컨트롤러는 시작할 때 이 CA를 만듭니다. 비공개 키를 포함한 CA는 컨트롤러 네임스페이스(geap-system)와 크로스 클라우드 프록시 및 AIR 사이드카용 Agent Gateway가 배포되는 게이트웨이 네임스페이스라는 두 네임스페이스의 Kubernetes Secret 리소스에 저장됩니다. 이러한 Secret 리소스를 읽을 수 있는 사용자는 에이전트 워크로드에 대한 외부 엔드포인트를 가장할 수 있습니다. CA를 보호하려면 다음 보호 조치를 적용하세요.

  • Secret에 대한 RBAC 액세스 제한: geap-system 및 게이트웨이 네임스페이스의 Secret 리소스에 대한 get, list, watch 권한을 크로스 클라우드 서비스 계정 및 전용 플랫폼 관리자를 위한 Agent Gateway로 제한합니다. list 및 watch 권한은 Secret 콘텐츠도 노출합니다.
  • 컨트롤러 및 게이트웨이 네임스페이스 격리: 네임스페이스에서 포드를 만들 수 있는 사용자는 해당 네임스페이스에 모든 Secret를 마운트할 수 있습니다. geap-system 네임스페이스 및 게이트웨이 네임스페이스에서 크로스 클라우드 구성요소의 Agent Gateway만 실행합니다. 이러한 네임스페이스에 에이전트 워크로드 또는 기타 포드를 배포하지 마세요. 이러한 네임스페이스에서 포드, 배포, 기타 워크로드 리소스를 만들거나 수정할 수 있는 권한을 신뢰할 수 있는 관리자로 제한합니다.
  • Secret 저장 데이터 암호화: 클러스터의 etcd 데이터 스토어에 있는 Secret 리소스에 대해 저장 데이터 암호화를 사용 설정합니다. 가능하면 KMS 제공업체를 사용하여 암호화 키를 관리합니다.
  • Secret에 대한 액세스 감사: Kubernetes 감사 로깅을 사용 설정하고 CA Secret에 대한 읽기 액세스를 모니터링합니다.

다음 단계