Do Agentspace para um banco de dados auto-hospedado de NEG zonal

1. Introdução

OBSERVAÇÃO: este codelab oferece orientação de configuração para acessar um banco de dados autohospedado no GCE usando um NEG zonal, publicado pelo Private Service Connect. Modifique o codelab conforme necessário para se alinhar aos requisitos específicos da sua organização.

Neste codelab, você vai implantar um balanceador de carga de proxy TCP interno e um grupo de endpoints de rede (NEG) zonal, publicado como um serviço de produtor do PSC. O NEG vai consistir em uma ou mais instâncias de computação no auto-hospedagem do GCP de um banco de dados, por exemplo, JIRA, Confluence, Sharepoint.

O Private Service Connect é um recurso da rede do Google Cloud que permite que os consumidores acessem serviços gerenciados de maneira particular na rede VPC deles. Da mesma forma, ele permite que produtores de serviços gerenciados hospedem esses serviços na própria rede VPC ou entre nuvens, oferecendo uma conexão particular aos consumidores. Por exemplo, ao usar o Private Service Connect para acessar um NEG zonal, você é o produtor de serviços, e o Google (Agentspace) é o consumidor de serviços.

O que você vai aprender

• Requisitos de rede para o Agentspace
• Práticas recomendadas de rede do Agentspace
• Criar um serviço de produtor do Private Service Connect

O que é necessário

• Projeto do Google Cloud com permissões de proprietário

2. O que você vai criar

Você vai estabelecer uma rede de produtor, agentspace-psc-demo, para implantar o balanceador de carga de proxy TCP interno e o NEG zonal publicado como um serviço pelo Private Service Connect (PSC).

3. Requisitos de rede

Confira abaixo o detalhamento dos requisitos de rede para a rede do produtor. O consumidor neste codelab é o Agentspace.

Componentes	Descrição
VPC (agentspace-psc-demo)	VPC de modo personalizado
Sub-rede NAT do PSC	Os pacotes da rede VPC do consumidor são convertidos usando a NAT de origem (SNAT) para que os endereços IP de origem sejam convertidos em endereços IP de origem da sub-rede NAT na rede VPC do produtor. O NAT do PSC aceita uma sub-rede /29 por anexo de serviço.
Sub-rede da regra de encaminhamento do PSC	Usada para alocar um endereço IP para o balanceador de carga de proxy TCP interno regional.A sub-rede da regra de encaminhamento é considerada uma sub-rede regular.
Sub-rede do NEG	Usado para alocar um endereço IP para o grupo de endpoints da rede de uma sub-rede normal.
Sub-rede somente proxy	Cada um dos proxies do balanceador de carga recebe um endereço IP interno. Os pacotes enviados de um proxy para uma VM de back-end ou um grupo de endpoints de rede têm um endereço IP de origem da sub-rede somente proxy.Uma sub-rede /23 é recomendada , embora a mínima, /26, seja compatível. Uma sub-rede de proxy regional é necessária por região.
Serviço de back-end	Um serviço de back-end atua como uma ponte entre o balanceador de carga e os recursos de back-end. No tutorial, o serviço de back-end está associado ao NEG zonal.

4. Práticas recomendadas

• As NEGs zonais oferecem suporte a uma ou mais instâncias zonais do GCE com base em GCE_VM_IP_PORT.
• Ative o acesso global na regra de encaminhamento do produtor antes de criar o anexo de serviço.
• Ative o acesso global ao criar o endpoint do Agentspace.
• O balanceador de carga de proxy TCP interno também é compatível com grupos de instâncias gerenciadas e não gerenciadas.
• Um proxy TCP ou balanceador de carga de passagem do Google Cloud pode ser exposto como um serviço do produtor.

5. Topologia do codelab

6. Configuração e requisitos

Configuração de ambiente autoguiada

1. Faça login no Console do Google Cloud e crie um novo projeto ou reutilize um existente. Crie uma conta do Gmail ou do Google Workspace, se ainda não tiver uma.

• O Nome do projeto é o nome de exibição para os participantes do projeto. É uma string de caracteres não usada pelas APIs do Google e pode ser atualizada quando você quiser.
• O ID do projeto precisa ser exclusivo em todos os projetos do Google Cloud e não pode ser mudado após a definição. O console do Cloud gera automaticamente uma string exclusiva. Em geral, não importa o que seja. Na maioria dos codelabs, é necessário fazer referência ao ID do projeto, normalmente identificado como PROJECT_ID. Se você não gostar do ID gerado, crie outro aleatório. Se preferir, teste o seu e confira se ele está disponível. Ele não pode ser mudado após essa etapa e permanece durante o projeto.
• Para sua informação, há um terceiro valor, um Número do projeto, que algumas APIs usam. Saiba mais sobre esses três valores na documentação.

Atenção: o ID do projeto é globalmente exclusivo e não pode ser usado por outras pessoas após a seleção. Você é o único usuário com esse ID. Mesmo que um projeto seja excluído, o ID não poderá ser usado novamente.

Observação: se você usa uma conta do Gmail, defina o local padrão como Sem organização. Se você usa uma conta do Google Workspace, escolha um local adequado para a organização.

2. Em seguida, ative o faturamento no console do Cloud para usar os recursos/APIs do Cloud. A execução deste codelab não vai ser muito cara, se tiver algum custo. Para encerrar os recursos e evitar cobranças além deste tutorial, exclua os recursos criados ou exclua o projeto. Novos usuários do Google Cloud estão qualificados para o programa de US$ 300 de avaliação sem custos.

Inicie o Cloud Shell

Embora o Google Cloud e o Spanner possam ser operados remotamente do seu laptop, neste codelab usaremos o Google Cloud Shell, um ambiente de linha de comando executado no Cloud.

No Console do Google Cloud, clique no ícone do Cloud Shell na barra de ferramentas superior à direita:

O provisionamento e a conexão com o ambiente levarão apenas alguns instantes para serem concluídos: Quando o processamento for concluído, você verá algo como:

Essa máquina virtual contém todas as ferramentas de desenvolvimento necessárias. Ela oferece um diretório principal persistente de 5 GB, além de ser executada no Google Cloud. Isso aprimora o desempenho e a autenticação da rede. Neste codelab, todo o trabalho pode ser feito com um navegador. Você não precisa instalar nada.

7. Antes de começar

Ativar APIs

No Cloud Shell, verifique se o ID do projeto está configurado:

gcloud config list project
gcloud config set project [YOUR-PROJECT-ID]
project=[YOUR-PROJECT-ID]
region=[YOUR-REGION]
zone1a=[YOUR-ZONE1a]
zone1b=[YOUR-ZONE1b]
echo $project
echo $region
echo $zone1a
echo $zone1b

Ative todos os serviços necessários:

gcloud services enable compute.googleapis.com

8. Criar rede VPC do produtor

Rede VPC

No Cloud Shell, faça o seguinte:

gcloud compute networks create agentspace-psc-demo --subnet-mode custom

Criar sub-redes

A sub-rede do PSC será associada ao anexo de serviço do PSC para fins de conversão de endereços de rede.

No Cloud Shell, crie a sub-rede NAT do PSC:

gcloud compute networks subnets create producer-psc-nat-subnet --network agentspace-psc-demo --range 172.16.10.0/28 --region $region --purpose=PRIVATE_SERVICE_CONNECT

No Cloud Shell, crie a sub-rede da regra de encaminhamento do produtor:

gcloud compute networks subnets create producer-psc-fr-subnet --network agentspace-psc-demo --range 172.16.20.0/28 --region $region --enable-private-ip-google-access

No Cloud Shell, crie a sub-rede do grupo de endpoints de rede:

gcloud compute networks subnets create neg-subnet --network agentspace-psc-demo --range 172.16.30.0/28 --region $region --enable-private-ip-google-access

No Cloud Shell, crie a sub-rede somente proxy regional do produtor.

gcloud compute networks subnets create $region-proxy-only-subnet \
  --purpose=REGIONAL_MANAGED_PROXY \
  --role=ACTIVE \
  --region=$region \
  --network=agentspace-psc-demo \
  --range=10.10.10.0/24

Reserve o endereço IP do balanceador de carga

No Cloud Shell, reserve um endereço IP interno para o balanceador de carga:

gcloud compute addresses create zonal-neg-lb-ip \
  --region=$region \
  --subnet=producer-psc-fr-subnet

No Cloud Shell, confira o endereço IP reservado.

gcloud compute addresses describe zonal-neg-lb-ip \
  --region=$region | grep -i address:

Exemplo de saída:

gcloud compute addresses describe zonal-neg-lb-ip --region=$region | grep -i address:
address: 172.16.20.2

Configurar o NEG zonal

Na seção a seguir, você vai criar um grupo de endpoints de rede zonal que contém um ou mais endereços IP ou combinações de endereço IP e porta de destino:

• O endereço IPv4 interno principal de uma interface de rede da VM
• O endereço IPv4 interno principal de uma interface de rede de VM mais um número de porta de destino
• Um endereço IPv4 interno do intervalo de endereços IP do alias atribuído a uma interface de rede da VM
• Um endereço IPv4 interno do intervalo de endereços IP do alias atribuído a uma interface de rede da VM, além de um número de porta de destino.

A interface de rede que contém o endpoint GCE_VM_IP_PORT precisa estar na sub-rede do NEG. Quando você omite um número de porta de um endpoint GCE_VM_IP_PORT, o Google Cloud usa o número de porta padrão do NEG para o endpoint.

Na arquitetura de referência, as instâncias do GCE associadas ao NEG zonal consistem no seguinte:

• database-us-central1-a | us-central1-a | IP: 100.100.10.2 | Porta: 443
• database-us-central1-a | us-central1-b | IP: 100.100.10.3 | Porta: 443
• Nome da sub-rede: database-subnet-1

Criar o NEG zonal para zone1a

Na seção a seguir, você vai criar o grupo de endpoints de rede por zona, por exemplo, us-central1-a, e especificar o nome da sub-rede usada para criar a instância do GCE. Na arquitetura de referência, o nome da sub-rede é database-subnet-1.

No Cloud Shell, crie um NEG zonal:

gcloud compute network-endpoint-groups create us-central-zonal-neg-1a \
    --zone=$zone1a \
    --network=agentspace-psc-demo \
    --subnet=database-subnet-1 \
    --default-port=443

No Cloud Shell, atualize o NEG zonal com o IP:Port da instância do GCE implantada na zona 1a. Na arquitetura de referência, a instância do GCE é 100.100.10.2 Porta 443 implantada na zona us-central1-a.

gcloud compute network-endpoint-groups update us-central-zonal-neg-1a --zone=$zone1a --add-endpoint instance=database-us-central1-a,port=443

Criar o NEG zonal para zone1b

Na seção a seguir, você vai criar o grupo de endpoints de rede por zona, por exemplo, us-central1-b, e especificar o nome da sub-rede usada para criar a instância do GCE. Na arquitetura de referência, o nome da sub-rede é database-subnet-1.

No Cloud Shell, crie um NEG zonal:

gcloud compute network-endpoint-groups create us-central-zonal-neg-1b \
    --zone=$zone1b \
    --network=agentspace-psc-demo \
    --subnet=database-subnet-1 \
    --default-port=443

No Cloud Shell, atualize o NEG zonal com o IP:Port da instância do GCE implantada na zona 1b. Na arquitetura de referência, a instância do GCE é 100.100.10.3 Porta 443 implantada na zona us-central1-b.

gcloud compute network-endpoint-groups update us-central-zonal-neg-1b --zone=$zone1b --add-endpoint instance=database-us-central1-b,port=443

Criar uma verificação de integridade regional

No Cloud Shell, crie uma verificação de integridade que teste a porta do banco de dados local, 443:

gcloud compute health-checks create tcp zonal-443-healthcheck \
    --region=$region \
    --port=443

Criar uma política de firewall de rede e regras de firewall

No Cloud Shell, faça o seguinte:

gcloud compute network-firewall-policies create agentspace-psc-demo-policy --global

gcloud compute network-firewall-policies associations create --firewall-policy agentspace-psc-demo-policy --network agentspace-psc-demo --name agentspace-psc-demo --global-firewall-policy

A regra de firewall a seguir permite o tráfego do intervalo da sub-rede NAT do PSC para todas as instâncias na rede.

No Cloud Shell, faça o seguinte:

gcloud compute network-firewall-policies rules create 2001 --action ALLOW --firewall-policy agentspace-psc-demo-policy --description "allow traffic from PSC NAT subnet to GCE" --direction INGRESS --src-ip-ranges 172.16.10.0/28 --global-firewall-policy --layer4-configs=tcp

A regra de firewall a seguir permite o tráfego do intervalo de sondagem de verificação de integridade para todas as instâncias na rede. A porta de verificação de integridade e a porta do aplicativo precisam corresponder.

No Cloud Shell, faça o seguinte:

gcloud compute network-firewall-policies rules create 2002 --action ALLOW --firewall-policy agentspace-psc-demo-policy --description "allow internal probe health check range to GCE" --direction INGRESS --src-ip-ranges 35.191.0.0/16,130.211.0.0/22 --global-firewall-policy --layer4-configs=tcp:443

A regra de firewall a seguir permite o tráfego do intervalo da sub-rede somente proxy para todas as instâncias na rede. A sub-rede de proxy e a porta do aplicativo precisam ser iguais.

No Cloud Shell, faça o seguinte:

gcloud compute network-firewall-policies rules create 2003 --action ALLOW --firewall-policy agentspace-psc-demo-policy --description "allow internal tcp proxy health check range to GCE" --direction INGRESS --src-ip-ranges 10.10.10.0/24 --global-firewall-policy --layer4-configs=tcp:443

9. Criar serviço de produtor

Criar componentes do balanceador de carga

No Cloud Shell, crie um serviço de back-end:

gcloud compute backend-services create producer-backend-svc --region=$region --load-balancing-scheme=INTERNAL_MANAGED --protocol=TCP --region=$region --health-checks=zonal-443-healthcheck --health-checks-region=$region

No Cloud Shell, associe o NEG zonal, us-central-zonal-neg-1a, ao serviço de back-end:

gcloud compute backend-services add-backend producer-backend-svc \
   --network-endpoint-group=us-central-zonal-neg-1a  \
   --network-endpoint-group-zone=$zone1a \
   --balancing-mode=CONNECTION \
   --max-connections-per-endpoint=100 \
   --region=$region

No Cloud Shell, associe o NEG zonal, us-central-zonal-neg-1b,ao serviço de back-end:

gcloud compute backend-services add-backend producer-backend-svc \
   --network-endpoint-group=us-central-zonal-neg-1b  \
   --network-endpoint-group-zone=$zone1b \
   --balancing-mode=CONNECTION \
   --max-connections-per-endpoint=100 \
   --region=$region

No Cloud Shell, crie um proxy TCP de destino para encaminhar solicitações ao serviço de back-end:

gcloud compute target-tcp-proxies create producer-lb-tcp-proxy \
      --backend-service=producer-backend-svc  \
      --region=$region

Na sintaxe a seguir, crie uma regra de encaminhamento (balanceador de carga de proxy TCP interno) com o acesso global ativado.

No Cloud Shell, faça o seguinte:

gcloud compute forwarding-rules create producer-zonal-neg-fr \
     --load-balancing-scheme=INTERNAL_MANAGED \
     --network-tier=PREMIUM \
     --network=agentspace-psc-demo \
     --subnet=producer-psc-fr-subnet \
     --address=zonal-neg-lb-ip \
     --target-tcp-proxy=producer-lb-tcp-proxy \
     --target-tcp-proxy-region=$region \
     --region=$region \
     --allow-global-access \
     --ports=443

Validar a integridade do back-end

Valide a integridade (status verde) do serviço de back-end e das instâncias de computação associadas usando o console do Cloud na seção a seguir. Acesse:

Serviços de rede → Balanceamento de carga → Producer-backend-svc

Criar anexo de serviço

Para publicar um serviço, é preciso criar um anexo de serviço do Private Service Connect. É possível publicar o serviço com aprovação automática ou explícita.

• Para publicar o serviço e permitir automaticamente que qualquer consumidor se conecte a ele, siga as instruções em Publicar um serviço com aprovação automática.
• Para publicar o serviço com aprovação explícita do consumidor, nas configurações de conexão do anexo de serviço, selecione "Aceitar conexões para projetos selecionados" e deixe o campo "Projetos aceitos" em branco.
• Depois de gerar o anexo de serviço, os endpoints do consumidor que solicitarem acesso ao serviço do produtor vão entrar em um estado pendente. Para autorizar a conexão, o produtor precisa aceitar o projeto de origem da solicitação de endpoint do consumidor.

No Cloud Shell, crie o anexo de serviço cc-database1-svc-attachment com aprovação automática:

gcloud compute service-attachments create zonal-database1-svc-attachment --region=$region --producer-forwarding-rule=producer-zonal-neg-fr --connection-preference=ACCEPT_AUTOMATIC --nat-subnets=producer-psc-nat-subnet

Em seguida, obtenha e anote o anexo de serviço listado no URI selfLink que começa com "projects" para configurar o endpoint do PSC no Agentspace.

selfLink: projects/<your-project-id>/regions/<your-region>/serviceAttachments/zonal-database1-svc-attachment

No Cloud Shell, faça o seguinte:

gcloud compute service-attachments describe zonal-database1-svc-attachment --region=$region

Exemplo de saída esperada:

connectionPreference: ACCEPT_AUTOMATIC
creationTimestamp: '2025-07-12T16:00:22.429-07:00'
description: ''
enableProxyProtocol: false
fingerprint: zOpeRQnPWSc=
id: '1784245893044590569'
kind: compute#serviceAttachment
name: zonal-database1-svc-attachment
natSubnets:
- https://www.googleapis.com/compute/v1/projects/$project-svc4/regions/us-central1/subnetworks/producer-psc-nat-subnet
pscServiceAttachmentId:
  high: '119824781489996776'
  low: '1784245893044590569'
reconcileConnections: false
region: https://www.googleapis.com/compute/v1/projects/$project-svc4/regions/us-central1
selfLink: https://www.googleapis.com/compute/v1/projects/$project-svc4/regions/us-central1/serviceAttachments/zonal-database1-svc-attachment
targetService: https://www.googleapis.com/compute/v1/projects/$project-svc4/regions/us-central1/forwardingRules/producer-zonal-neg-fr

No console do Cloud, navegue até:

Serviços de rede → Private Service Connect → Serviços publicados

10. Estabelecer uma conexão de endpoint do PSC no Agentspace

Associe o URI do anexo de serviço dos produtores ao Agentspace e verifique se o acesso global está selecionado. Confira abaixo um exemplo de ativação do acesso global com o anexo de serviço da arquitetura de referência.

Para finalizar a rede particular, consulte as fontes de dados de terceiros do Agentspace para mais instruções.

Validar o endpoint do PSC no console do Cloud

Para confirmar uma conexão PSC bem-sucedida entre o Agentspace (o consumidor) e o produtor, verifique o projeto locatário do Agentspace vinculado ao serviço do produtor. Ele pode ser encontrado em "Projetos conectados". O ID do projeto do locatário é atribuído aleatoriamente, mas sempre termina com "tp".

No console do Cloud, é possível validar a conexão do PSC. No console do Cloud, navegue até:

Serviços de rede → Private Service Connect → Serviço publicado e selecione o serviço zonal-database1-svc-attachment.

11. Limpar

Excluir componentes do laboratório em um único terminal do Cloud Shell

gcloud compute service-attachments delete zonal-database1-svc-attachment --region=$region -q

gcloud compute forwarding-rules delete producer-zonal-neg-fr --region=$region -q

gcloud compute target-tcp-proxies delete producer-lb-tcp-proxy --region=$region -q

gcloud compute backend-services delete producer-backend-svc --region=$region -q

gcloud compute network-firewall-policies rules delete 2001 --firewall-policy agentspace-psc-demo-policy --global-firewall-policy -q

gcloud compute network-firewall-policies rules delete 2002 --firewall-policy agentspace-psc-demo-policy --global-firewall-policy -q

gcloud compute network-firewall-policies rules delete 2003 --firewall-policy agentspace-psc-demo-policy --global-firewall-policy -q

gcloud compute network-firewall-policies associations delete --firewall-policy=agentspace-psc-demo-policy  --name=agentspace-psc-demo --global-firewall-policy -q

gcloud compute network-firewall-policies delete agentspace-psc-demo-policy --global -q

gcloud compute network-endpoint-groups delete us-central-zonal-neg-1a --zone=$zone1a -q

gcloud compute network-endpoint-groups delete us-central-zonal-neg-1b --zone=$zone1b -q

gcloud compute addresses delete zonal-neg-lb-ip --region=$region -q

gcloud compute networks subnets delete $region-proxy-only-subnet --region=$region -q

gcloud compute networks subnets delete producer-psc-nat-subnet --region=$region -q

gcloud compute networks subnets delete producer-psc-fr-subnet --region=$region -q

gcloud compute networks subnets delete neg-subnet --region=$region -q

gcloud compute health-checks delete zonal-443-healthcheck --region=us-central1 -q

gcloud compute networks delete agentspace-psc-demo -q

12. Parabéns

Parabéns, você configurou e publicou um serviço de produtor com o Private Service Connect.

Você criou a infraestrutura do produtor, aprendeu a criar um NEG zonal, um serviço do produtor e associar o anexo de serviço ao Agentspace.

O Cosmopup acha que os codelabs são incríveis!

Qual é a próxima etapa?

Confira alguns destes codelabs:

• Como usar o Private Service Connect para publicar e consumir serviços
• Acesso a todos os codelabs publicados do Private Service Connect

Leituras e vídeos complementares

• Visão geral do Private Service Connect

Documentos de referência

• Visão geral do balanceador de carga de rede de proxy interno
• Configurar um balanceador de carga de rede de proxy interno regional com back-ends de NEG por zona
• Como publicar um serviço usando o Private Service Connect