O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Implantar um agente e um gateway de agente com o VPC Service Controls

1. Introdução

Neste codelab, você vai aprender a configurar um ambiente do Google Cloud para criar um agente e um gateway de agente com perímetros do VPC Service Controls. Você estabelece um perímetro do VPC Service Controls, configura rede e DNS, implanta um gateway de agente com autorização de solicitação do Identity-Aware Proxy (IAP) e testa o agente com segurança.

O que você vai criar

Neste codelab, você vai criar uma arquitetura segura do Google Cloud para a Gemini Enterprise Agent Platform e o Gateway de Agente que faz o seguinte:

Usa o VPC Service Controls para ajudar a proteger os recursos do projeto contra exfiltração de dados não autorizada.
Configura o Acesso privado do Google, o Private Service Connect (PSC) e as zonas particulares do Cloud DNS para o roteamento de API particular.
Provisiona um gateway de agente com proxy centralizado de tráfego, regras de saída e configuração de protocolo.
Aplica políticas de autorização de solicitação do Identity-Aware Proxy (IAP).
Implanta e testa com segurança um agente do Agent Engine usando conectividade particular.

O que você vai aprender

Como ativar as APIs do Cloud necessárias do Google Cloud para a Agent Platform e segurança.
Como configurar um perímetro do VPC Service Controls e regras de acesso de entrada.
Como configurar a conectividade de rede privada e os registros de DNS particular.
Como criar um Gateway de Agente e modelos de conectividade de agente.
Como configurar extensões e políticas de autorização de solicitação do IAP.
Como implantar e testar um agente do Agent Engine com segurança.

O que é necessário

A CLI do Google Cloud instalada e atualizada para a versão mais recente.
Python 3 instalado na sua estação de trabalho.
O Git instalado na sua estação de trabalho.
Uma organização ativa do Google Cloud e permissões da conta de faturamento.

2. Pré-requisitos

Esta seção descreve os requisitos básicos de ferramentas de linha de comando e a configuração de ambiente necessária antes de executar scripts de configuração.

Verifique se a CLI do Google Cloud está instalada e atualizada para a versão mais recente. Em seguida, faça a autenticação com sua Conta do Google. Atualize os componentes da CLI do Google Cloud para garantir que você tenha o suporte mais recente para os Serviços de rede e o VPC Service Controls.

gcloud components update
gcloud auth login
gcloud config set account USER_EMAIL

Verifique se o Python 3 está instalado para configurar e implantar a estrutura de agente personalizada. Para instruções, consulte Instalar módulos do Python:

python3 --version

Verifique se o Git está instalado para clonar o repositório de exemplo que contém o código de configuração e os modelos de configuração. Para instruções, consulte Instalação do Git.

3. Configurar um projeto do Google Cloud

Criar um projeto isolado na sua organização garante que todos os recursos, redes e permissões usados neste codelab permaneçam encapsulados e gerenciáveis. Saiba mais sobre Como criar e gerenciar projetos.

Inicialize um novo projeto na nuvem do Google Cloud na sua organização para hospedar os recursos dessa configuração. Você também pode usar seu próprio projeto:

export PROJ_ID="YOUR_PROJECT_ID"
gcloud projects create ${PROJ_ID} --organization=YOUR_ORG_ID

gcloud config set project $PROJ_ID

gcloud auth application-default set-quota-project $PROJ_ID

Faça login para receber as credenciais padrão do aplicativo:

gcloud auth application-default login

Verifique a configuração:

gcloud config list

Ativar faturamento

Vincule uma conta de faturamento ativa ao projeto recém-criado para ativar o uso do serviço.

Ativar o faturamento é um pré-requisito para consumir a cota da API e provisionar a infraestrutura em nuvem do Google Cloud, como Gateways de Agente, nuvens privadas virtuais e nós de computação. Para detalhes sobre as configurações de faturamento, consulte a documentação do Google Cloud Billing.

gcloud billing accounts list
# Copy the billing account to assign to your GCP project
gcloud billing projects link $PROJ_ID --billing-account=BILLING_ACCOUNT_ID

4. Ativar o Services

Ative todas as APIs do Google Cloud necessárias para os recursos de agente, gateway do agente, rede, segurança e observabilidade.

A ativação da API expõe serviços de nuvem de back-end para gerenciamento de recursos, capacidade de observação e recursos de rede necessários para a conectividade segura do agente. Saiba mais na documentação da API Service Usage.

gcloud services enable \
  agentregistry.googleapis.com \
  aiplatform.googleapis.com \
  apphub.googleapis.com \
  apptopology.googleapis.com \
  cloudapiregistry.googleapis.com \
  cloudtrace.googleapis.com \
  compute.googleapis.com \
  dataform.googleapis.com \
  iam.googleapis.com \
  iap.googleapis.com \
  logging.googleapis.com \
  modelarmor.googleapis.com \
  monitoring.googleapis.com \
  networksecurity.googleapis.com \
  networkservices.googleapis.com \
  notebooks.googleapis.com \
  observability.googleapis.com \
  securitycenter.googleapis.com

gcloud services enable \
  saasservicemgmt.googleapis.com \
  storage.googleapis.com \
  telemetry.googleapis.com \
  texttospeech.googleapis.com \
  run.googleapis.com \
  artifactregistry.googleapis.com \
  cloudbuild.googleapis.com \
  dns.googleapis.com \
  accesscontextmanager.googleapis.com \
  discoveryengine.googleapis.com \
  agentidentity.googleapis.com \
  agentidentitycredentials.googleapis.com

5. Exportar variáveis de ambiente

Defina variáveis de ambiente reutilizáveis para região, ID do projeto, número do projeto, ID da organização e identidade do usuário. A definição de variáveis de shell padroniza os comandos de configuração de recursos em todas as etapas, minimizando erros de substituição manual durante a execução do script.

export REGION="us-central1"
export PROJ_ID=$(gcloud config list --format="value(core.project)")
export PROJ_NO=$(gcloud projects describe ${PROJ_ID} --format="value(projectNumber)")
export ORG_ID=$(gcloud projects get-ancestors ${PROJ_ID} --format="value(id)" | tail -n 1)
export USER_IDENTITY=$(gcloud config get-value account)

6. Criar um perímetro do VPC Service Controls

Crie um perímetro do VPC Service Controls para isolar os recursos do projeto e evitar a exfiltração de dados. Para mais informações, consulte a Visão geral do VPC Service Controls.

Buscar sua política de acesso

Recupere o ID da política do Access Context Manager associado à sua organização. As políticas do Access Context Manager definem o limite organizacional em que os perímetros do VPC Service Controls são anexados e aplicados.

gcloud access-context-manager policies list --organization=$ORG_ID

Exportar sua política de acesso

Defina a política de acesso na configuração do gcloud CLI e colete a lista de serviços restritos compatíveis. Ao coletar todos os serviços compatíveis, você pode criar um conjunto de regras de perímetro restrito que impede o acesso não autorizado aos endpoints da API do Google Cloud.

export ACCESS_POLICY=ACCESS_POLICY_ID

gcloud config set access_context_manager/policy $ACCESS_POLICY
SUPPORTED_SERVICES=$(gcloud access-context-manager supported-services list --format="value(name)" | paste -sd, -)

Criar um perímetro

Defina o nome do perímetro de serviço e aplique restrições em todos os serviços do Google Cloud compatíveis no projeto. O perímetro atua como um limite ao redor dos recursos do projeto, restringindo o tráfego direto de entrada e saída, a menos que seja explicitamente permitido pelas regras de entrada/saída.

export PERIMETER_NAME="perimeter_${PROJ_NO}"

gcloud access-context-manager perimeters create accessPolicies/${ACCESS_POLICY}/servicePerimeters/${PERIMETER_NAME} \
--title="${PERIMETER_NAME}" \
--perimeter-type=regular \
--resources=projects/${PROJ_NO} \
--restricted-services=${SUPPORTED_SERVICES}

Criar uma política de entrada

As políticas de entrada definem condições explícitas, como identidades de usuários ou níveis de acesso específicos, em que o tráfego se origina fora do perímetro e pode alcançar recursos restritos dentro dele.

Crie um arquivo YAML que permita o acesso explícito para sua identidade de usuário em todos os serviços:

cat > ingress-policy.yaml << EOF
- ingressFrom:
    identities:
      - user:${USER_IDENTITY}
    sources:
      - accessLevel: '*'
  ingressTo:
    operations:
      - serviceName: '*'
    resources:
      - '*'
EOF

gcloud access-context-manager perimeters update $PERIMETER_NAME --set-ingress-policies="ingress-policy.yaml"

Este codelab configura seu ambiente para evitar negações de acesso do VPC Service Controls por padrão. No entanto, para ajudar na solução de problemas durante o teste, o VPC Service Controls fornece registros detalhados de negação e ferramentas de inteligência de políticas.

Resolver problemas de negações do VPC Service Controls

Durante o teste, consulte estas dicas de solução de problemas:

Ative o painel de violações para acompanhar as violações mais recentes no seu ambiente.
Monitore os registros de auditoria do Cloud para registros de negação de acesso (403) do VPC Service Controls.
Diagnostique violações usando o ID exclusivo ou o token da violação no Analisador de violações.
Assista o vídeo sobre como resolver problemas do VPC Service Controls para conferir um tutorial detalhado.

7. Configurar redes

Configure as definições de rede VPC para oferecer suporte à comunicação particular com as APIs e os serviços do Google. A configuração adequada da rede garante que o tráfego entre agentes, gateways e APIs do Google Cloud permaneça em redes internas privadas. Para padrões de rede detalhados, consulte a documentação da VPC do Google Cloud.

ativar o Acesso privado do Google

Ative o Acesso privado do Google na sub-rede padrão para que as instâncias de VM e as cargas de trabalho internas possam acessar as APIs do Google usando endereços IP internos em vez de públicos.

export NETWORK_NAME="default"
export SUBNET_NAME="default"

gcloud compute networks subnets update $SUBNET_NAME --region=$REGION --enable-private-ip-google-access

Criar um anexo de rede do PSC

Crie um anexo de rede do Private Service Connect (PSC) para a conectividade do Gateway de Agente. Os anexos de rede fornecem interfaces do Private Service Connect (PSC), facilitando a comunicação segura entre VPCs do serviço Gateway de Agente e sua sub-rede interna.

gcloud compute network-attachments create psc-agw-${REGION} \
  --region=${REGION} \
  --subnets=${SUBNET_NAME} \
  --connection-preference=ACCEPT_AUTOMATIC

Verificar

Recupere e inspecione o URI do recurso de autovinculação do anexo de rede recém-criado. A validação do URI do recurso garante que a vinculação de rede foi instanciada e pode ser referenciada em modelos de conectividade.

export PSC_NA_URI=$(gcloud compute network-attachments describe psc-agw-${REGION} \
  --region=${REGION} \
  --format="value(selfLink.scope(v1))")
echo ${PSC_NA_URI}

Criar uma zona particular do Cloud DNS

Configure uma zona particular do Cloud DNS para rotear o tráfego de googleapis.com por intervalos de IP particulares. As zonas de DNS particular substituem as pesquisas de domínio público para googleapis.com, direcionando todo o tráfego de saída para IPs virtuais (VIPs) internos privados na sua rede VPC. Consulte Zonas particulares do Cloud DNS para mais detalhes.

export ZONE_NAME="gapis"

gcloud dns managed-zones create ${ZONE_NAME} \
--visibility=private \
--networks=https://www.googleapis.com/compute/v1/projects/${PROJ_ID}/global/networks/${NETWORK_NAME} \
  --description="Privately reach Google APIs" \
  --dns-name=googleapis.com

gcloud dns record-sets transaction start --zone=${ZONE_NAME}

Escolha uma das seguintes opções de domínio para roteamento particular (execute apenas os comandos em "Opção 1" ou "Opção 2" antes de executar a transação). Leia mais em Opções de configuração do Acesso privado do Google:

Opção 1: VIP particular [recomendado]

gcloud dns record-sets transaction add --name="*.googleapis.com." \
    --type=CNAME private.googleapis.com. \
    --zone=${ZONE_NAME} \
    --ttl=300

gcloud dns record-sets transaction add --name=private.googleapis.com. \
    --type=A 199.36.153.8 199.36.153.9 199.36.153.10 199.36.153.11 \
    --zone=${ZONE_NAME} \
    --ttl=300

Opção 2: VIP restrito

gcloud dns record-sets transaction add --name="*.googleapis.com." \
    --type=CNAME restricted.googleapis.com. \
    --zone=${ZONE_NAME} \
    --ttl=300

gcloud dns record-sets transaction add --name=restricted.googleapis.com. \
    --type=A 199.36.153.4 199.36.153.5 199.36.153.6 199.36.153.7 \
    --zone=${ZONE_NAME} \
    --ttl=300

Confirmar transações de DNS:

gcloud dns record-sets transaction execute --zone=${ZONE_NAME}

8. Criar gateway de agente

Provisione o Gateway de Agente e defina os modelos de conectividade e as regras de roteamento dele. O Gateway de Agente serve como proxy centralizado para gerenciar o tráfego de agentes, políticas de saída, processamento de protocolos e descoberta de serviços segura. Para referências de arquitetura, consulte a Visão geral do Gateway de Agente.

Diagrama de arquitetura mostrando um agente roteando solicitações pelo Gateway de Agente, autorização de solicitação do IAP e um anexo de rede do PSC dentro de um perímetro do VPC Service Controls.

export AGW_NAME="gateway-${USER_IDENTITY}"
export AGW_CONNECTIVITY_TEMPLATE="agw-connectivity-template-${USER_IDENTITY}"

Criar modelo de conectividade do agente

Os modelos de conectividade especificam a configuração de rede, as políticas de roteamento de saída, as configurações de peering de DNS e os URIs de anexo de rede necessários para que o gateway processe solicitações de saída.

cat > ${AGW_CONNECTIVITY_TEMPLATE}.yaml << EOF
name: projects/${PROJ_NO}/locations/${REGION}/agentConnectivityTemplates/${AGW_CONNECTIVITY_TEMPLATE}
accessPath: AGENT_TO_ANYWHERE
deploymentModel: CENTRALIZED
egressNetworkConfig:
  networkAttachment: ${PSC_NA_URI}
  dnsPeeringConfig:
    domain: googleapis.com.
    targetNetwork: projects/${PROJ_ID}/global/networks/${NETWORK_NAME}
  vpcEgress: ALL_TRAFFIC
EOF

gcloud network-services agent-connectivity-templates import ${AGW_CONNECTIVITY_TEMPLATE} \
    --source="${AGW_CONNECTIVITY_TEMPLATE}.yaml" \
    --location=${REGION}

Criar gateway de agente

cat > ${AGW_NAME}-config.yaml << EOF
name: ${AGW_NAME}
protocols:
  - MCP
googleManaged:
  governedAccessPath: AGENT_TO_ANYWHERE
agentConnectivityTemplate: projects/${PROJ_NO}/locations/${REGION}/agentConnectivityTemplates/${AGW_CONNECTIVITY_TEMPLATE}
registries:
  - //agentregistry.googleapis.com/projects/${PROJ_NO}/locations/global
EOF

gcloud network-services agent-gateways import ${AGW_NAME} \
    --source="${AGW_NAME}-config.yaml" \
    --location=${REGION}

Verificar a criação

Confirme se o recurso do Gateway de Agente foi implantado e configurado com sucesso. Descrever o gateway do agente implantado confirma que o estado operacional dele está ativo e verifica se os modelos e registros de conectividade associados estão anexados corretamente.

gcloud network-services agent-gateways describe ${AGW_NAME} \
  --location=${REGION}

9. Criar autorização usando o IAP

Configure políticas de autorização de solicitação e Service Extensions do Identity-Aware Proxy (IAP) para verificar as credenciais de solicitação antes de conceder acesso ao Gateway de Agente. Para mais informações, consulte a documentação do IAP.

Diagrama de fluxo mostrando como o Gateway de Agente delega a autorização de solicitação ao Identity-Aware Proxy (IAP) usando uma política de autorização de segurança de rede e uma extensão de serviço de autorização.

export AUTHZ_EXT="iap-authz-extension-${USER_IDENTITY}"
export AUTHZ_POLICY="iap-authz-policy-${USER_IDENTITY}"

Criar extensão de autorização

cat > ${AUTHZ_EXT}.yaml << EOF
name: ${AUTHZ_EXT}
service: iap.googleapis.com
failOpen: false
timeout: 1s
metadata:
  iapPolicyVersion: "V2"
EOF

gcloud service-extensions authz-extensions import ${AUTHZ_EXT} \
    --source=${AUTHZ_EXT}.yaml \
    --location=${REGION}

Criar e vincular uma política de autorização ao Gateway de Agente

cat > ${AUTHZ_POLICY}.yaml << EOF
name: ${AUTHZ_POLICY}
target:
  resources:
    - "projects/${PROJ_ID}/locations/${REGION}/agentGateways/${AGW_NAME}"
policyProfile: REQUEST_AUTHZ
action: CUSTOM
customProvider:
  authzExtension:
    resources:
      - "projects/${PROJ_ID}/locations/${REGION}/authzExtensions/${AUTHZ_EXT}"
EOF

gcloud network-security authz-policies import ${AUTHZ_POLICY} \
    --source=${AUTHZ_POLICY}.yaml \
    --location=${REGION}

Este codelab garante que você não terá nenhuma negação de acesso ao IAP por padrão. No entanto, para ajudar nos testes, o Gateway de Agente oferece observabilidade detalhada para negações de acesso.

Resolver problemas e monitorar negações de autorização do IAP

Ative a Análise de dados de registros no bucket de registros padrão:

gcloud logging buckets update _Default --location=global --enable-analytics --async

Abra o painel de observabilidade do Gateway de Agente:
No console do Google Cloud, acesse a página Gateway de agente.
Clique no nome do gateway (por exemplo, gateway-xyz).
Clique na guia Observabilidade.
Analise os painéis "Falha de autorização" e "Negações 403".

10. Criar agente do Agent Engine

Criar bucket de staging

Crie um bucket do Cloud Storage na região de destino para armazenar artefatos de preparo temporários, dependências e configurações de implantação durante a inicialização do tempo de execução.

#Staging bucket name needs to be globally unique
export STAGING_BUCKET="agent-temp-bucket-${PROJ_NO}-${USER_IDENTITY}"
gcloud storage buckets create gs://${STAGING_BUCKET} --location=${REGION}

Ativar o ambiente virtual do Python

python3 -m venv .venv
source .venv/bin/activate

Baixar o código do agente

git clone https://github.com/gpratikab/gcp-vpcsc-agent.git
cd gcp-vpcsc-agent

Instalar dependências

python3 -m pip install --upgrade -r requirements.txt

Conceder papéis do IAM ao agente de serviço da Agent Platform

gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="serviceAccount:service-${PROJ_NO}@gcp-sa-aiplatform.iam.gserviceaccount.com" \
  --role="roles/agentgateway.serviceAgent"
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="serviceAccount:service-${PROJ_NO}@gcp-sa-aiplatform.iam.gserviceaccount.com" \
  --role="roles/ml.serviceAgent"
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="serviceAccount:service-${PROJ_NO}@gcp-sa-aiplatform.iam.gserviceaccount.com" \
  --role="roles/networkservices.viewer"

Implantar o agente

python3 deploy_gcp_agent.py create

Exporte a identidade do agente impressa na saída do comando anterior como uma variável de ambiente:

#Paste identity of your Agent, it will be printed as the output of the previous command
export AGENT_IDENTITY="principal://PRINCIPAL_ID"
echo $AGENT_IDENTITY

11. Permitir saída do agente pelo gateway

Permita que o agente recém-criado envie tráfego de saída para googleapis.com.

Observação:é possível adicionar endpoints à lista de permissões de forma seletiva usando a observabilidade do Gateway de Agente. Para simplificar, este codelab permite o acesso a todas as APIs.

A configuração de regras explícitas de política de saída do IAM concede ao agente permissão para rotear chamadas de API pelo Gateway de Agente e pelo proxy do IAP para acessar serviços externos do Google Cloud.

Criar política de IAM

cat > agent-access-rules.json << EOF
{
  "conditions": {
    "iap.googleapis.com": {
      "description": "Allow access to agent",
      "expression": "(destination.agent_registry.location == 'global') || (destination.unregistered.host.endsWith('googleapis.com'))",
      "title": "agenttogapis"
    }
  },
  "description": "agenttogapis",
  "effect": "ALLOW",
  "excludedPrincipals": [],
  "operation": {
    "excludedPermissions": [],
    "permissions": [
      "iap.googleapis.com/resources.egressViaIAP"
    ]
  },
  "principals": [
    "${AGENT_IDENTITY}"
  ]
}
EOF

Atualizar política de acesso

Verifique se você tem uma política de acesso:

gcloud iam access-policies list --project=${PROJ_ID} --location=global

Defina o nome da política de acesso:

export IAM_ACCESS_POLICY="agent-access-policy"

Para criar uma nova política:

gcloud iam access-policies create ${IAM_ACCESS_POLICY} \
  --details-rules=agent-access-rules.json \
  --project=${PROJ_ID} \
  --location=global

Ou, como alternativa, atualize uma política existente:

gcloud iam access-policies update ${IAM_ACCESS_POLICY} \
  --add-details-rules=agent-access-rules.json \
  --project=${PROJ_ID} \
  --location=global

12. Testar o agente

A validação da operação do agente no console do Google Cloud verifica se a comunicação de ponta a ponta, as políticas do IAM e os limites do VPC Service Controls estão funcionando corretamente. Agora você pode testar o agente:

No console do Google Cloud, acesse a página Implantações de agentes.
Selecione o agente implantado (gcp_agent_...).
Abra a guia Playground.
No campo de comando, insira: List storage buckets in the current project.
Verifique se o agente retorna a lista de buckets pelo Gateway de Agente particular.
Verifique se o agente não consegue recuperar buckets de outro projeto devido a uma negação de acesso. É possível inspecionar a negação nos registros de auditoria do Cloud ou no painel de violações do VPC Service Controls.

13. Limpar

Para evitar cobranças na sua conta do Google Cloud pelos recursos usados neste codelab, exclua o projeto criado:

gcloud projects delete ${PROJ_ID}

14. Parabéns

Parabéns! Você configurou um agente e um gateway de agente em um perímetro seguro do VPC Service Controls no Google Cloud.

Qual é a próxima etapa?

Confira regras granulares de entrada e saída no VPC Service Controls.
Configure políticas de acesso e semânticas usando o Gateway de Agente.
Integre o Model Armor para filtragem avançada de segurança.