CLI Gemini no GCE com um endpoint do Private Service Connect

1. Visão geral

É possível usar a CLI do Gemini nos ambientes local e virtual. A CLI do Gemini é um agente de IA de código aberto que leva o poder do Gemini diretamente ao seu terminal. Do ponto de vista de rede, quando você usa a CLI Gemini, ela faz uma chamada para a API Gemini usando o endereço IP da API, que é acessível publicamente.

E se você quiser usar a CLI Gemini em uma máquina do Google Compute Engine, mas se conectar à API de forma privada? Neste codelab, você vai aprender a configurar um endpoint do Private Service Connect para APIs do Google e rotear o tráfego para um endereço IP interno especificado.

As configurações serão uma combinação de Terraform, gcloud e console.

Neste laboratório, você vai aprender a fazer o seguinte:

• Configurar a instância de VM e o Cloud NAT
• Instalar e autenticar a CLI do Gemini
• Configurar o endpoint do Private Service Connect para se conectar a Googleapis
• Verificar o caminho de conectividade para *.googleais
• Configurar entradas DNS manuais

Neste laboratório, você vai criar o seguinte padrão.

Figura 1.

2. Configuração dos serviços do Google Cloud

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.

3. Tarefa 1: Configurar o ambiente com o Terraform

Vamos criar uma VPC personalizada com regras de firewall e uma sub-rede. Abra o console do Cloud e selecione o projeto que você vai usar.

1. Abra o Cloud Shell, localizado na parte superior direita do console. Verifique se o ID do projeto correto aparece no Cloud Shell e confirme todas as solicitações para permitir o acesso.
2. Crie uma pasta chamada "terraform-build" e acesse-a.

mkdir terraform-build  && cd terraform-build

3. Crie um arquivo main.tf e variable.tf.

touch main.tf variable.tf 

4. Mude para a visualização do editor do Cloud Shell. Selecione editor e permita todos os avisos necessários para que a interface possa ser carregada.
5. Depois de carregado, navegue até Arquivo > Abrir pasta e acesse /home/your-user-name/terraform-build. Selecione Ok para abrir a pasta no editor.
6. Selecione o arquivo variable.tf e adicione o seguinte. Substitua o texto your-project-id-here pelo ID do projeto entre aspas.

variable "project_id" {
  type = string
  default = "your-project-id-here"
}

variable "network_id" {
  type = string
  default = "gemini-vpc-net"
}

7. Em seguida, abra o arquivo main.tf. Vamos adicionar um código do Terraform para realizar várias ações, conforme explicado abaixo.

Ativar APIs	resource "google_project_service" "default"
Criar VPC chamada python-net	resource "google_compute_network" "default"
Adicionar uma sub-rede	resource "google_compute_subnetwork" "default"
Adicionar duas regras de firewall	resource "google_compute_firewall" "allow_icmp"resource "google_compute_firewall" "allow_ssh"

8. Copie e cole o seguinte no arquivo main .tf.

resource "google_project_service" "default" {
  for_each = toset([
    "dns.googleapis.com",
    "aiplatform.googleapis.com",
    "servicedirectory.googleapis.com"
  ])

  service            = each.value
  disable_on_destroy = false
}

resource "google_compute_network" "default" {
  project                 = var.project_id
  name                    = var.network_id
  auto_create_subnetworks = false
  mtu                     = 1460
  routing_mode            = "GLOBAL"
}

resource "google_compute_subnetwork" "default" {
  name          = "vm1-subnet"
  ip_cidr_range = "192.168.100.0/24"
  region        = "us-east1"
  stack_type    = "IPV4_ONLY"
  network       = google_compute_network.default.id
}

resource "google_compute_firewall" "allow_icmp" {
  name    = "allow-icmp-${google_compute_network.default.name}"
  network = google_compute_network.default.id
  project = var.project_id

  allow {
    protocol = "icmp"
  }

  source_ranges = ["0.0.0.0/0"]
  target_tags   = ["allow-icmp"]
}

resource "google_compute_firewall" "allow_ssh" {
  name    = "allow-ssh-${google_compute_network.default.name}"
  network = google_compute_network.default.id
  project = var.project_id

  allow {
    protocol = "tcp"
    ports    = ["22"]
  }

  source_ranges = ["0.0.0.0/0"]
  target_tags   = ["allow-ssh"]
}

9. Volte para o terminal do Cloud Shell, verifique se você está no diretório terraform-build cd terraform-build e execute os comandos a seguir:

terraform init

Inicializa o diretório de trabalho. Essa etapa faz o download dos provedores necessários para a configuração especificada.

terraform plan

Gera um plano de execução, mostrando quais ações o Terraform vai realizar para implantar sua infraestrutura.

10. Agora, para criar os recursos, execute o comando terraform apply e digite yes para executar.

Verifique sua configuração:confira se o ambiente tem

• VPC chamada gemini-vpc-net
• sub-rede
• firewall-rules

4. Tarefa 2: Criar um gateway NAT e VMs com o Terraform

Precisamos conceder acesso externo de saída à Internet. Portanto, vamos criar e anexar um gateway do Cloud NAT.

1. Abra o Cloud Shell, navegue até a pasta terraform-build e crie os seguintes arquivos (total de três arquivos). Vamos editar isso mais tarde.

touch nat-vm.tf psc.tf dns.tf

2. Mude para a visualização do editor do Cloud Shell, selecione o arquivo nat-vm.tf e adicione o seguinte código do Terraform. Isso vai criar um gateway NAT e duas VMs.

Terraform nat-vm.tf

resource "google_compute_router" "default" {
  name    = "outbound-nat"
  region  = "us-east1"
  network = google_compute_network.default.id

 bgp {
  asn = 64514
  }
}

resource "google_compute_router_nat" "default" {
  name                               = "outbound-gw"
  router                             = google_compute_router.default.name
  region                             = google_compute_router.default.region
  nat_ip_allocate_option             = "AUTO_ONLY"
  source_subnetwork_ip_ranges_to_nat = "ALL_SUBNETWORKS_ALL_IP_RANGES"

  log_config {
    enable = true
    filter = "ERRORS_ONLY"
  }
}

resource "google_compute_instance" "vm1" {
  name         = "cli-vm"
  zone         = "us-east1-b"
  machine_type = "n2-standard-2"

  boot_disk {
    initialize_params {
      image = "debian-cloud/debian-12"
    }
  }

  network_interface {
    subnetwork = google_compute_subnetwork.default.id  
    stack_type = "IPV4_ONLY"
  }

  tags = ["allow-ssh", "allow-icmp"]

  metadata_startup_script = <<-EOF
    sudo apt-get update    
  EOF
}

resource "google_compute_instance" "vm2" {
  name         = "monitor-vm"
  zone         = "us-east1-b"
  machine_type = "n2-standard-2"

  boot_disk {
    initialize_params {
      image = "debian-cloud/debian-12"
    }
  }

  network_interface {
    subnetwork = google_compute_subnetwork.default.id   
    stack_type = "IPV4_ONLY"
  }

  tags = ["allow-ssh", "allow-icmp"]

  metadata_startup_script = <<-EOF
    sudo apt-get update
    sudo apt-get install python3 python3-dev python3-venv -y
    sudo apt-get install tcpdump dnsutils -y
  EOF
}

3. Mude para o terminal do Cloud Shell, verifique se você está na pasta terraform-build e execute terraform plan. Isso vai mostrar que quatro itens serão adicionados. Em seguida, execute terraform apply e digite yes para criar o gateway NAT e duas VMs.

Verifique sua configuração:confira se o ambiente tem

1 gateway NAT

1 Cloud Router

VM chamada cli-vm

VM chamada monitor-vm

5. Tarefa 3: Configurar VMs da CLI e testar

1. Navegue até "Instâncias de VM". Selecione a VM que começa com cli-vm. Escolha SSH.
2. Depois de fazer o SSH, você terá acesso à VM. Vamos criar uma pasta para quando executarmos a CLI do Gemini.

mkdir geminicli && cd geminicli

3. Para instalar a CLI Gemini, precisamos do Node.js. Instale o node JS usando o seguinte

curl -fsSL https://deb.nodesource.com/setup_24.x -o nodesource_setup.sh

Executar script

sudo -E bash nodesource_setup.sh

Instalar o Node.js

sudo apt-get install -y nodejs

4. Vamos definir algumas variáveis que vão ajudar a usar a opção de autenticação da Vertex AI para autenticar e fazer alguns testes mais tarde. Substitua YOUR_PROJECT_ID pelo seu project ID real.

cat <<EOF >> ~/.bashrc 

export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
export GOOGLE_CLOUD_LOCATION="us-east1" 
export GOOGLE_GENAI_USE_VERTEXAI=true
EOF

Atualizar o bash

source ~/.bashrc

5. Agora vamos fazer a autenticação. Execute o seguinte comando na VM e pressione y quando solicitado.

gcloud auth application-default login

6. Em seguida, copie o URL que aparece começando com https://, abra uma nova guia na janela do navegador do laboratório e cole o URL. Aceite os comandos.
7. Quando você vir a opção de copiar, volte para a sessão da VM cli-vm e, em Inserir código de autorização, cole o código copiado e pressione "Enter" para autenticar.

8. Agora vamos instalar a CLI do Gemini. Execute o comando

sudo npm install -g @google/gemini-cli

Depois de concluir, digite gemini para iniciar a interface, selecione um tema de sua preferência e, em Selecionar método de autenticação, escolha Vertex AI.

9. Depois de autenticado, você pode começar a usar a CLI do Gemini.

Observação:você pode mudar a pergunta do comando para outra coisa.

Monitorar a rota de tráfego para o Gemini usando a VM de monitoramento

1. Navegue até "Instâncias de VM". Selecione a VM que começa com monitor-vm. Escolha SSH.
2. Depois de usar SSH para acessar monitor-vm, você terá acesso
3. Vamos usar o comando dig para testar o caminho de conexão com a API Gemini. Vamos usar o us-east1-aiplatform.googleapis.com

dig us-east1-aiplatform.googleapis.com

Você vai ver algo parecido (o endereço será diferente). O caminho é feito por endereços IP públicos porque a API é pública.

NÃO COPIE

; <<>> DiG 9.18.33-1~deb12u2-Debian <<>> us-east1-aiplatform.googleapis.com
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 58905
;; flags: qr rd ra; QUERY: 1, ANSWER: 14, AUTHORITY: 0, ADDITIONAL: 1

;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 65494
;; QUESTION SECTION:
;us-east1-aiplatform.googleapis.com. IN A

;; ANSWER SECTION:
us-east1-aiplatform.googleapis.com. 300 IN A    173.194.217.95
us-east1-aiplatform.googleapis.com. 300 IN A    172.217.204.95
us-east1-aiplatform.googleapis.com. 300 IN A    172.217.203.95
us-east1-aiplatform.googleapis.com. 300 IN A    142.250.98.95
us-east1-aiplatform.googleapis.com. 300 IN A    142.251.107.95
us-east1-aiplatform.googleapis.com. 300 IN A    74.125.196.95
us-east1-aiplatform.googleapis.com. 300 IN A    173.194.216.95
us-east1-aiplatform.googleapis.com. 300 IN A    108.177.11.95
us-east1-aiplatform.googleapis.com. 300 IN A    192.178.219.95
us-east1-aiplatform.googleapis.com. 300 IN A    173.194.210.95
us-east1-aiplatform.googleapis.com. 300 IN A    173.194.212.95
us-east1-aiplatform.googleapis.com. 300 IN A    173.194.215.95
us-east1-aiplatform.googleapis.com. 300 IN A    108.177.12.95
us-east1-aiplatform.googleapis.com. 300 IN A    74.125.26.95

4. Agora vamos fazer um teste rápido de ping para ver se conseguimos nos conectar à API Gemini. Esse comando usa quatro pings para us-east1-aiplatform.googleapis.com, assim recebemos uma resposta do endereço público da API.

ping -c 4 us-east1-aiplatform.googleapis.com

5. Vamos voltar para testar essa VM mais tarde. Encerre a sessão SSH e vamos continuar.

6. Tarefa 4: Criar o endpoint do PSC para googleapis com o Terraform

Para ativar a conectividade particular com nosso endpoint da API Vertex, vamos criar um endpoint do Private Service Connect para APIs do Google. Isso nos permite usar um endereço IP particular que atribuímos para rotear o tráfego para as APIs do Google de que precisamos, neste caso, a Vertex.

1. Abra o Cloud Shell na visualização do editor, se ele ainda não estiver aberto. Vamos criar o seguinte:

• Crie um IP para o endpoint do PSC 10.10.100.250 (resource "google_compute_global_address" "default")
• Crie um endpoint do PSC para APIs do Google (resource "google_compute_global_forwarding_rule" "default")

Abra o arquivo psc.tf na pasta terraform-build. Adicione o seguinte código ao arquivo.

Terraform psc.tf

resource "google_compute_global_address" "default" {
  name         = "gemini-ip"
  purpose      = "PRIVATE_SERVICE_CONNECT"
  network      = google_compute_network.default.id
  address_type = "INTERNAL"
  address      = "10.10.100.250"
}

resource "google_compute_global_forwarding_rule" "default" {  
  name                  = "pscgemini"
  target                = "all-apis"
  network               = google_compute_network.default.id
  ip_address            = google_compute_global_address.default.id
  load_balancing_scheme = ""
  }

2. Mude para o terminal do Cloud Shell e confira se você está na pasta terraform-build. Em seguida, execute terraform init e terraform plan. Isso vai mostrar que dois itens serão adicionados.
   Depois, execute terraform apply e digite yes para criar o endpoint de APIs do Google de IP e PSC.
3. Verificar se o endpoint existe

gcloud compute addresses list --filter="name=( 'gemini-ip' ...)"

gcloud compute forwarding-rules describe pscgemini --global

7. Tarefa 5: Criar uma entrada DNS manual para googleapis com o Terraform

É possível criar uma entrada DNS manual para apontar para o endpoint do PSC usando o DNS particular. Isso afetaria todas as redes atribuídas a ele.

1. Acesse "Serviços de rede" e selecione "Cloud DNS".
2. Nas zonas, você vai encontrar uma zona criada automaticamente para o Private Service Connect para APIs do Google, com o tipo de zona "diretório de serviços". Isso pode ser usado para se conectar ao endpoint do PSC com o formato **SERVICE-ENDPOINT.p.googleapis.com. Exemplo: aiplatform-pscgemini.p.googleapis.com
3. Neste caso, vamos criar manualmente uma entrada de DNS particular. A configuração será a seguinte:

• Crie uma zona de DNS particular chamada "googleapis-private" para "googleapis.com" e restrinja-a à rede "python-net".
• Adicione um registro A para mapear "googleapis.com" para o endereço IP "10.10.100.250".
• Adicione um registro CNAME para redirecionar todos os subdomínios de "googleapis.com" (por exemplo, www.googleapis.com) para "googleapis.com".

4. Abra o Cloud Shell na visualização do editor, se ele ainda não estiver aberto. Abra o arquivo dns.tf na pasta "terraform-build". Adicione o seguinte código ao arquivo.

Terraform dns.tf

resource "google_dns_managed_zone" "private_zone" {
  name        = "googleapis-private"
  dns_name    = "googleapis.com."  
  visibility  = "private"
  project     = var.project_id     

  private_visibility_config {
    networks {
      network_url = google_compute_network.default.id  
    }
  }
}

resource "google_dns_record_set" "a_record" {
  name    = "googleapis.com."  
  type    = "A"
  ttl     = 300
  managed_zone = google_dns_managed_zone.private_zone.name
  project = var.project_id    

  rrdatas = ["10.10.100.250"]
}

resource "google_dns_record_set" "cname_record" {
 name    = "*.googleapis.com."
 type    = "CNAME"
 ttl     = 300
 managed_zone = google_dns_managed_zone.private_zone.name
 project = var.project_id    

 rrdatas = ["googleapis.com."]  
}

5. Mude para o terminal do Cloud Shell e confira se você está na pasta terraform-build. Em seguida, execute terraform plan. Isso vai mostrar quais itens serão adicionados.
   Depois, execute terraform apply e digite yes para criar a entrada de DNS particular.
6. Você vai ver uma configuração com um registro A e um CNAME como este:

7. Em seguida, vamos verificar a conectividade com essas mudanças em monitor-vm.

8. Tarefa 7: Verificar a conectividade do endpoint com o endereço IP

Vamos nos conectar usando o endpoint particular para acessar o Gemini.

Observação:não são necessárias configurações manuais na VM.

1. Acesse a instância de VM monitor-vm. Selecione SSH e faça login na VM
2. Verifique o caminho de conectividade para us-east1-aiplatform.googleapis.com usando o comando ping. Isso vai fazer ping no endereço IP no DNS particular, um registro para googleapis. Esse IP é um endpoint do PSC, e seus pings não vão funcionar.

ping -c 2 us-east1-aiplatform.googleapis.com

3. Verifique o caminho de conectividade com um ping usando a entrada DNS criada automaticamente para APIs do Google do PSC com aiplatform-pscvertexgemini.p.googleapis.com. Isso aponta para o endereço IP do endpoint do PSC, e seus pings não vão funcionar.

ping -c 2 aiplatform-pscgemini.p.googleapis.com

4. Verifique o caminho de conectividade para us-east1-aiplatform.googleapis.com usando o comando dig. Esse precisa ser o endereço IP do endpoint do PSC (10.10.100.250).

dig us-east1-aiplatform.googleapis.com

5. Depois de concluir, feche a sessão SSH monitor-vm.
6. Agora podemos executar um despejo de TCP na cli-vm. Precisamos abrir duas sessões SSH na mesma VM. Uma sessão vai executar o comando tcpdump, e a outra vai usar a CLI do Gemini.
7. Conecte-se via SSH à primeira sessão na cli-vm.
8. Digite o seguinte comando para ver a conectividade em um tcpdump

sudo tcpdump -i any port 53 -n or host us-east1-aiplatform.googleapis.com

9. Agora, use o SSH na próxima sessão da cli-vm.
10. Ative a CLI do Gemini digitando gemini
11. Faça a seguinte pergunta: "Qual é a cor do céu?" para gerar uma chamada à API Gemini.

12. Pressione Enter para executar e conferir o resultado.
13. Volte para a primeira sessão em cli-vm. Você vai ver o resultado do tcpdump. Você vai notar que o endereço IP da VM está usando o endereço IP do endpoint do PSC para se conectar à API Gemini.

Fechar todas as sessões SSH para instâncias de VM

9. Limpeza

1. Acesse o Cloud Shell, confira se você está no diretório terraform-build cd terraform-build e execute o seguinte comando terraform destroy e digite yes. Todos os recursos criados no projeto com o Terraform serão removidos.

10. Parabéns

Parabéns! Você se conectou à CLI Gemini usando o endereço da API pública e de forma privada com o endpoint do Private Service Connect para APIs do Google. Essa funcionalidade pode estender a conectividade de API particular para seu ambiente local/de outra nuvem conectado via Interconnect, Cross-Cloud Interconnect e VPC.

Próximas etapas / Saiba mais

Leia mais sobre redes da Vertex AI e confira o repositório da CLI Gemini.

Comece o próximo laboratório

Continue sua Quest com o Google Cloud e confira estes outros laboratórios do Google Cloud:

• Noções básicas de rede no Google Cloud
• Descobrindo a IA generativa - Vertex AI
• Tour do Cloud Networking