本頁面由 Cloud Translation API 翻譯而成。

透過 Private Service Connect 端點在 GCE 上使用 Gemini CLI

1. 總覽

您可以在本機和虛擬環境中使用 Gemini CLI。Gemini CLI 是一款開放原始碼 AI 代理程式，可直接在終端機使用 Gemini 的強大功能。從網路的角度來看，使用 Gemini CLI 時，系統會透過可公開存取的 API IP 位址呼叫 Gemini API。

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

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

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

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

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

圖 1。

2. 設定 Google Cloud 服務

自行設定環境

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

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

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

啟動 Cloud Shell

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

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

佈建並連線至環境的作業只需幾分鐘即可完成。完成後，您應該會看到如下的內容：

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

3. 工作 1：使用 Terraform 設定環境

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

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

mkdir terraform-build  && cd terraform-build

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

touch main.tf variable.tf

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

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

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

接著開啟 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"`

複製下列程式碼並貼到 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"]
}

切換回 Cloud Shell 終端機，確認您位於 terraform-build 目錄 cd terraform-build，然後執行下列指令

terraform init

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

terraform plan

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

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

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

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

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

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

切換至 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
}

切換至 Cloud Shell 終端機，確認您位於 terraform-build 資料夾中，然後執行 terraform plan，這會顯示將新增 4 個項目，接著執行 terraform apply 並輸入 yes，建立 NAT 閘道和兩個 VM。

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

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

mkdir geminicli && cd geminicli

如要安裝 Gemini CLI，必須先安裝 Node.js。使用下列指令安裝 Node.js

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

執行指令碼

sudo -E bash nodesource_setup.sh

安裝 Node.js

sudo apt-get install -y nodejs

讓我們設定一些變數，稍後將使用 Vertex AI 驗證選項進行驗證，以利進行測試。附註：請將 YOUR_PROJECT_ID 替換為實際的 project ID

cat <<EOF >> ~/.bashrc 

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

重新載入 Bash

source ~/.bashrc

現在進行驗證。在 VM 中執行下列指令，並在系統提示時按下 y。

gcloud auth application-default login

接著複製開頭為 https:// 的網址，在實驗室瀏覽器視窗中開啟新分頁並貼上網址。接受提示。
看到下列選取複製畫面時，請切換回 VM cli-vm 工作階段，然後在「Enter authorization code:」中貼上複製的程式碼，並按下 Enter 鍵進行驗證。

現在安裝 Gemini CLI，執行下列指令：

sudo npm install -g @google/gemini-cli

完成後，請輸入 gemini 啟動介面，選取偏好的主題，然後在「Select Auth method」(選取驗證方法) 下方選擇 Vertex AI。

完成驗證後，即可開始使用 Gemini CLI

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

前往 VM 執行個體。選取以 monitor-vm 開頭的 VM。選擇 SSH。
透過 SSH 連線至 monitor-vm 後，您應該就能存取
請使用 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    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

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

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

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

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

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

如果尚未開啟 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 = ""
  }

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

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

gcloud compute forwarding-rules describe pscgemini --global

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

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

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

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

如果尚未開啟 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."]  
}

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

接著，我們在 monitor-vm 上驗證這些變更的連線

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

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

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

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

使用 aiplatform-pscvertexgemini.p.googleapis.com 為 PSC Google API 自動建立的 DNS 項目，以 ping 檢查連線路徑。這會指向 PSC 端點的 IP 位址，因此您無法成功執行 Ping。

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

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

dig us-east1-aiplatform.googleapis.com

完成後，即可關閉 monitor-vm SSH 工作階段。
現在可以在 cli-vm 上執行 TCP 傾印。我們需要開啟兩個與相同 VM 的 SSH 工作階段。一個工作階段會執行 tcpdump 指令，另一個工作階段則會使用 Gemini CLI。
透過 SSH 連線至 cli-vm 的第一個工作階段
輸入下列指令，查看 tcpdump 中的連線

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

現在透過 SSH 連線至 cli-vm 的下一個工作階段
輸入 gemini 啟動 Gemini CLI
提出「天空是什麼顏色？」這個問題，生成對 Gemini API 的呼叫

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

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

9. 清除

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

10. 恭喜

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

後續步驟/瞭解詳情

您可以進一步瞭解 Vertex AI 網路，並查看 Gemini CLI 存放區

挑戰下一個研究室

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