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
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/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 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:
| 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
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 alterações 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 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:
| 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) |
|
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) |
|
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) |
|
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 (TARGET_VPC_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. |
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
/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
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:
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.
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.ougoogleapis.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.
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
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. 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_IDserá o ID do projeto host da VPC compartilhada. Sempre especifiquetargetNetworkusando 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 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, o modo de saída da VPC ou as configurações detlsConfigem um gateway, crie um modelo de conectividade que use o mesmonetworkAttachmentcom 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
networkAttachmentem 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:
- 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, o projeto host que possui a sub-rede do anexo de rede e o
dnsPeeringConfig.targetNetworkprecisam 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 (comocorp.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.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.APIsGoogle Cloud com VPC Service Controls: quando
ALL_TRAFFICestá 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 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 listadomains. Peering raiz catch-all com uma zona de encaminhamento particular: inclua
"."no campodomainsdo 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 (como8.8.8.8ou 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.
- Fazer peering de vários domínios individuais: especifique uma lista de sufixos de domínio
no campo
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:
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
Aprenda 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.