搭配 Private Service Connect 端點在 GCE 機器上使用 Antigravity CLI

1. 總覽

您可以在本機和虛擬環境中使用 Antigravity CLI。Antigravity 可讓您直接在終端機使用 Gemini 的強大功能。從網路角度來看，使用 Antigravity CLI 時，系統會透過可公開存取的 API IP 位址呼叫 Gemini API。

現在，如果您想在 Google Compute Engine 電腦上使用 Antigravity CLI，但想以私密方式連線至 API，該怎麼做？在本程式碼研究室中，您將瞭解如何設定 Google API 的 Private Service Connect 端點，將流量路由至您指定的內部 IP 位址。

設定會結合 Terraform、gcloud 和控制台。

在本實驗室中，您將瞭解如何執行下列工作：

• 設定 VM 執行個體和 Cloud NAT
• 安裝 Antigravity CLI 並完成驗證
• 設定 Private Service Connect 端點，連線至 Googleapis
• 驗證 *.googleapis 的連線路徑
• 設定手動 DNS 項目

在本實驗室中，您將建立下列模式。

圖 1

2. 設定 Google Cloud 服務

自修實驗室環境設定

1. 登入 Google Cloud 控制台，然後建立新專案或重複使用現有專案。如果沒有 Gmail 或 Google Workspace 帳戶，請先建立帳戶。

• 專案名稱是這個專案參與者的顯示名稱。這是 Google API 未使用的字元字串。你隨時可以更新。
• 專案 ID 在所有 Google Cloud 專案中都是不重複的，而且設定後即無法變更。Cloud 控制台會自動產生專屬字串，通常您不需要在意該字串為何。在大多數程式碼研究室中，您需要參照專案 ID (通常標示為 PROJECT_ID)。如果您不喜歡產生的 ID，可以產生另一個隨機 ID。你也可以嘗試使用自己的名稱，看看是否可用。完成這個步驟後就無法變更，且專案期間會維持不變。
• 請注意，有些 API 會使用第三個值，也就是「專案編號」。如要進一步瞭解這三種值，請參閱說明文件。

注意：專案 ID 在全域中是唯一的，選定後就無法再供他人使用。您是該 ID 的唯一使用者。即使專案已刪除，ID 也無法再次使用

注意：如果使用 Gmail 帳戶，可以將預設位置設為「沒有機構」。如果你使用 Google Workspace 帳戶，請選擇適合貴機構的位置。

2. 接著，您需要在 Cloud 控制台中啟用帳單，才能使用 Cloud 資源/API。完成這個程式碼研究室的費用不高，甚至可能完全免費。如要關閉資源，避免在本教學課程結束後繼續產生費用，請刪除您建立的資源或專案。Google Cloud 新使用者可參加價值$300 美元的免費試用計畫。

啟動 Cloud Shell

雖然可以透過筆電遠端操作 Google Cloud，但在本程式碼研究室中，您將使用 Google Cloud Shell，這是可在雲端執行的指令列環境。

在 Google Cloud 控制台中，點選右上角工具列的 Cloud Shell 圖示：

佈建並連線至環境的作業需要一些時間才能完成。完成後，您應該會看到如下的內容：

這部虛擬機器搭載各種您需要的開發工具，並提供永久的 5GB 主目錄，而且可在 Google Cloud 運作，大幅提升網路效能並強化驗證功能。您可以在瀏覽器中完成本程式碼研究室的所有作業。您不需要安裝任何軟體。

3. 使用 Terraform 設定環境

我們會建立含有防火牆規則和子網路的自訂虛擬私有雲。開啟 Cloud 控制台，然後選取要使用的專案。

1. 開啟控制台右上方的 Cloud Shell，確認 Cloud Shell 中顯示正確的專案 ID，並確認允許存取的任何提示。
2. 建立名為 terraform-build 的資料夾，然後移至該資料夾

mkdir terraform-build && cd terraform-build 

3. 建立 main.tf 和 variable.tf 檔案。

touch main.tf variable.tf 

4. 切換至 Cloud Shell 編輯器檢視畫面。選取「編輯器」，並允許所有必要提示，確保介面可以載入。
5. 載入後，依序前往「File」>「Open Folder」，然後前往「/home/your-user-name/terraform-build」，並選取「Ok」，在編輯器中開啟資料夾。
6. 選取 variable.tf 檔案，然後新增下列內容。將 your-project-id-here 文字替換為實際專案 ID (以半形引號括住)

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

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

7. 接著開啟 main.tf 檔案。我們將新增一些 Terraform 程式碼，執行下列各種動作。

啟用 API	resource "google_project_service" "default"
建立名為 python-net 的虛擬私有雲	resource "google_compute_network" "default"
新增子網路	resource "google_compute_subnetwork" "default"
新增兩項防火牆規則	resource "google_compute_firewall" "allow_icmp"resource "google_compute_firewall" "allow_ssh"

8. 複製下列程式碼並貼到 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. 切換回 Cloud Shell 終端機，確認您位於 terraform-build 目錄 cd terraform-build，然後執行下列指令：

terraform init

初始化工作目錄。這個步驟會下載指定設定所需的供應商。

terraform plan

產生執行計畫，顯示 Terraform 將採取哪些動作來部署基礎架構。

10. 現在請執行 terraform apply 指令，然後輸入 yes 來建立資源。

驗證設定：檢查環境是否符合下列條件：

• 名為 antigravity-vpc-net 的 VPC
• 子網路
• firewall-rules

4. 工作 2：使用 Terraform 建立 NAT 閘道和 VM

我們需要授予連出網際網路的外部存取權，因此請建立並附加 Cloud NAT 閘道。

1. 開啟 Cloud Shell，前往 terraform-build 資料夾，然後建立下列檔案 (共三個檔案)。我們稍後會編輯這些內容。

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

2. 切換至 Cloud Shell 編輯器檢視畫面，選取 nat-vm.tf 檔案，然後新增下列 Terraform 程式碼。系統會建立 NAT 閘道和兩部 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. 切換至 Cloud Shell 終端機，確認您位於 terraform-build 資料夾中，然後執行 terraform plan，這會顯示將新增 4 個項目，接著執行 terraform apply 並輸入 yes，建立 NAT 閘道和兩個 VM。

驗證設定：檢查環境是否符合下列條件：

1 個 NAT 閘道

1 個 Cloud Router

名為「cli-vm」的 VM

名為「monitor-vm」的 VM

5. 工作 3：設定 CLI VM 並進行測試

1. 前往 VM 執行個體。選取以 cli-vm 開頭的 VM。選擇「SSH」SSH。
2. 透過 SSH 連線後，您應該就能存取 VM，接著建立資料夾，以便執行 Gemini CLI

mkdir antigravitycli && cd antigravitycli

3. 如要安裝 Antigravity CLI，請使用下列指令：

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

查看版本

agy --version

4. 請登入並驗證，以便稍後進行測試。

agy

5. 選取選項 1 Google OAuth。現在進行驗證。
6. 接著複製開頭為 https:// 的網址，在實驗室瀏覽器視窗中開啟新分頁並貼上網址。接受提示。

7. 看到下列訊息時，請選取複製到剪貼簿，然後切換回 VM cli-vm 工作階段，在「Enter authorization code:」中貼上複製的授權碼，然後按下 Enter 鍵進行驗證。

8. 切換回 VM cli-vm 工作階段，在「Enter authorization code:」貼上您複製的授權碼，然後按下 Enter 鍵進行驗證。

9. 畫面上會顯示可自訂及接受協議的選項，並引導你前往住家目錄。選取相關選項並完成設定。

10. 完成後，即可開始使用 Antigravity CLI

注意：你可以將提示問題修改為其他內容。

透過監控 VM 監控 Gemini 的流量路徑

1. 前往 VM 執行個體。選取以 monitor-vm 開頭的 VM。選擇 SSH。
2. 透過 SSH 連線至 monitor-vm 後，您應該可以存取
3. 我們將使用 dig 指令測試 Gemini API 的連線路徑。我們將使用 us-east1-aiplatform.googleapis.com

dig us-east1-aiplatform.googleapis.com

畫面應會顯示類似內容 (地址會有所不同)。注意：由於 API 是公用 API，路徑會經過公開 IP 位址。

請勿複製

; <<>> 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. 現在來快速ping測試，看看是否能連線至 Gemini API。這項指令會使用 4 個 Ping 傳送至 us-east1-aiplatform.googleapis.com，因此我們會收到 API 公開位址的回應。

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

5. 我們稍後會回來測試這個 VM。關閉 SSH 工作階段，然後繼續。

6. 工作 4：使用 Terraform 建立 googleapis 的 PSC 端點

如要啟用與 Vertex API 端點的私人連線，請為 Google API 建立 Private Service Connect 端點。這樣一來，我們就能使用指派的私人 IP 位址，將流量轉送至所需的 Google API (在本例中為 Vertex)。

1. 如果尚未開啟 Cloud Shell，請在編輯器檢視畫面中開啟。我們要建立下列項目：

• 為 PSC 端點 10.10.100.250 建立 IP (resource "google_compute_global_address" "default")
• 建立 Google API 的 PSC 端點 (resource "google_compute_global_forwarding_rule" "default")

開啟 terraform-build 資料夾中的 psc.tf 檔案。在檔案中新增下列程式碼。

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. 切換到 Cloud Shell 終端機，確認您位於 terraform-build 資料夾。然後執行 terraform init 然後執行 terraform plan，這會顯示將新增 2 個項目，
   然後執行 terraform apply 並輸入 yes，即可建立 IP 和 PSC Google API 端點。
3. 確認端點是否存在

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

gcloud compute forwarding-rules describe pscgemini --global

7. 工作 5：使用 Terraform 為 googleapis 建立手動 DNS 項目

您可以使用私人 DNS 建立手動 DNS 項目，指向 PSC 端點。這會影響您指派給該廣告活動的所有聯播網。

1. 前往「網路服務」，然後選取「Cloud DNS」。
2. 在區域中，您應該會看到系統自動為 Google API 的 Private Service Connect 建立區域，且區域類型為 Service Directory。可用於以 **SERVICE-ENDPOINT.p.googleapis.com 格式連線至 PSC 端點。範例：aiplatform-pscgemini.p.googleapis.com
3. 在本例中，我們要手動建立私人 DNS 項目。設定如下所示

• 為「googleapis.com」建立名為「googleapis-private」的私人 DNS 區域，並將其限制在「antigravity-vpc-net」網路中。
• 新增 A 記錄，將「googleapis.com」對應至 IP 位址「10.10.100.250」。
• 新增 CNAME 記錄，將「googleapis.com」的所有子網域 (例如 www.googleapis.com) 重新導向至「googleapis.com」。

4. 如果尚未開啟 Cloud Shell，請在編輯器檢視畫面中開啟。開啟 terraform-build 資料夾中的 dns.tf 檔案。在檔案中新增下列程式碼。

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. 切換到 Cloud Shell 終端機，確認您位於 terraform-build 資料夾。然後執行 terraform plan，這會顯示要新增的項目，
   接著執行 terraform apply，然後輸入 yes 建立私人 DNS 項目。
6. 您應該會看到設定，其中包含 A 記錄和 CNAME，如下所示：

7. 接著，我們在 monitor-vm 上驗證連線，確認這些變更是否生效。

8. 工作 7：透過 IP 位址驗證端點連線

讓我們使用私人端點連線至 Gemini。

注意：您不必在 VM 上手動設定任何項目。我們使用monitor-vm

1. 前往 VM 執行個體 monitor-vm。選取「SSH」，透過 SSH 連線至 VM
2. 使用 ping 指令檢查 us-east1-aiplatform.googleapis.com 的連線路徑。這會對 googleapis 的私人 DNS 中的 IP 位址 (A 記錄) 執行 Ping 作業。這個 IP 是 PSC 端點，因此 Ping 會失敗。

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

3. 使用 dig 指令檢查 us-east1-aiplatform.googleapis.com 的連線路徑。這應該是 PSC 端點的 IP 位址 (10.10.100.250)。

dig us-east1-aiplatform.googleapis.com

4. 完成後，即可關閉 monitor-vm SSH 工作階段。

我們將改用 **cli-vm**

5. 前往 VM 執行個體 cli-vm。選取「SSH」，透過 SSH 連線至 VM
6. 現在可以在 cli-vm 上執行 TCP 傾印。我們需要開啟兩個與相同 VM 的 SSH 工作階段。一個工作階段會執行 tcpdump 指令，另一個工作階段則會使用 Gemini CLI。
7. 輸入下列指令，查看 tcpdump 中的連線

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

8. 現在請透過 SSH 連線至 cli-vm 的下一個工作階段。
9. 前往 antigravitycli 資料夾 cd antigravitycli
10. 輸入 agy 即可啟動 Antigravity CLI
11. 提出下列問題，what color is the sky?生成對 Gemini API 的呼叫

12. 按下 Enter 鍵執行並查看結果。
13. 切換回 cli-vm 的第一個工作階段。您應該會看到 tcpdump 的結果。您會發現 VM 的輸入和輸出，以及 IP 位址，都使用 PSC 端點 IP 位址連線至 Gemini API

關閉所有 VM 執行個體的 SSH 工作階段

9. 清除

1. 前往 Cloud Shell，確認您位於 terraform-build 目錄 cd terraform-build，然後執行下列指令 terraform destroy 並輸入 yes，即可移除您在專案中以 Terraform 建立的所有資源。

10. 恭喜

恭喜！您已成功使用公用 API 位址，以及透過 Google API 適用的 Private Service Connect 端點，以私密方式連線至 Antigravity CLI。這項功能可將非公開 API 連線能力擴展至地端部署/其他雲端環境，這些環境透過 (互連網路、Cross-Cloud Interconnect 和虛擬私有雲) 連線。

後續步驟/瞭解詳情

詳情請參閱 Antigravity CLI 說明文件

挑戰下一個實驗室

繼續完成 Google Cloud 任務，或查看下列其他 Google Cloud 實驗室：

• Google Cloud 網路基礎知識
• 探索生成式 AI - Vertex AI
• Cloud 網路導覽