Antigravity CLI su GCE con un endpoint Private Service Connect

1. Panoramica

Puoi utilizzare l'interfaccia a riga di comando Antigravity sia nell'ambiente locale che in quello virtuale. Antigravity porta la potenza di Gemini direttamente nel tuo terminale. Dal punto di vista del networking, quando utilizzi Antigravity CLI, viene effettuata una chiamata all'API Gemini tramite l'indirizzo IP dell'API, che è accessibile pubblicamente.

Ora, cosa succede se vuoi utilizzare Antigravity CLI su una macchina Google Compute Engine, ma vuoi connetterti all'API in modo privato? In questo codelab vedrai come configurare l'endpoint Private Service Connect per le API di Google, in modo da indirizzare il traffico a un indirizzo IP interno specificato.

Le configurazioni saranno una combinazione di Terraform, gcloud e console.

In questo lab imparerai a svolgere la seguente attività:

• Configura l'istanza VM e Cloud NAT
• Installa l'interfaccia a riga di comando Antigravity ed esegui l'autenticazione
• Configura l'endpoint Private Service Connect per connetterti a Googleapis
• Verifica il percorso di connettività a *.googleapis
• Configurare le voci DNS manuali

In questo lab creerai il seguente pattern.

Figura 1.

2. Configurazione dei servizi Google Cloud

Configurazione dell'ambiente autonomo

1. Accedi alla console Google Cloud e crea un nuovo progetto o riutilizzane uno esistente. Se non hai ancora un account Gmail o Google Workspace, devi crearne uno.

• Il nome del progetto è il nome visualizzato per i partecipanti a questo progetto. È una stringa di caratteri non utilizzata dalle API di Google. Puoi sempre aggiornarlo.
• L'ID progetto è univoco in tutti i progetti Google Cloud ed è immutabile (non può essere modificato dopo l'impostazione). La console Cloud genera automaticamente una stringa univoca, di solito non ti interessa di cosa si tratta. Nella maggior parte dei codelab, dovrai fare riferimento all'ID progetto (in genere identificato come PROJECT_ID). Se l'ID generato non ti piace, puoi generarne un altro casuale. In alternativa, puoi provare a crearne uno e vedere se è disponibile. Non può essere modificato dopo questo passaggio e rimane per tutta la durata del progetto.
• Per tua informazione, esiste un terzo valore, un numero di progetto, utilizzato da alcune API. Scopri di più su tutti e tre questi valori nella documentazione.

Attenzione:un ID progetto è univoco a livello globale e non può essere utilizzato da altri dopo che lo hai selezionato. Sei l'unico utente di questo ID. Anche se un progetto viene eliminato, l'ID non può essere riutilizzato

Nota:se utilizzi un account Gmail, puoi lasciare la località predefinita impostata su Nessuna organizzazione. Se utilizzi un account Google Workspace, scegli una posizione adatta alla tua organizzazione.

2. Successivamente, devi abilitare la fatturazione in Cloud Console per utilizzare le risorse/API Cloud. Completare questo codelab non costa molto, se non nulla. Per arrestare le risorse ed evitare addebiti oltre a quelli previsti in questo tutorial, puoi eliminare le risorse che hai creato o il progetto. I nuovi utenti di Google Cloud possono beneficiare del programma prova senza costi di 300$.

Avvia Cloud Shell

Sebbene Google Cloud possa essere gestito da remoto dal tuo laptop, in questo codelab utilizzerai Google Cloud Shell, un ambiente a riga di comando in esecuzione nel cloud.

Nella console Google Cloud, fai clic sull'icona di Cloud Shell nella barra degli strumenti in alto a destra:

Bastano pochi istanti per eseguire il provisioning e connettersi all'ambiente. Al termine, dovresti vedere un risultato simile a questo:

Questa macchina virtuale è caricata con tutti gli strumenti per sviluppatori di cui avrai bisogno. Offre una home directory permanente da 5 GB e viene eseguita su Google Cloud, migliorando notevolmente le prestazioni e l'autenticazione della rete. Tutto il lavoro in questo codelab può essere svolto all'interno di un browser. Non devi installare nulla.

3. Configura l'ambiente con Terraform

Creeremo un VPC personalizzato con regole firewall e subnet. Apri la console Cloud e seleziona il progetto che utilizzerai.

1. Apri Cloud Shell in alto a destra nella console, assicurati di visualizzare l'ID progetto corretto in Cloud Shell e conferma le richieste di autorizzazione all'accesso.
2. Crea una cartella denominata terraform-build e spostati al suo interno

mkdir terraform-build && cd terraform-build 

3. Crea un file main.tf e variable.tf.

touch main.tf variable.tf 

4. Passa alla visualizzazione dell'editor di Cloud Shell. Seleziona Editor e assicurati di consentire tutti i prompt necessari per caricare l'interfaccia.
5. Una volta caricato, vai a File > Apri cartella e vai a /home/your-user-name/terraform-build e seleziona Ok per aprire la cartella nell'editor.
6. Seleziona il file variable.tf e aggiungi quanto segue. Sostituisci il testo your-project-id-here con l'ID progetto effettivo tra virgolette.

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

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

7. A questo punto, apri il file main.tf. Aggiungeremo del codice Terraform per eseguire varie azioni, come spiegato di seguito.

Abilita API	resource "google_project_service" "default"
Crea un VPC chiamato python-net	resource "google_compute_network" "default"
Aggiungi una subnet	resource "google_compute_subnetwork" "default"
Aggiungi due regole firewall	resource "google_compute_firewall" "allow_icmp"resource "google_compute_firewall" "allow_ssh"

8. Copia e incolla quanto segue nel file 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. Torna al terminale Cloud Shell, assicurati di trovarti nella directory terraform-build cd terraform-build ed esegui questi comandi:

terraform init

Inizializza la directory di lavoro. Questo passaggio scarica i provider richiesti per la configurazione specificata.

terraform plan

Genera un piano di esecuzione, che mostra le azioni che Terraform eseguirà per eseguire il deployment dell'infrastruttura.

10. Ora, per creare le risorse, esegui il comando terraform apply e digita yes per eseguire.

Verifica la configurazione: controlla l'ambiente per

• VPC denominato antigravity-vpc-net
• subnet
• firewall-rules

4. Attività 2: Crea gateway NAT e VM con Terraform

Dobbiamo concedere l'accesso esterno in uscita a internet, quindi creiamo un gateway Cloud NAT e lo colleghiamo.

1. Apri Cloud Shell, vai alla cartella terraform-build e crea i seguenti file (tre in totale). Li modificheremo in un secondo momento.

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

2. Passa alla visualizzazione Editor di Cloud Shell, seleziona il file nat-vm.tf e aggiungi il seguente codice Terraform. Verranno creati un gateway NAT e due VM.

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. Passa al terminale Cloud Shell, assicurati di trovarti nella cartella terraform-build ed esegui terraform plan. Verrà visualizzato che verranno aggiunti 4 elementi, quindi esegui terraform apply e digita yes per creare il gateway NAT e due VM.

Verifica la configurazione: controlla l'ambiente per

1 gateway NAT

1 router Cloud

VM denominata cli-vm

VM denominata monitor-vm

5. Attività 3: Configura le VM CLI e testale

1. Vai a Istanze VM. Seleziona la VM che inizia con cli-vm. Scegli SSH.
2. Una volta eseguito SSH, dovresti avere accesso alla VM. Creiamo una cartella per quando eseguiamo la CLI Gemini.

mkdir antigravitycli && cd antigravitycli

3. Per installare Antigravity CLI, utilizza il seguente comando

curl -fsSL https://antigravity.google/cli/install.sh | bash && source ~/.bashrc

Controllare la versione

agy --version

4. Accediamo e autentichiamoci per fare dei test in un secondo momento.

agy

5. Seleziona l'opzione 1 Google OAuth . Ora eseguiamo l'autenticazione.
6. Copia quindi l'URL che inizia con https://, apri una nuova scheda nella finestra del browser del lab e incolla l'URL. Accetta le richieste.

7. Quando viene visualizzato il seguente messaggio, seleziona Copia negli appunti, torna alla sessione cli-vm della VM e, per Inserisci codice di autorizzazione, incolla il codice copiato e premi Invio per eseguire l'autenticazione.

8. Torna alla sessione della VM cli-vm e, per Enter authorization code: (Inserisci codice di autorizzazione), incolla il codice che hai copiato e premi Invio per eseguire l'autenticazione.

9. Dovresti visualizzare la schermata in cui puoi personalizzare e accettare il contratto e andare alla tua directory Home. Seleziona le opzioni pertinenti da completare.

10. Una volta completata la procedura, puoi iniziare a utilizzare l'interfaccia a riga di comando Antigravity.

Nota:puoi modificare la domanda del prompt.

Monitorare il percorso del traffico verso Gemini tramite la VM di monitoraggio

1. Vai a Istanze VM. Seleziona la VM che inizia con monitor-vm. Scegli SSH.
2. Una volta eseguito l'accesso SSH a monitor-vm, dovresti avere accesso
3. Utilizziamo il comando dig per testare il percorso di connessione all'API Gemini. Utilizzeremo us-east1-aiplatform.googleapis.com

dig us-east1-aiplatform.googleapis.com

Dovresti vedere qualcosa di simile (l'indirizzo sarà diverso). Tieni presente che il percorso avviene tramite indirizzi IP pubblici, poiché l'API è pubblica.

NON COPIARE

; <<>> 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    216.239.38.223
us-east1-aiplatform.googleapis.com. 300 IN A    216.239.34.223
us-east1-aiplatform.googleapis.com. 300 IN A    216.239.36.223
us-east1-aiplatform.googleapis.com. 300 IN A    216.239.32.223

4. Ora eseguiamo un rapido test ping per verificare se riusciamo a connetterci all'API Gemini. Questo comando utilizzerà 4 ping per us-east1-aiplatform.googleapis.com, quindi riceveremo una risposta dall'indirizzo pubblico dell'API.

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

5. Torneremo a testare questa VM in un secondo momento. Chiudi la sessione SSH e continuiamo.

6. Attività 4: Crea l'endpoint PSC per googleapis con Terraform

Per abilitare la connettività privata al nostro endpoint API Vertex, creeremo un endpoint Private Service Connect per le API di Google. Ciò ci consentirà di utilizzare un indirizzo IP privato che assegniamo per instradare il traffico alle API di Google di cui abbiamo bisogno, in questo caso Vertex.

1. Apri Cloud Shell nella visualizzazione dell'editor, se non è già aperta. Creeremo quanto segue:

• Crea un IP per l'endpoint PSC 10.10.100.250 (resource "google_compute_global_address" "default")
• Crea un endpoint PSC per le API di Google (resource "google_compute_global_forwarding_rule" "default")

Apri il file psc.tf nella cartella terraform-build. Aggiungi il seguente codice al file.

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 = ""
  
  service_directory_registrations {
    namespace                = "googleapis"
    service_directory_region = "us-east1"
  }
}

2. Passa al terminale Cloud Shell e assicurati di trovarti nella cartella terraform-build. Quindi esegui terraform init Quindi esegui terraform plan, che ti mostrerà che verranno aggiunti due elementi,
   poi esegui terraform apply e digita yes per creare l'endpoint API di Google IP e PSC.
3. Verifica l'esistenza dell'endpoint

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

gcloud compute forwarding-rules describe pscgemini --global

7. Attività 5: Crea una voce DNS manuale in googleapis con Terraform

Puoi creare una voce DNS manuale che punti all'endpoint PSC utilizzando il DNS privato. Ciò influirà su tutte le emittenti che gli assegni.

1. Vai a Servizi di rete e seleziona Cloud DNS.
2. Nelle zone dovresti vedere una zona creata automaticamente per Private Service Connect per le API di Google, con il tipo di zona Service Directory. Può essere utilizzato per connettersi all'endpoint PSC con il formato **SERVICE-ENDPOINT.p.googleapis.com. Esempio: aiplatform-pscgemini.p.googleapis.com
3. In questo caso vogliamo creare manualmente una voce DNS privata. La configurazione sarà la seguente

• Crea una zona DNS privata denominata "googleapis-private" per "googleapis.com" e limitane l'accesso alla rete "antigravity-vpc-net".
• Aggiungi un record A per mappare "googleapis.com" all'indirizzo IP "10.10.100.250".
• Aggiungi un record CNAME per reindirizzare tutti i sottodomini di "googleapis.com" (ad es. www.googleapis.com) a "googleapis.com".

4. Apri Cloud Shell nella visualizzazione dell'editor, se non è già aperta. Apri il file dns.tf nella cartella terraform-build. Aggiungi il seguente codice al file.

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. Passa al terminale Cloud Shell e assicurati di trovarti nella cartella terraform-build. Poi esegui terraform plan,che mostra gli elementi che verranno aggiunti.
   Poi esegui terraform apply e digita yes per creare la voce DNS privata.
6. Dovresti visualizzare una configurazione con un record A e un record CNAME come questo

7. Successivamente, verifichiamo la connettività con queste modifiche su monitor-vm

8. Attività 7: Verifica la connettività dell'endpoint tramite l'indirizzo IP

Connettiamoci utilizzando l'endpoint privato per connetterci a Gemini.

Nota:non sono necessarie configurazioni manuali sulla VM. Utilizziamo monitor-vm

1. Vai all'istanza VM monitor-vm. Seleziona SSH e accedi alla VM tramite SSH
2. Controlla il percorso di connettività a us-east1-aiplatform.googleapis.com utilizzando il comando ping. Verrà eseguito il ping dell'indirizzo IP nel DNS privato, record A per googleapis. Questo IP è un endpoint PSC e i ping non andranno a buon fine.

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

3. Controlla il percorso di connettività a us-east1-aiplatform.googleapis.com utilizzando il comando dig. Deve essere l'indirizzo IP dell'endpoint PSC (10.10.100.250).

dig us-east1-aiplatform.googleapis.com

4. Al termine, puoi chiudere la sessione SSH monitor-vm.

Stiamo passando a **cli-vm**

5. Vai all'istanza VM cli-vm. Seleziona SSH e accedi alla VM tramite SSH
6. Ora possiamo eseguire un dump TCP sulla cli-vm. Dobbiamo aprire due sessioni SSH nella stessa VM. Una sessione eseguirà il comando tcpdump, l'altra utilizzerà la CLI di Gemini.
7. Digita il seguente comando per visualizzare la connettività in un tcpdump

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

8. Ora accedi alla sessione successiva tramite SSH su cli-vm
9. Vai alla cartella antigravitycli cd antigravitycli
10. Attiva Antigravity CLI digitando agy
11. Poni la seguente domanda: what color is the sky? per generare una chiamata all'API Gemini

12. Premi Invio per eseguire il comando e visualizzare il risultato.
13. Torna alla prima sessione su cli-vm. Dovresti vedere il risultato di tcpdump. Noterai che l'indirizzo IP della VM utilizza l'indirizzo IP dell'endpoint PSC per connettersi all'API Gemini

Chiudi tutte le sessioni SSH alle istanze VM

9. Elimina

1. Vai a Cloud Shell, assicurati di trovarti nella directory terraform-build cd terraform-build ed esegui il seguente comando terraform destroy e digita yes tutte le risorse che hai creato nel tuo progetto con Terraform verranno rimosse.

10. Complimenti

Congratulazioni, la connessione alla CLI Antigravity è stata eseguita correttamente utilizzando sia l'indirizzo API pubblico sia privatamente l'endpoint Private Service Connect per le API di Google. Questa funzionalità può estendere la connettività API privata al tuo ambiente on-premise/altro cloud connesso tramite (Interconnect, Cross-Cloud Interconnect e VPC).

Prossimi passi/Scopri di più

Per saperne di più, consulta la documentazione di Antigravity CLI.

Segui il prossimo lab

Continua la Quest con Google Cloud e dai un'occhiata a questi altri lab Google Cloud:

• Networking Fundamentals in Google Cloud
• Generative AI Explorer - Vertex AI
• Tour di Cloud Networking