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_ONLYouALL_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
O Gateway de Agente é executado em um ambiente gerenciado pelo Google. Para permitir que os agentes acessem de forma particular recursos internos, como bancos de dados, ferramentas corporativas ou sistemas locais, sem expô-los à Internet pública, estabeleça uma conectividade de VPC particular.
Para conectar o Gateway de Agente à sua rede VPC, crie um anexo de rede do Private Service Connect em uma sub-rede dedicada na sua rede. Em seguida, defina um
modelo de conectividade do Gateway de Agente
(AgentConnectivityTemplate) que faça referência a esse anexo de rede e aplique
o modelo ao gateway.
Quando você implanta uma instância do Gateway de Agente com um modelo de conectividade, o Google provisiona uma interface do Private Service Connect que conecta o gateway ao seu anexo de rede. O tráfego de saída dos seus agentes flui por essa interface para a rede VPC, usando endereços IP de origem alocados da sub-rede do anexo de rede. Essa configuração permite que as regras de roteamento da VPC, as políticas de firewall, os gateways do Cloud NAT e os perímetros de serviço do VPC Service Controls controlem e protejam todo o tráfego de saída dos agentes.
Modos de saída de VPC
A configuração vpcEgress no modelo de conectividade controla qual tráfego de saída dos agentes é roteado pelo anexo de rede para a rede VPC e qual tráfego sai diretamente pelos caminhos de rede gerenciados pelo Google.
Dependendo da postura de segurança e dos requisitos de roteamento da sua organização, é possível configurar um dos dois modos de saída:
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/30restricted.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.
- RFC 1918:
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_TRAFFICpara oferecer suporte aos perímetros de serviço do VPC Service Controls.
- 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 (
Resolução de DNS particular 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 sua rede
VPC (como endpoints corp.internal. ou PSC), configure
o peering Cloud DNS no modelo de conectividade.
Quando você configura o peering de DNS do Cloud DNS, a resolução de DNS e o roteamento de pacotes de saída operam de maneira independente:
Caminho de resolução de DNS (
dnsPeeringConfig.targetNetwork): o Gateway de Agente usa o peering do Cloud DNS para encaminhar consultas DNS dodomainsconfigurado para a rede VPC de destino (targetNetwork). Dependendo da arquitetura da rede, você configuratargetNetworkusando uma das duas opções relativas à sub-rede de anexo de rede:Mesma rede VPC: a rede de destino é a mesma rede VPC que contém a sub-rede do anexo de rede. Use essa opção para implantações independentes (projeto único) ou de VPC compartilhada.
Rede VPC separada (como um hub de DNS central): a rede de destino está em outro projeto, como uma rede de hub de DNS central (ignorando o Cloud DNS spoke). Use essa opção em arquiteturas hub-and-spoke em que sua organização centraliza a resolução de DNS em um projeto hub dedicado separado da rede spoke que hospeda o anexo de rede.
Com qualquer uma das opções, o
targetNetworkpode resolver consultas DNS de duas maneiras:- Resolução direta (um salto de peering): o
targetNetworkresponde a consultas usando zonas particulares autoritativas, zonas vinculadas entre projetos ou zonas de encaminhamento autorizadas para otargetNetwork. - Peering transitivo do Cloud DNS (dois saltos de peering):
targetNetworkcorresponde a uma zona de peering de DNS do Cloud DNS que encaminha consultas para outra rede VPC. Como o Gateway de Agente é compatível com o peering de DNS transitivo até um único salto transitivo (no máximo dois saltos de peering do Cloud DNS em três redes VPC), a conexão de peering do Gateway de Agente comtargetNetworkusa o primeiro salto (salto 1), e a zona de peering de DNS detargetNetworkpara a rede de destino usa o segundo salto (salto 2). Essa rede de destino precisa responder a consultas usando zonas particulares autoritativas ou zonas de encaminhamento, e não pode encaminhar consultas por um terceiro salto de peering.
Caminho de saída de tráfego (
networkAttachment): independentemente da rede especificada emtargetNetwork, os pacotes de saída entram na rede VPC da sub-rede de anexo de rede do Private Service Connect. Se as cargas de trabalho de destino estiverem em outra rede (por exemplo, atrás de um hub central conectado com peering de rede VPC e VPN de alta disponibilidade ou Cloud Interconnect com Cloud Router), verifique se as regras de roteamento de IP e firewall permitem o tráfego entre a sub-rede de anexo de rede e os endereços IP de destino resolvidos.
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:
| 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 sua rede VPC de destino, diretamente ou por um salto transitivo de peering do Cloud DNS. | O tráfego entra na rede VPC do anexo de rede e segue as rotas para cargas de trabalho internas ou com peering. |
| 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
tlsConfigno modelo de conectividade.Ao referenciar um recurso
TrustConfigdo 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, definaadditionalRootscomoPUBLICLY_TRUSTED_ROOTS. Sem essa configuração, o Gateway de Agente não confia em certificados assinados pelo Google paragoogleapis.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 mudanças feitas emtlsConfig(como atualizaradditionalRoots) 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.
- Ao usar
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 seu projeto:
- 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 (a menos que targetNetwork resida em um projeto de hub de DNS separado).
Se você provisionar o Gateway de Agente em um projeto de serviço enquanto a
rede VPC compartilhada, a sub-rede, o anexo de rede ou as zonas de DNS particulares
estiverem no projeto host (HOST_PROJECT_ID) ou se
targetNetwork estiver em um projeto de hub de DNS central separado
(DNS_HUB_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 nesses projetos. Conceda os seguintes papéis, além das permissões padrão do Gateway de Agente:
| 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 (HOST_PROJECT_ID) |
|
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 (HOST_PROJECT_ID) |
|
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 (HOST_PROJECT_ID) |
|
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) |
|
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.. |
| Anexo de rede no projeto host | |||
| Agente de serviço do Gateway de Agente2 | Projeto host (HOST_PROJECT_ID) |
|
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. |
Topologia de hub de DNS entre projetos
(targetNetwork em um projeto separado) |
|||
| Agente de serviço do Gateway de Agente2 | Projeto de hub de DNS (DNS_HUB_PROJECT_ID) |
|
Permite que o agente de serviço do Gateway de Agente valide a rede VPC hub e as zonas particulares do Cloud DNS (incluindo a distância de salto de peering) e faça peering com zonas particulares do Cloud DNS na rede hub. Conceda esses papéis de DNS no projeto hub em vez do projeto independente ou host quando targetNetwork estiver em um projeto separado. Para conferir as etapas de configuração, consulte Configurar o peering de DNS. |
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). - 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
/28mínima para o anexo de rede. Uma sub-rede/28fornece 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/26ou/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
Conclua esta seção somente se os agentes precisarem resolver nomes de domínio internos privados (como corp.internal.) ou aplicar o VPC Service Controls para APIs do Google (googleapis.com.). Se você estiver configurando o peering de DNS entre projetos, leia Resolução de DNS privado e roteamento de tráfego e conceda os papéis de agente de serviço entre projetos em VPC compartilhada ou implantações entre projetos.
Para configurar o peering de DNS, siga estas etapas:
Escolha a rede VPC de destino (
targetNetwork), que é a rede VPC que contém a sub-rede de anexo de rede ou uma rede separada, como um hub de DNS central, e configure as zonas particulares do Cloud DNS usando uma das seguintes opções:- Resolução direta em
targetNetwork(um salto de peering): use essa opção quandotargetNetworkresolver consultas diretamente em implantações independentes, de VPC compartilhada ou de hub único. Autorize zonas gerenciadas particulares (e adicione seus registros DNS) ou zonas de encaminhamento paratargetNetwork, no mesmo projeto quetargetNetworkou em um projeto de DNS separado usando vinculação entre projetos. Peering transitivo de
targetNetworkpara outra rede VPC (dois saltos de peering): use essa opção quandotargetNetwork(sua rede anexada ou uma rede central de hub de DNS) encaminhar consultas para uma rede VPC de destino que hospeda ou encaminha registros DNS:- No projeto de destino, autorize zonas particulares autoritativas (e adicione seus registros DNS) ou zonas de encaminhamento para a rede VPC de destino.
No projeto
targetNetwork, verifique setargetNetworknão tem uma zona conflitante para o mesmo nome de DNS e crie uma zona de peering autorizada paratargetNetworkque tenha como destino a rede VPC de destino (por exemplo, para um sufixo de domínio particular específico ou o domínio raiz.).
- Resolução direta em
Reúna as seguintes informações para configurar o modelo de conectividade em Implantar o Gateway de Agente:
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. Dependendo da topologia de implantação,TARGET_VPC_PROJECT_IDé um dos seguintes IDs de projeto:AGENT_GATEWAY_PROJECT_IDpara implantações independentes em quetargetNetworkestá no mesmo projeto.HOST_PROJECT_IDpara implantações de VPC compartilhada, em quetargetNetworké a rede host.DNS_HUB_PROJECT_IDquandotargetNetworkestá em um projeto de hub de DNS central separado.
Nomes de domínio (
domains): um ou mais sufixos de domínio que terminam com um ponto final (.), comocorp.internal.,googleapis.com.ou.(ao encaminhar todas as consultas para uma zona de encaminhamento raiz ou zona de peering de DNS raiz notargetNetwork).Para padrões de domínio de peering e regras de validação, consulte Padrões de domínio de peering de DNS e Requisitos de zona de DNS e peering entre projetos.
Opcional: definir a configuração de confiança de TLS
Se o destino de destino usar uma AC 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.
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.
Execute o comando a seguir para criar o recurso
TrustConfig. OTrustConfigprecisa 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_FILESubstitua:
TRUST_CONFIG_NAME: um nome para o recursoTrustConfig.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
Implante o Gateway de Agente com as configurações de conectividade da VPC:
Console
- No console do Google Cloud , acesse a página Gateways.
- Clique em Adicionar gateway.
- No campo Nome, insira um nome para o gateway.
- Na lista Região, selecione uma região.
- Em Modo de implantação, verifique se a opção Gerenciado pelo Google está selecionada.
- O campo Agent Registry é preenchido automaticamente com o URI do registro regional que corresponde à região do Gateway de Agente.
- Na lista Caminho de acesso governado, selecione Agente para qualquer lugar (saída).
Na seção Autorização de acesso, configure como o tráfego é processado pelo Identity-Aware Proxy (IAP):
Para implantar o gateway em um modo de teste em que ele permite todo o tráfego e gera apenas registros de auditoria, selecione Somente auditoria.
Para bloquear solicitações que não têm uma política do IAM
Allowexplícita, selecione Aplicar políticas. Essa opção é recomendada para ambientes de produção.Em Modelo de política, selecione Política de acesso unificada.
Opcional: na seção Segurança de IA, configure outras medidas de segurança:
- Para proteger as interações do modelo de IA com o Model Armor, clique no botão Ativar o Model Armor para a posição ativada.
- Selecione um modelo para as solicitações recebidas pelo gateway.
- Para usar um modelo diferente para as respostas, desmarque a caixa de seleção Usar o mesmo modelo para solicitações e respostas e selecione um modelo na lista.
Na seção Modelo de conectividade, faça as seguintes alterações:
Para rotear o tráfego de saída do gateway por uma rede VPC privada, clique no botão de alternância Rotear o tráfego de saída por uma rede VPC para a posição de ativação e faça o seguinte:
- Em Anexo de rede, insira o URI completo do anexo de rede que você criou na rede VPC de destino:
projects/TARGET_VPC_PROJECT_ID/regions/REGION/networkAttachments/ATTACHMENT_NAME Em Saída da VPC, selecione uma das seguintes opções:
- Somente intervalos particulares: permite apenas o tráfego de IP particular.
- Todo o tráfego: permite o tráfego de IP particular e público. Essa opção é necessária para compliance com o VPC Service Controls.
- Em Anexo de rede, insira o URI completo do anexo de rede que você criou na rede VPC de destino:
Opcional: para configurar o peering de DNS, marque a caixa de seleção Ativar peering de DNS e faça o seguinte:
- Em Domínios, insira um ou mais sufixos de domínio para
peering de DNS. Cada domínio precisa terminar com um ponto final (
.), por exemplo,corp.internal.ougoogleapis.com.. - Em Rede de destino, insira o URI completo da rede VPC de destino em que você criou o anexo de rede:
projects/TARGET_VPC_PROJECT_ID/global/networks/TARGET_VPC_NETWORK_NAME.
- Em Domínios, insira um ou mais sufixos de domínio para
peering de DNS. Cada domínio precisa terminar com um ponto final (
Opcional: para se conectar a destinos que usam CAs particulares ou certificados autoassinados, clique no botão Usar uma configuração de confiança de TLS personalizada para a posição de ativação e faça o seguinte:
- No campo Configuração de confiança, insira o URI da configuração de confiança que você criou anteriormente, usando o seguinte formato:
projects/AGENT_GATEWAY_PROJECT_NUMBER/locations/REGION/trustConfigs/TRUST_CONFIG_NAME. Em Raízes adicionais, selecione uma das seguintes opções:
- Raízes publicamente confiáveis: confie em certificados validados pela configuração Configuração de confiança e em todas as CAs publicamente confiáveis.
- Nenhuma raiz adicional: confie apenas nos certificados validados pela configuração Configuração de confiança.
- No campo Configuração de confiança, insira o URI da configuração de confiança que você criou anteriormente, usando o seguinte formato:
Clique em Adicionar gateway.
gcloud
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_OPTIONSubstitua:
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 comoAGENT_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 comoCENTRALIZED.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 emdomainspara 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. Dependendo da topologia de implantação, essa é a rede VPC que contém a sub-rede de anexo de rede ou uma rede VPC em um projeto de hub de DNS separado:TARGET_VPC_PROJECT_ID: o ID do projeto que é proprietário da rede VPC de destino:AGENT_GATEWAY_PROJECT_IDpara implantações independentes,HOST_PROJECT_IDpara redes host de VPC compartilhada ouDNS_HUB_PROJECT_IDpara uma rede de hub de DNS separada. Sempre especifiquetargetNetworkusando o ID do projeto, e 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 comoPRIVATE_RANGES_ONLYouALL_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 recursoTrustConfigdo 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âmetrotrustConfige em todas as CAs publicamente confiáveis. DefinaadditionalRootscomoPUBLICLY_TRUSTED_ROOTSse 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 paragoogleapis.com. - Defina como
NO_ADDITIONAL_ROOTSpara confiar apenas nos certificados validados pelo parâmetrotrustConfig.
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=LOCATIONSubstitua:
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.
Defina o recurso do Gateway de Agente:
Defina um novo recurso de Gateway de Agente no modo
AGENT_TO_ANYWHEREcriando 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_PATHSubstitua:
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.
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=LOCATIONSubstitua
LOCATIONpelo 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 campotlsConfig.trustConfigé imutável depois de configurado, e as atualizações no local paratlsConfig(como adicionar ou alteraradditionalRoots) não são detectadas por um Gateway de Agente anexado. Para atualizar a configuração de peering de DNS (incluindo a troca detargetNetworkpara uma rede VPC ou um projeto diferente), o modo de saída da VPC ou as configurações detlsConfigem um gateway, crie um novo modelo de conectividade que faça referência ao mesmonetworkAttachmentcom as configurações atualizadas e executegcloud network-services agent-gateways importpara apontar o Gateway de Agente para o novo modelo. Essa atualização é concluída no local sem recriar o gateway ou reimplantar os agentes conectados.Alterar o anexo de rede: o
networkAttachmentem si é imutável depois de configurado no modelo de conectividade e no Gateway de Agente. Para mudar para um anexo de rede diferente, 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:
- Recomendado: anexo de rede no projeto de serviço:
- Crie a sub-rede no projeto host.
- Crie o anexo de rede no projeto de serviço, referenciando a sub-rede do projeto host.
- Anexo de rede no projeto host:
- Crie a sub-rede no projeto host.
- Crie o anexo de rede 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
vpcEgresscomoALL_TRAFFICno 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.compararestricted.googleapis.come incluagoogleapis.com.no campodomainsdo 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 e hub-and-spoke de DNS entre projetos, todos os projetos no caminho de saída e de resolução de DNS, incluindo o projeto proprietário da sub-rede do anexo de rede, o projeto proprietário do
targetNetworke qualquer projeto separado que hospede zonas de Cloud DNS privadas entre projetos ou com peering, 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 em um projeto de serviço de VPC compartilhada, porque a sub-rede e a rede VPC ainda pertencem ao projeto host.
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 (comocorp.internal.). Uma zona gerenciada particular do Cloud DNS correspondente (correspondência exata ou sufixo pai) precisa ser autorizada ou acessível em um salto de peering de DNS da 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.comresolvendo 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.APIs doGoogle Cloud com VPC Service Controls: quando o
ALL_TRAFFICé configurado para aplicar o VPC Service Controls, as solicitações de API do Google precisam ser resolvidas para o intervalo de IPrestricted.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.compararestricted.googleapis.come incluagoogleapis.com.no campodomainsdo 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
domainsdednsPeeringConfig(por exemplo,corp.internal.,prod.internal.egoogleapis.com.). Cada domínio na lista precisa terminar com um ponto final (.) e ter uma zona gerenciada de nuvem privada do Cloud DNS correspondente autorizada ou com peering com 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 listadomains. Peering raiz catch-all com uma zona de encaminhamento ou zona de peering de DNS: inclua
"."no campodomainsdo modelo de conectividade e configure uma das seguintes zonas raiz (.) na rede VPC de destino (targetNetwork):- Uma zona de encaminhamento particular do Cloud DNS que aponta para um
resolvedor recursivo upstream (como
8.8.8.8ou um resolvedor empresarial interno), em que zonas particulares mais específicas na sua rede VPC de destino correspondem primeiro pela correspondência de sufixo mais longo. - Uma zona de peering de DNS do Cloud DNS em uma rede hub de DNS central (consulte Configurar peering de DNS) que segmenta uma terceira rede VPC que resolve zonas particulares internas e nomes públicos.
- Uma zona de encaminhamento particular do Cloud DNS que aponta para um
resolvedor recursivo upstream (como
- Fazer peering de vários domínios individuais: especifique uma lista de sufixos de domínio
no campo
Requisitos de zona de DNS e peering entre projetos
A configuração dnsPeeringConfig do modelo de conectividade é compatível com topologias de DNS entre projetos em redes VPC e projetos de zona do Cloud DNS:
targetNetworkentre projetos (desacoplado denetworkAttachment): quandotargetNetworkreside em um projeto diferente do Gateway de Agente (como um projeto host de VPC compartilhada ou um projeto de hub de DNS central), o Gateway de Agente valida a rede de destino e as zonas dela usando o agente de serviço do Gateway de Agente. Conceda os papéis de agente de serviço necessários no projetotargetNetwork, conforme descrito em Implantações de VPC compartilhada ou entre projetos.Vinculação de zona de DNS entre projetos: as zonas gerenciadas de nuvem privada do Cloud DNS autorizadas para
targetNetworkpodem residir no projeto que possuitargetNetworkou em um projeto de DNS separado usando a vinculação entre projetos.Quando uma zona particular reside em um projeto separado que o Gateway de Agente não inspeciona, como um projeto de vinculação de DNS entre projetos separado ou um projeto com peering de segundo salto em que o agente de serviço do Gateway de Agente não tem o papel
roles/dns.reader, o Gateway de Agente ignora a verificação da zona e permite a configuração. Especifique corretamente os sufixos emdomains, porque erros de digitação de domínio para zonas nesses projetos não são detectados durante a criação do modelo e falham comNXDOMAINno ambiente de execução.Tipos de zona compatíveis e limite de peering de dois saltos: cada domínio configurado em
domainspode ser resolvido emtargetNetworkpor qualquer um dos seguintes tipos de zona gerenciada:- Zona particular autoritativa: resolve registros definidos diretamente na zona.
- Zona de encaminhamento: encaminha consultas para destinos de encaminhamento particular configurados ou resolvedores upstream.
- Zona de peering de DNS do Cloud DNS (segundo salto de peering):
o Cloud DNS segue no máximo
dois saltos de peering,
e a zona de peering de DNS gerenciada do Gateway de Agente para
targetNetworkusa o primeiro salto. SetargetNetworkcorresponder a uma zona de peering de DNS do Cloud DNS (salto 2) que segmenta uma terceira rede VPC, essa rede de destino precisará responder à consulta usando uma zona particular autoritativa ou uma zona de encaminhamento. O encaminhamento da consulta por outra zona de peering de DNS para uma quarta rede (um terceiro salto de peering) ou a formação de um ciclo de peering falha na validação (ou não é resolvida no ambiente de execução).
Se a rede spoke da carga de trabalho fizer peering com um hub de DNS central que, por sua vez, faz peering com um terceiro projeto, aponte targetNetwork diretamente para a rede do hub de DNS para permanecer dentro de dois saltos de peering. Para conferir as etapas de configuração, consulte Configurar o peering de DNS.
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:
Criar um grupo de segurança: crie um grupo de segurança no Google Admin Console ou executando o comando
gcloud identity groups create.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) emAGENT_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).
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 addda 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_NUMBERpelo número do projeto de serviço do Agent Runtime.
A seguir
Rotear o tráfego do Agent Runtime pelo Gateway de Agente
Saiba como rotear o tráfego do Agent Runtime pelo Gateway de Agente para uma conectividade segura e controlada.
Codelab: controlar cargas de trabalho de agentes com a Agent Platform
Saiba como controlar cargas de trabalho agênticas com o Gateway de Agente na Gemini Enterprise Agent Platform.
Codelab: saída do Gateway de Agente do Agent Runtime para redes VPC
Saiba mais sobre a governança de saída do Gateway de Agente para agentes de IA que acessam destinos em uma rede VPC.
Delegar autorização para o Gateway de Agente
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.
Gerenciar o Gateway de Agente
Saiba como visualizar, atualizar, desassociar e excluir recursos do Gateway de Agente.
Encaminhar o tráfego do Gemini Enterprise pelo Gateway de Agente
Saiba como rotear o tráfego do Gemini Enterprise pelo Gateway de Agente.