Configurar o gateway de agente com conectividade VPC

Este documento orienta você no processo de configuração da conectividade de VPC ao implantar um Gateway de Agente para que ele possa se comunicar de forma particular com uma rede VPC na sua organização.

Ao configurar a conectividade de VPC, é possível:

  • Aplicar a saída de VPC para o tráfego: roteie o tráfego originado dos seus agentes pelo anexo de rede do Private Service Connect para sua rede VPC usando o modo PRIVATE_RANGES_ONLY ou ALL_TRAFFIC.
  • Intervalo de endereços IP de origem estático: o tráfego de saída usa o intervalo de endereços IP particulares da sub-rede de anexo de rede do Private Service Connect como o endereço IP de origem. Esse intervalo de IP de origem estático permite configurar políticas de firewall para que sua rede VPC controle o tráfego proveniente do gateway.
  • Resolução de DNS personalizada: resolva nomes de domínio privados internos e nomes de domínio externos diretamente dos seus agentes usando o peering de DNS do Cloud DNS.
  • Segurança de perímetro: proteja as comunicações do agente usando os perímetros de serviço do VPC Service Controls.
  • Validação de certificado particular ou autoassinado: conecte-se a destinos que usam ACs particulares ou certificados autoassinados.

Para configurar a conectividade de VPC, crie um modelo de conectividade do Gateway de Agente (AgentConnectivityTemplate) em que você define e gerencia as configurações de rede de saída para as instâncias do Gateway de Agente.

Como funciona a conectividade VPC

Quando você implanta um Gateway de Agente com um modelo de conectividade, o gateway usa uma interface do Private Service Connect para encaminhar o tráfego de saída do agente para a rede VPC designada.

Modos de saída de VPC

Configure como o gateway roteia o tráfego pelo anexo de rede usando a configuração vpcEgress no modelo de conectividade.

  • Tráfego para intervalos de endereços IP privados (PRIVATE_RANGES_ONLY): encaminha o tráfego destinado apenas a intervalos de endereços IP privados para sua rede VPC. O tráfego de saída será roteado para sua rede VPC somente se o endereço IP de destino estiver em um dos seguintes intervalos:

    • RFC 1918: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16
    • RFC 6598: 100.64.0.0/10
    • Classe E: 240.0.0.0/4
    • private.googleapis.com: 199.36.153.8/30
    • restricted.googleapis.com: 199.36.153.4/30
    • Endpoints do PSC para APIs do Google: se você implantar um endpoint personalizado do Private Service Connect para APIs do Google usando um endereço IP interno privado na sua rede VPC, o tráfego para esse endpoint será roteado pela sua rede VPC. Verifique se o peering de DNS do Cloud DNS está configurado no modelo de conectividade para que o Gateway de Agente resolva corretamente os domínios da API do Google para o endereço IP do endpoint interno do PSC.

    As solicitações para APIs públicas padrão do Google são processadas automaticamente usando o Acesso Privado do Google, e o tráfego destinado à Internet é roteado diretamente pelo Gateway de Agente, em vez de passar pela rede VPC.

  • Tráfego para todos os intervalos de endereços IP (ALL_TRAFFIC): encaminha todo o tráfego de saída originado dos agentes pela rede VPC, incluindo Internet pública, APIs SaaS externas e endereços que não são RFC 1918.

    • Roteamento e segurança: como essa configuração roteia todo o tráfego de saída para sua VPC, você é responsável por gerenciar o roteamento e a segurança dela. Verifique se a rede VPC tem uma rota padrão (0.0.0.0/0) para encaminhar esse tráfego aos gateways de saída ou dispositivos de segurança (como firewalls de próximo salto ou interfaces do Cloud Interconnect).
    • Saída de dados para a Internet pública: o Gateway de Agente envia tráfego de saída para sua rede VPC, de onde ele sai para a Internet pública por um gateway do Cloud NAT na sub-rede de anexo de rede do Private Service Connect. Se você atribuir endereços IP externo estáticos ao gateway do Cloud NAT, os serviços remotos poderão colocar na lista de permissões o tráfego de saída dos agentes com base nesses endereços IP de origem.
    • VPC Service Controls: o modo de saída precisa ser definido como ALL_TRAFFIC para oferecer suporte aos perímetros de serviço do VPC Service Controls.

Resolução de DNS e roteamento de tráfego

Por padrão, o Gateway de Agente resolve nomes de domínio usando DNS recursivo público. Se os agentes precisarem acessar cargas de trabalho internas, ferramentas particulares ou APIs do Google hospedadas em nomes de domínio particulares na rede VPC (como endpoints corp.internal. ou PSC), configure o peering de DNS do Cloud DNS para encaminhar consultas DNS para as zonas gerenciadas particulares do Cloud DNS da rede.

A tabela a seguir resume os requisitos de peering de DNS do Cloud DNS e o comportamento de roteamento de tráfego para diferentes destinos quando a conectividade VPC é configurada no modo ALL_TRAFFIC:

Tabela: resolução de DNS e roteamento de tráfego no modo ALL_TRAFFIC
Destino do tráfego O peering do Cloud DNS é obrigatório? Resolução DNS Caminho de saída
Serviços de IP privado
(RFC 1918 / interno)
Sim (por exemplo, corp.internal.) É resolvido usando o peering do Cloud DNS com a zona gerenciada do Cloud DNS particular da rede VPC de destino. O tráfego entra na rede VPC pelo anexo de rede para se conectar às cargas de trabalho internas.
Nomes de host públicos com IPs particulares
(DNS split horizon)
Não Resolve usando o DNS recursivo público padrão no proxy do gateway sem exigir o peering do Cloud DNS. O tráfego entra na rede VPC pelo anexo de rede para se conectar às cargas de trabalho internas.
Internet pública e APIs SaaS
(domínios externos)
Não Resolve usando o DNS recursivo público padrão no proxy do gateway sem exigir o peering do Cloud DNS. O tráfego entra na rede VPC pelo anexo de rede e sai para a Internet pública usando o Cloud NAT configurado na sub-rede.
APIs doGoogle Cloud
(padrão, sem VPC Service Controls)
Não Resolve usando o DNS recursivo público padrão no proxy do gateway sem exigir o peering do Cloud DNS. O tráfego entra na rede VPC pelo anexo de rede e é roteado de forma particular usando o Acesso Privado do Google ativado na sub-rede, sem usar o Cloud NAT ou o peering de DNS.
APIs doGoogle Cloud
(com o VPC Service Controls)
Sim (para googleapis.com.) É resolvido para o intervalo restrito de APIs do Google (199.36.153.4/30) ou endpoints internos do Private Service Connect usando uma zona Cloud DNS privada. O tráfego entra na rede VPC pelo anexo de rede para aplicar as regras de segurança do perímetro do VPC Service Controls1.

1 Se as solicitações falharem com violações do VPC Service Controls, como NETWORK_NOT_IN_SAME_SERVICE_PERIMETER ou SECURITY_POLICY_VIOLATED em compute.googleapis.com ou dns.googleapis.com que fazem referência ao projeto host, verifique se o projeto host está no mesmo perímetro que o projeto de gateway.

Requisitos para certificados TLS

Ao rotear o tráfego de saída por HTTPS, o Gateway de Agente valida a cadeia de certificados TLS do servidor de destino durante o handshake de TLS. Os requisitos de certificado para conexões HTTPS dependem de os endpoints de destino usarem autoridades certificadoras (CAs) publicamente confiáveis ou CAs privadas/autoassinadas.

  • Autoridades certificadoras públicas: por padrão, o Gateway de Agente confia em certificados emitidos por autoridades certificadoras (CAs) publicamente confiáveis que atendem aos requisitos padrão de certificado de servidor (incluindo um nome alternativo do sujeito (SAN) que corresponde ao nome do host de destino).

  • CAs privadas e certificados autoassinados: se o destino (agentes, ferramentas ou servidores MCP na sua rede VPC) usar uma CA privada ou uma PKI interna, será possível configurar âncoras de confiança personalizadas usando a configuração tlsConfig no modelo de conectividade.

    Ao referenciar um recurso TrustConfig do Certificate Manager, é possível configurar o Gateway de Agente para confiar apenas em ACs particulares específicas ou combinar ACs raiz particulares com ACs publicamente confiáveis (PUBLICLY_TRUSTED_ROOTS). Isso estabelece confiança para endpoints públicos e particulares.

    Se os agentes se conectarem a APIs do Google Cloud (*.googleapis.com) ou a outros endpoints HTTPS públicos, defina additionalRoots como PUBLICLY_TRUSTED_ROOTS. Sem essa configuração, o Gateway de Agente não confia em certificados assinados pelo Google para googleapis.com.

    Observe as seguintes limitações ao usar tlsConfig:

    • Ao usar trustConfigs para rotear o tráfego para destinos que usam CAs particulares, é necessário alternar os arquivos PEM manualmente. A rotação automatizada de arquivos PEM usando gerenciadores de secrets, como o Secret Manager do Google Cloud, não é compatível.
    • O campo trustConfig é imutável depois de configurado em um modelo de conectividade, e o Gateway de Agente não detecta automaticamente as alterações feitas em tlsConfig (como atualizar additionalRoots) em um modelo de conectividade anexado. Para instruções sobre como atualizar as configurações de TLS, consulte Como atualizar as configurações de saída da VPC.

Se o Gateway de Agente não conseguir validar a cadeia de certificados, a conexão vai falhar.

Papéis e permissões necessárias

Para configurar a conectividade VPC para o Gateway de Agente, verifique se a identidade usada para provisionamento e o agente de serviço do gateway têm os papéis necessários.

Implantações de projetos independentes

Em um projeto independente em que o gateway, o anexo de rede e a rede VPC residem no mesmo projeto, as permissões padrão do Gateway de Agente se aplicam. Para mais detalhes, consulte Permissões necessárias.

Se você configurar um anexo de rede, a identidade que cria ou atualiza o modelo de conectividade do gateway ou do agente (sua conta de usuário ou conta de serviço de implantação) também precisará ter a permissão compute.networkAttachments.use no anexo de rede, por exemplo, pelo papel de Administrador de rede do Compute (roles/compute.networkAdmin) no projeto que contém o anexo de rede. O papel de Usuário de rede do Compute não é suficiente. Sem essa permissão, a solicitação falha com um erro PERMISSION_DENIED que nomeia o anexo de rede.

Além disso, se você configurar o peering de DNS, o Gateway de Agente vai validar a configuração de peering de DNS (e qualquer anexo de rede e a sub-rede dele) usando o agente de serviço do Gateway de Agente (service-AGENT_GATEWAY_PROJECT_NUMBER@gcp-sa-agentgateway.iam.gserviceaccount.com). Conceda ao agente de serviço os seguintes papéis no projeto que contém a rede VPC de destino, o anexo de rede e as zonas de DNS particulares (seu próprio projeto em uma implantação independente):

  • Leitor da rede do Compute (roles/compute.networkViewer)
  • Leitor do DNS (roles/dns.reader)

Esses papéis não são concedidos automaticamente. Os anexos de rede sozinhos, sem peering de DNS, não exigem isso.

Sem esses papéis, a criação ou atualização de um modelo de conectividade de gateway ou agente que configura o peering de DNS falha na validação com um erro INVALID_ARGUMENT que nomeia o agente de serviço e o papel ausente.

VPC compartilhada ou implantações entre projetos

Em uma implantação de VPC compartilhada, é possível provisionar o Gateway de Agente em um projeto de serviço ou no projeto host. Se você provisionar o gateway no projeto host (onde a rede VPC compartilhada, a sub-rede e o anexo de rede também residem), as permissões de projeto independente serão aplicadas.

Se você provisionar o Gateway de Agente em um projeto de serviço enquanto a rede VPC de destino, o anexo de rede ou as zonas de DNS particulares estiverem no projeto host (TARGET_VPC_PROJECT_ID), as identidades no projeto de serviço não terão permissões automáticas para validar, anexar ou fazer peering com recursos de rede e DNS no projeto host. Conceda os seguintes papéis no projeto host, além das permissões padrão do Gateway de Agente:

Tabela: permissões necessárias para VPC compartilhada e implantações entre projetos
Principal ou identidade Conceder no projeto Papel do IAM obrigatório Finalidade
Identidade de provisionamento1
(conta de usuário ou conta de serviço de implantação)
Projeto host (TARGET_VPC_PROJECT_ID)
  • Leitor da rede do Compute (roles/compute.networkViewer)
  • Leitor do DNS (roles/dns.reader)
  • Administrador de endpoint regional da Conectividade de rede (roles/networkconnectivity.regionalEndpointAdmin)
  • Administrador de rede do consumidor do Network Connectivity (roles/networkconnectivity.consumerNetworkAdmin)
  • Administrador de rede do Compute (roles/compute.networkAdmin) no projeto que contém o anexo de rede, para a permissão compute.networkAttachments.use
Permite que a identidade de provisionamento visualize a rede do projeto host e os recursos de DNS particulares, por exemplo, no console do Google Cloud , gerencie o endpoint regional e use o anexo de rede. O agente de serviço do Gateway de Agente, não a identidade de provisionamento, valida a rede VPC de destino, as sub-redes, o anexo de rede e as zonas de DNS particulares durante a criação ou atualização do gateway.
Criador de anexos de rede
(administrador que cria o anexo do PSC)
Projeto host (TARGET_VPC_PROJECT_ID)
  • Usuário da rede do Compute (roles/compute.networkUser)
Permite usar uma sub-rede de VPC compartilhada no projeto host para criar um anexo de rede do Private Service Connect.
Anexo de rede no projeto de serviço (recomendado)
Agente de serviço do Gateway de Agente2 Projeto host (TARGET_VPC_PROJECT_ID)
  • Usuário da rede do Compute (roles/compute.networkUser)
  • Leitor da rede do Compute (roles/compute.networkViewer)
  • Leitor do DNS (roles/dns.reader)
  • Par de DNS (roles/dns.peer)
Permite que o agente de serviço do Gateway de Agente use a sub-rede do projeto host para o anexo de rede, conecte a interface do Private Service Connect para rotear o tráfego de saída e faça peering com zonas privadas do Cloud DNS no projeto host. Além disso, permite que o agente de serviço valide a rede VPC de destino, as sub-redes e as zonas de DNS privadas durante a criação ou atualização do gateway.
Agente de serviço do Gateway de Agente2 Projeto de serviço (AGENT_GATEWAY_PROJECT_ID)
  • Leitor da rede do Compute (roles/compute.networkViewer)
Permite que o agente de serviço leia o anexo de rede, que reside no projeto de serviço, ao validar uma configuração de peering de DNS durante a criação ou atualização do gateway. O papel padrão do agente de serviço não inclui compute.networkAttachments.get.
Anexo de rede no projeto host
Agente de serviço do Gateway de Agente2 Projeto host (TARGET_VPC_PROJECT_ID)
  • Administrador de rede do Compute (roles/compute.networkAdmin) ou uma função personalizada com:
    • compute.networkAttachments.get
    • compute.networkAttachments.update
    • compute.regionOperations.get
  • Leitor da rede do Compute (roles/compute.networkViewer)
  • Leitor do DNS (roles/dns.reader)
  • Par de DNS (roles/dns.peer)
Permite que o agente de serviço do Gateway de Agente atualize o anexo de rede do projeto host para permitir a conexão do projeto de locatário do Gateway de Agente, rotear o tráfego de saída e fazer peering com zonas de DNS privadas do Cloud no projeto host. Além disso, permite que o agente de serviço valide a rede VPC de destino, as sub-redes, o anexo de rede e as zonas de DNS privadas durante a criação ou atualização do gateway.

1 Para a identidade de provisionamento, papéis básicos para envolvidos no projeto, como Leitor (roles/viewer) ou Editor (roles/editor) no projeto host, também são suficientes.

2 O agente de serviço do Gateway de Agente é formatado como: service-AGENT_GATEWAY_PROJECT_NUMBER@gcp-sa-agentgateway.iam.gserviceaccount.com, em que AGENT_GATEWAY_PROJECT_NUMBER é o número do projeto em que você provisiona o Gateway de Agente. Para implantações de VPC compartilhada, esse projeto pode ser um projeto de serviço ou o projeto host.

Se você conectar vários projetos de serviço do Agent Runtime a um projeto host do Gateway de Agente, também será necessário conceder acesso entre projetos no projeto do gateway a cada agente de serviço do Agent Runtime. Para implantações em grande escala, consulte Escalonar projetos de serviço do Agent Runtime com um grupo do Google.

Configurar a conectividade VPC

Para implantar um Gateway de Agente com um modelo de conectividade, siga as etapas nas seções a seguir.

Criar um anexo de rede do Private Service Connect

Crie um anexo de rede do Private Service Connect na rede VPC de destino.

Verifique se o anexo de rede atende aos seguintes requisitos:

  • Preferência de conexão: configure o anexo de rede para aceitar conexões automaticamente (--connection-preference=ACCEPT_AUTOMATIC).
  • Requisito da mesma rede VPC: a sub-rede do anexo de rede e a rede de destino configuradas para peering de DNS (targetNetwork) precisam estar exatamente na mesma rede VPC. Se a sub-rede do anexo de rede pertencer a uma rede diferente da rede de destino do peering de DNS, a validação da configuração vai falhar.
  • Suporte à MTU da rede VPC: o Gateway de Agente oferece suporte a uma unidade de transmissão máxima (MTU) de até 1.500 bytes para a rede VPC que contém a sub-rede do anexo de rede. Se essa rede VPC usar uma MTU maior, como frames jumbo, entre em contato com o Cloud Customer Care para alinhar o serviço de produtor do Gateway de Agente com sua MTU de VPC personalizada.
  • Requisitos de sub-rede: observe os seguintes requisitos para a sub-rede de anexo de rede:
    • Intervalo de sub-rede: a sub-rede do anexo de rede é compatível com todos os intervalos válidos.
    • Tamanho da sub-rede: o Gateway de Agente requer uma sub-rede /28 mínima para o anexo de rede. Uma sub-rede /28 fornece 12 endereços IP utilizáveis, o que é suficiente para uma única instância do Gateway de Agente. Se você planeja conectar vários gateways ao mesmo anexo de rede ou sub-rede, use uma sub-rede maior (como /26 ou /24) para evitar o esgotamento de endereços IP.
    • Requisito de acesso privado do Google: é preciso ativar o Acesso privado do Google (private_ip_google_access = true) na sub-rede que hospeda o anexo de rede.
  • Implantações de VPC compartilhada: consulte Topologias de implantação de VPC compartilhada.

Anote o URI de recurso completo do anexo de rede (por exemplo, projects/NETWORK_ATTACHMENT_PROJECT_NUMBER/regions/NETWORK_ATTACHMENT_REGION/networkAttachments/NETWORK_ATTACHMENT_NAME). Você vai precisar dele ao criar o recurso de modelo de conectividade em uma etapa posterior.

Opcional: configurar o peering de DNS

O peering de DNS permite que o Gateway de Agente resolva nomes DNS usando registros de uma zona gerenciada particular do Cloud DNS na sua rede VPC. O peering de DNS só é necessário quando os agentes precisam resolver nomes de domínio internos privados (como corp.internal.) ou aplicar o VPC Service Controls para APIs do Google (googleapis.com.). Ele não é necessário para domínios públicos da Internet ou APIs padrão do Google sem o VPC Service Controls.

O Gateway de Agente aceita peering de DNS transitivo apenas até um único salto transitivo, o que significa um máximo de três redes VPC. Por exemplo, vpc-net-a (a rede de locatário do Gateway de Agente) pode fazer peering com vpc-net-b (rede anexada), que, por sua vez, faz peering com vpc-net-c (rede remota) para resolver consultas DNS em toda a cadeia.

Para configurar o peering de DNS, siga estas etapas:

  1. Configure sua zona de DNS particular na rede VPC de destino. Para adicionar registros DNS à sua zona de DNS particular, consulte Adicionar um conjunto de registros de recursos.

  2. Reúna as seguintes informações para configurar o modelo de conectividade e ativar o peering:

    • URI da rede de destino (targetNetwork): observe o URI de recurso completo da rede VPC de destino no seguinte formato: projects/TARGET_VPC_PROJECT_ID/global/networks/TARGET_VPC_NETWORK_NAME. A rede de destino é sempre a rede VPC que contém a sub-rede referenciada pelo anexo de rede. Se a rede de destino for uma rede VPC compartilhada, use o ID do projeto host da VPC compartilhada correspondente.

    • Nomes de domínio: um ou mais sufixos de domínio para peering de DNS. Cada domínio precisa terminar com um ponto final (.) (por exemplo, corp.internal. ou googleapis.com.).

      Para mais orientações sobre como configurar o campo domains, consulte Padrões de domínio de peering de DNS. Para implantações entre projetos, como VPC compartilhada, consulte Requisitos de zona de DNS e peering entre projetos.

Opcional: definir a configuração de confiança de TLS

Se o destino usar uma CA particular ou um certificado autoassinado, será necessário criar um recurso TrustConfig no Certificate Manager. O recurso TrustConfig define as âncoras de confiança e os certificados que o Gateway de Agente usa para validar conexões TLS.

  1. Prepare os arquivos de certificado no formato PEM:

    • Repositório de confiança: certificados de CA raiz ou intermediários no formato PEM. O Gateway de Agente confia em qualquer certificado de servidor cuja cadeia de confiança leve a um desses certificados de CA. O repositório de confiança precisa conter pelo menos um certificado de CA raiz ou intermediário.
    • Certificados na lista de permissões (opcional): certificados de servidor no formato PEM em que você quer confiar explicitamente, como um certificado autoassinado.
  2. Execute o comando a seguir para criar o recurso TrustConfig. O TrustConfig precisa ser criado no mesmo projeto e região que o Gateway de Agente e o modelo de conectividade.

    gcloud certificate-manager trust-configs create TRUST_CONFIG_NAME \
        --location=LOCATION \
        --trust-store="trust-anchors=ROOT_CERT_FILE" \
        --allowlisted-certificates=ALLOWLISTED_CERT_FILE
    

    Substitua:

    • TRUST_CONFIG_NAME: um nome para o recurso TrustConfig.
    • LOCATION: a região da configuração de confiança (por exemplo, europe-west1). Ela precisa ser a mesma região do Gateway de Agente e do modelo de conectividade.
    • ROOT_CERT_FILE: o caminho para o certificado de CA raiz ou intermediário codificado em PEM.
    • ALLOWLISTED_CERT_FILE: (opcional) o caminho para um certificado codificado em PEM em que você quer confiar explicitamente. Se você não estiver usando certificados da lista de permissões, omita essa flag.

    Para mais informações sobre como gerenciar configurações de confiança, consulte Criar e gerenciar configurações de confiança.

Implantar o Gateway de Agente

  1. Crie o arquivo de configuração do modelo de conectividade:

    Crie um arquivo YAML chamado agw-connectivity-template.yaml:

    name: projects/AGENT_GATEWAY_PROJECT_NUMBER/locations/LOCATION/agentConnectivityTemplates/CONNECTIVITY_TEMPLATE_NAME
    accessPath: AGENT_TO_ANYWHERE
    deploymentModel: CENTRALIZED
    egressNetworkConfig:
      networkAttachment: projects/NETWORK_ATTACHMENT_PROJECT_NUMBER/regions/NETWORK_ATTACHMENT_REGION/networkAttachments/NETWORK_ATTACHMENT_NAME
      dnsPeeringConfig:
        domains:
          - DOMAIN_NAME
        targetNetwork: projects/TARGET_VPC_PROJECT_ID/global/networks/TARGET_VPC_NETWORK_NAME
      vpcEgress: VPC_EGRESS_MODE
      tlsConfig:
        trustConfig: projects/AGENT_GATEWAY_PROJECT_NUMBER/locations/LOCATION/trustConfigs/TRUST_CONFIG_NAME
        additionalRoots: ADDITIONAL_ROOTS_OPTION
    

    Substitua:

    • AGENT_GATEWAY_PROJECT_NUMBER: o número do projeto do Google Cloud em que você provisiona o Gateway de Agente. Para recuperar o número do projeto, execute: gcloud projects describe PROJECT_ID --format="value(projectNumber)".

    • LOCATION: a região do modelo de conectividade (por exemplo, europe-west1).

    • CONNECTIVITY_TEMPLATE_NAME: o nome do recurso do modelo de conectividade.

    • accessPath: o caminho de acesso controlado do modelo de conectividade. Defina como AGENT_TO_ANYWHERE (os modelos de conectividade são compatíveis apenas com gateways de saída).

    • deploymentModel: o modelo de implantação do gateway. Defina como CENTRALIZED.

    • networkAttachment: o URI completo do recurso do anexo de rede do Private Service Connect:

      • NETWORK_ATTACHMENT_PROJECT_NUMBER: o número do projeto em que você criou o anexo de rede. Esse projeto pode ser o mesmo do Gateway de Agente ou um projeto diferente se você provisionar o Gateway de Agente em um projeto de serviço de VPC compartilhada e criar o anexo de rede no projeto host da VPC compartilhada.
      • NETWORK_ATTACHMENT_REGION: a região que contém o anexo de rede.
      • NETWORK_ATTACHMENT_NAME: o nome do anexo de rede.
    • DOMAIN_NAME: (opcional) um ou mais sufixos de domínio para peering de DNS (por exemplo, corp.internal., googleapis.com. ou .). Adicione um item de lista em domains para cada sufixo de domínio que você quer parear. Cada valor precisa terminar com um ponto final (.) e ter uma zona gerenciada do Cloud DNS particular correspondente autorizada para a rede de destino.

      Para mais orientações sobre como configurar o campo domains, consulte Padrões de domínio de peering de DNS.

    • targetNetwork: (opcional) o URI de recurso completo da rede VPC de destino para peering de DNS. A rede de destino é sempre a rede VPC que contém a sub-rede referenciada pelo anexo de rede:

      • TARGET_VPC_PROJECT_ID: o ID do projeto que é proprietário da rede VPC de destino. Se a rede que contém a sub-rede referenciada pelo anexo de rede for uma rede VPC compartilhada, TARGET_VPC_PROJECT_ID será o ID do projeto host da VPC compartilhada. Sempre especifique targetNetwork usando o ID do projeto, não o número do projeto.
      • TARGET_VPC_NETWORK_NAME: o nome da rede VPC de destino.
    • VPC_EGRESS_MODE: defina o modo de roteamento de saída. Defina como PRIVATE_RANGES_ONLY ou ALL_TRAFFIC.

    • tlsConfig: (opcional) a configuração de TLS para validação de certificado do servidor ao se conectar a endpoints particulares por HTTPS:

      • TRUST_CONFIG_NAME: o nome do recurso TrustConfig do Certificate Manager que contém seus certificados de CA particulares ou âncoras de confiança.
      • ADDITIONAL_ROOTS_OPTION: especifica se as raízes de CA publicamente confiáveis devem ser consideradas confiáveis, além da configuração de confiança personalizada:
      • Defina como PUBLICLY_TRUSTED_ROOTS (padrão) para confiar nos certificados validados pelo parâmetro trustConfig e em todas as CAs publicamente confiáveis. Defina additionalRoots como PUBLICLY_TRUSTED_ROOTS se os agentes também se conectarem a APIs doGoogle Cloud (*.googleapis.com) ou outros endpoints HTTPS públicos. Sem essa configuração, o Gateway de Agente não vai confiar em certificados assinados pelo Google para googleapis.com.
      • Defina como NO_ADDITIONAL_ROOTS para confiar apenas nos certificados validados pelo parâmetro trustConfig.
  2. Crie o modelo de conectividade:

    Execute o comando a seguir para criar o modelo de conectividade:

    gcloud network-services agent-connectivity-templates import CONNECTIVITY_TEMPLATE_NAME \
        --source="agw-connectivity-template.yaml" \
        --location=LOCATION
    

    Substitua:

    • CONNECTIVITY_TEMPLATE_NAME: o nome do recurso do modelo de conectividade.
    • LOCATION: o local em que você quer criar o recurso de modelo de conectividade. Por exemplo, europe-west1.
  3. Defina o recurso do Gateway de Agente:

    Defina um novo recurso de Gateway de Agente no modo AGENT_TO_ANYWHERE criando um arquivo de configuração YAML de gateway (por exemplo, my-agent-gateway-vpc-egress.yaml) que faça referência ao modelo de conectividade:

    name: AGENT_GATEWAY_NAME
    protocols:
      - MCP
    googleManaged:
      governedAccessPath: AGENT_TO_ANYWHERE
    agentConnectivityTemplate: projects/AGENT_GATEWAY_PROJECT_NUMBER/locations/LOCATION/agentConnectivityTemplates/CONNECTIVITY_TEMPLATE_NAME
    registries:
      - AGENT_REGISTRY_PATH
    

    Substitua:

    • AGENT_GATEWAY_NAME: o nome do recurso do Gateway de Agente.

    • AGENT_GATEWAY_PROJECT_NUMBER: o número do projeto do Google Cloud projeto em que você provisiona o Gateway de Agente e o modelo de conectividade. Para implantações de VPC compartilhada, esse projeto pode ser um projeto de serviço ou o projeto host. Para recuperar o número do projeto, execute: gcloud projects describe PROJECT_ID --format="value(projectNumber)".

    • LOCATION: o local do modelo de conectividade (por exemplo, europe-west1).

    • CONNECTIVITY_TEMPLATE_NAME: o nome do recurso do modelo de conectividade.

      • AGENT_REGISTRY_PATH: o caminho para a instância regional do Agent Registry no mesmo projeto e região do gateway, formatado como //agentregistry.googleapis.com/projects/PROJECT_ID/locations/LOCATION. Para orientações, consulte Planejar a implantação do Gateway de Agente.
  4. Importar e implantar o Gateway de Agente:

    Execute o seguinte comando para criar o recurso do Gateway de Agente com base na especificação YAML:

    gcloud network-services agent-gateways import AGENT_GATEWAY_NAME \
        --source="my-agent-gateway-vpc-egress.yaml" \
        --location=LOCATION
    

    Substitua LOCATION pelo local em que você quer criar o recurso do Gateway de Agente. Por exemplo, europe-west1.

Considerações sobre arquitetura e rede

Nesta seção, fornecemos orientações de arquitetura e padrões de rede avançados para implantar o Gateway de Agente com conectividade de VPC.

Como atualizar as configurações de saída da VPC

Não é possível modificar um modelo de conectividade no local enquanto ele é referenciado por um Gateway de Agente, e o Gateway de Agente não seleciona automaticamente as mudanças feitas em um modelo de conectividade anexado:

  • Atualização do peering de DNS, do modo de saída da VPC ou das configurações de TLS (tlsConfig): em um modelo de conectividade, o campo tlsConfig.trustConfig é imutável depois de configurado, e as atualizações no local para tlsConfig (como adicionar ou alterar additionalRoots) não são detectadas por um Gateway de Agente anexado. Para atualizar a configuração de peering de DNS, o modo de saída da VPC ou as configurações de tlsConfig em um gateway, crie um modelo de conectividade que use o mesmo networkAttachment com as configurações atualizadas e atualize o Gateway de Agente para referenciar o novo modelo (ou desvincule e vincule novamente o modelo de conectividade).

  • Alterar o anexo de rede: o networkAttachment em si é imutável depois de configurado no modelo de conectividade e no Gateway de Agente. Para mudar para um anexo de rede diferente (ou rede VPC de destino), crie um novo modelo de conectividade e um novo Gateway de Agente.

Topologias de implantação de VPC compartilhada

Em uma arquitetura de VPC compartilhada, é possível provisionar o Gateway de Agente em um projeto de serviço ou no projeto host. Ao provisionar o Gateway de Agente em um projeto de serviço, é possível criar o anexo de rede no projeto de serviço (recomendado) ou no projeto host:

Conformidade com o VPC Service Controls

Para aplicar os perímetros do VPC Service Controls às comunicações do agente, verifique o seguinte:

  • Defina vpcEgress como ALL_TRAFFIC no modelo de conectividade.

  • Direcione as solicitações de API do Google para o intervalo de IP restricted.googleapis.com (199.36.153.4/30) ou para um endpoint interno do Private Service Connect para APIs do Google.

  • Configure a resolução de DNS para googleapis.com. Crie uma zona de DNS particular do Cloud DNS na rede VPC mapeando *.googleapis.com para restricted.googleapis.com e inclua googleapis.com. no campo domains do modelo de conectividade.

    Para mais detalhes sobre a configuração de DNS, consulte Configurar o DNS para googleapis.com na documentação do Acesso Privado do Google.

  • Para implantações de VPC compartilhada, o projeto host que possui a sub-rede do anexo de rede e o dnsPeeringConfig.targetNetwork precisam estar no mesmo perímetro de serviço que o projeto em que você implanta o Gateway de Agente. Isso se aplica mesmo quando você cria o anexo de rede no projeto de serviço, porque a sub-rede e a rede VPC ainda pertencem ao projeto host. Se as zonas de DNS privadas estiverem hospedadas em um projeto de DNS separado, inclua esse projeto no perímetro também.

Padrões de domínio de peering de DNS

Nesta seção, descrevemos os padrões de resolução de domínio e as opções para configurar o campo domains em um modelo de conectividade.

Configuração do nome de domínio: configure o campo domains no modelo de conectividade com base nas seguintes considerações:

  • Domínios internos particulares: para resolver serviços internos particulares hospedados na sua rede VPC (por exemplo, service.corp.internal), especifique o sufixo de domínio interno (como corp.internal.). Uma zona gerenciada do Cloud DNS particular de correspondência exata para esse domínio precisa ser autorizada para a rede VPC de destino.

  • DNS de horizonte dividido (domínio público com IP RFC 1918): se você usar uma zona de DNS pública para hospedar registros que apontam para IPs privados internos (como mcp.example.com resolvendo para um endereço RFC 1918 para certificados públicos do Certificate Manager), o gateway resolverá esses registros automaticamente usando DNS recursivo público sem exigir peering de DNS.

  • APIsGoogle Cloud com VPC Service Controls: quando ALL_TRAFFIC está configurado para aplicar o VPC Service Controls, as solicitações de API do Google precisam ser resolvidas para o intervalo de IP restricted.googleapis.com (199.36.153.4/30) ou para endpoints internos do PSC. Crie uma zona particular do Cloud DNS no mapeamento da rede VPC de *.googleapis.com para restricted.googleapis.com e inclua googleapis.com. no campo domains do modelo de conectividade.

  • Padrões de resolução de vários domínios: se a implantação exigir a resolução de vários sufixos de domínio particular, escolha um dos seguintes padrões:

    • Fazer peering de vários domínios individuais: especifique uma lista de sufixos de domínio no campo domains de dnsPeeringConfig (por exemplo, corp.internal., prod.internal. e googleapis.com.). Cada domínio na lista precisa terminar com um ponto final (.) e ter uma zona gerenciada particular do Cloud DNS correspondente autorizada para a rede VPC de destino.
    • Sufixo pai consolidado (recomendado): consolide os serviços internos em um sufixo de domínio pai compartilhado (como *.internal. ou *.corp.internal.) e inclua esse domínio pai na lista domains.
    • Peering raiz catch-all com uma zona de encaminhamento particular: inclua "." no campo domains do modelo de conectividade e configure uma zona de encaminhamento particular do Cloud DNS para o domínio raiz (.) na sua rede VPC que aponta para um resolvedor recursivo upstream (como 8.8.8.8 ou um resolvedor empresarial interno). As zonas particulares mais específicas na sua VPC correspondem primeiro pela correspondência de sufixo mais longa, enquanto as consultas públicas sem correspondência são resolvidas pelo encaminhador upstream.

Requisitos de peering e zona de DNS entre projetos

A configuração dnsPeeringConfig do modelo de conectividade não é compatível com o peering de DNS direto do Cloud DNS entre projetos. Ao importar o modelo de conectividade, a validação vai falhar se a sub-rede referenciada pelo networkAttachment pertencer a uma rede VPC diferente de targetNetwork ou se você depender da vinculação de zona de DNS entre projetos de um serviço ou projeto externo.

A zona gerenciada do domínio precisa ser criada no projeto host que é proprietário de targetNetwork. A zona gerenciada pode ser de qualquer um destes tipos:

  • Zona privada autoritativa
  • Zona de encaminhamento
  • Zona de peering de DNS do Cloud DNS: precisa estar associada à rede VPC do projeto host e ter como destino uma rede VPC de destino. A VPC de destino precisa resolver a consulta diretamente usando uma zona particular autoritativa. O encaminhamento da consulta para outra zona de peering de DNS (encadeamento) não é compatível e resulta em um erro NXDOMAIN.

Escalonar projetos de serviço do Agent Runtime com um grupo do Google

Se você conectar vários projetos de serviço do Agent Runtime a um projeto host do Gateway de Agente e conceder acesso entre projetos a cada agente de serviço individualmente, será necessário atualizar a política do IAM do projeto host sempre que adicionar um projeto. Em implantações em grande escala, você também pode atingir os limites da política do IAM ao adicionar vinculações de papéis.

Para evitar a atualização da política do IAM do projeto host para cada novo projeto de serviço, gerencie o acesso por meio de um único grupo de segurança do Google:

  1. Criar um grupo de segurança: crie um grupo de segurança no Google Admin Console ou executando o comando gcloud identity groups create.

  2. Conceda ao grupo acesso ao projeto host do Gateway de Agente: vincule o grupo ao papel de Leitor de Serviços de Rede (roles/networkservices.viewer) em AGENT_GATEWAY_PROJECT_ID:

    gcloud projects add-iam-policy-binding AGENT_GATEWAY_PROJECT_ID \
        --member="group:GROUP_EMAIL" \
        --role="roles/networkservices.viewer"
    

    Substitua:

    • AGENT_GATEWAY_PROJECT_ID: o ID do projeto host do Gateway de Agente.
    • GROUP_EMAIL: o endereço de e-mail do seu grupo de segurança (por exemplo, agw-cross-project-runtime@example.com).
  3. Adicione o agente de serviço do Agent Runtime de cada projeto de serviço ao grupo: para cada projeto de serviço do Agent Runtime, adicione o agente de serviço ao grupo de segurança executando o comando gcloud identity groups memberships add da seguinte maneira:

    gcloud identity groups memberships add \
        --group-email="GROUP_EMAIL" \
        --member-email="service-AGENT_RUNTIME_PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com"
    

    Substitua AGENT_RUNTIME_PROJECT_NUMBER pelo número do projeto de serviço do Agent Runtime.

A seguir

Guia

Saiba como rotear o tráfego do Agent Runtime pelo Gateway de Agente para uma conectividade segura e controlada.

Codelab

Saiba como controlar cargas de trabalho agênticas com o Gateway de Agente na Gemini Enterprise Agent Platform.

Codelab

Aprenda mais sobre a governança de saída do Gateway de Agente para agentes de IA que acessam destinos em uma rede VPC.

Guia

Saiba como delegar a autorização do Gateway de Agente ao IAP, ao Model Armor ou ao seu próprio serviço de autorização personalizado.

Guia

Saiba como visualizar, atualizar, desassociar e excluir recursos do Gateway de Agente.

Guia

Saiba como monitorar o Gateway de Agente.

Guia

Saiba como rotear o tráfego do Gemini Enterprise pelo Gateway de Agente.