在 GCE 上通过 Private Service Connect 端点使用 Gemini CLI

1. 概览

您可以在本地环境和虚拟环境中使用 Gemini CLI。Gemini CLI 是一款开源 AI 智能体，可将 Gemini 的强大功能直接引入您的终端。从网络角度来看，当您使用 Gemini CLI 时，它将通过 API IP 地址（可公开访问）调用 Gemini API。

现在，如果您想在 Google Compute Engine 机器上使用 Gemini CLI，但想以私密方式连接到 API，该怎么办？在此 Codelab 中，您将了解如何为 Google API 配置 Private Service Connect 端点，以将流量路由到您指定的内部 IP 地址。

配置将是 Terraform、gcloud 和控制台的组合。

在本实验中，您将学习如何执行以下任务：

  • 设置虚拟机实例和 Cloud NAT
  • 安装 Gemini CLI 并进行身份验证
  • 配置 Private Service Connect 端点以连接到 Googleapis
  • 验证与 *.googleais 的连接路径
  • 配置手动 DNS 条目

在本实验中，您将创建以下模式。

图 1。

809ec92718405b07.png

2. Google Cloud 服务设置

自定进度的环境设置

  1. 登录 Google Cloud 控制台，然后创建一个新项目或重复使用现有项目。如果您还没有 Gmail 或 Google Workspace 账号，则必须创建一个。

fbef9caa1602edd0.png

a99b7ace416376c4.png

5e3ff691252acf41.png

  • 项目名称是此项目参与者的显示名称。它是 Google API 尚未使用的字符串。您可以随时对其进行更新。
  • 项目 ID 在所有 Google Cloud 项目中是唯一的，并且是不可变的（一经设置便无法更改）。Cloud 控制台会自动生成一个唯一字符串；通常情况下，您无需关注该字符串。在大多数 Codelab 中，您都需要引用项目 ID（通常用 PROJECT_ID 标识）。如果您不喜欢生成的 ID，可以再随机生成一个 ID。或者，您也可以尝试自己的项目 ID，看看是否可用。完成此步骤后便无法更改该 ID，并且此 ID 在项目期间会一直保留。
  • 此外，还有第三个值，即部分 API 使用的项目编号，供您参考。如需详细了解所有这三个值，请参阅文档。
  1. 接下来，您需要在 Cloud 控制台中启用结算功能，以便使用 Cloud 资源/API。运行此 Codelab 应该不会产生太多的费用（如果有的话）。若要关闭资源以避免产生超出本教程范围的结算费用，您可以删除自己创建的资源或删除项目。Google Cloud 新用户符合参与 300 美元免费试用计划的条件。

启动 Cloud Shell

虽然可以通过笔记本电脑对 Google Cloud 进行远程操作，但在此 Codelab 中，您将使用 Google Cloud Shell，这是一个在云端运行的命令行环境。

在 Google Cloud 控制台 中，点击右上角工具栏中的 Cloud Shell 图标：

55efc1aaa7a4d3ad.png

预配和连接到环境应该只需要片刻时间。完成后，您应该会看到如下内容：

7ffe5cbb04455448.png

这个虚拟机已加载了您需要的所有开发工具。它提供了一个持久的 5 GB 主目录，并且在 Google Cloud 中运行，大大增强了网络性能和身份验证功能。您在此 Codelab 中的所有工作都可以在浏览器中完成。您无需安装任何程序。

3. 任务 1. 使用 Terraform 设置环境

我们将创建一个具有防火墙规则和子网的自定义 VPC。打开 Cloud 控制台，然后选择要使用的项目。

  1. 打开 Cloud Shell（位于控制台右上角），确保在 Cloud Shell 中看到正确的 项目 ID，确认所有提示以允许访问。4261e776f64ea978.png
  2. 创建一个名为 terraform-build 的文件夹，然后移至该文件夹
mkdir terraform-build  && cd terraform-build
  1. 创建 main.tf 和 variable.tf 文件。
touch main.tf variable.tf
  1. 切换到 Cloud Shell 编辑器 视图。选择编辑器，确保允许所有必要的提示，以便加载界面。
  2. 加载后，依次前往 File > Open Folder ，然后前往 /home/your-user-name/terraform-build ，选择 Ok 以在编辑器中打开该文件夹。 78f5eb9f2f82f1b0.png
  3. 选择 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"
}
  1. 接下来，打开 main.tf 文件。我们将添加一些 Terraform 代码来执行各种操作，如下所述。

启用 API

resource "google_project_service" "default"

创建名为 python-net 的 VPC

resource "google_compute_network" "default"

添加子网

resource "google_compute_subnetwork" "default"

添加两条防火墙规则

resource "google_compute_firewall" "allow_icmp"resource "google_compute_firewall" "allow_ssh"

  1. 将以下内容复制并粘贴到 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"]
}
  1. 切换回 Cloud Shell 终端 ，确保您位于 terraform-build 目录中 cd terraform-build，然后运行以下命令

terraform init

初始化工作目录。此步骤会下载给定配置所需的提供商。

terraform plan

生成执行计划，显示 Terraform 将采取哪些操作来部署基础架构。

  1. 现在，如需创建资源，请运行 terraform apply 命令，然后输入 yes 以运行。

4. 任务 2. 使用 Terraform 创建 NAT 网关和虚拟机

我们需要授予出站外部互联网访问权限，因此让我们创建一个 Cloud NAT 网关并将其连接。

  1. 打开 Cloud Shell，前往 terraform-build 文件夹，然后创建以下文件（共三个文件）。我们稍后将对其进行修改。
touch nat-vm.tf psc.tf dns.tf
  1. 切换到 Cloud Shell 编辑器 视图，选择 nat-vm.tf 文件，然后添加以下 Terraform 代码。这将创建一个 NAT 网关和两个虚拟机。

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
}
  1. 切换到 Cloud Shell 终端，确保您位于 terraform-build 文件夹中，然后运行 terraform plan，这将显示将添加 4 个项，然后运行 terraform apply 并输入 yes 以创建 NAT 网关和两个虚拟机。

5. 任务 3. 配置 CLI 虚拟机并进行测试

  1. 前往虚拟机实例。选择以 cli-vm 开头的虚拟机。选择 SSH 。
  2. 通过 SSH 连接后，您应该有权访问虚拟机，让我们在运行 Gemini CLI 时创建一个文件夹
mkdir geminicli && cd geminicli
  1. 如需安装 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
  1. 让我们设置一些变量，这些变量将有助于使用 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
  1. 现在，让我们进行身份验证。在虚拟机中运行以下命令，并在出现提示时按 y 。
gcloud auth application-default login
  1. 接下来，复制以 https:// 开头的网址，在实验浏览器窗口中打开一个新标签页，然后粘贴该网址。接受提示。
  2. 看到以下内容时，选择“复制”，切换回虚拟机 cli-vm 会话，然后在输入授权代码： 中粘贴您复制的代码，然后按 Enter 进行身份验证。

c29615cdf9324209.png

  1. 现在，让我们安装 Gemini CLI，运行以下命令
sudo npm install -g @google/gemini-cli

完成后，输入 gemini 以启动界面，选择您喜欢的主题，然后在选择身份验证方法 下选择 Vertex AI

7fb8ea7fbf48cad9.png

a9f9a93ae8694e2f.png

  1. 通过身份验证后，您就可以开始使用 Gemini CLI 了

b13a934b6220c9af.png

通过监控虚拟机监控 Gemini 的流量路由

  1. 前往虚拟机实例。选择以 monitor-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    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
  1. 现在，让我们进行快速 ping 测试，看看是否可以连接到 Gemini API。此命令将使用 4 个 ping 来 ping us-east1-aiplatform.googleapis.com，因此我们将收到来自 API 公共地址的响应。
ping -c 4 us-east1-aiplatform.googleapis.com
  1. 我们稍后将返回来测试此虚拟机。关闭 SSH 会话，然后继续。

6. 任务 4. 使用 Terraform 为 Googleapis 创建 PSC 端点

如需启用与 Vertex API 端点的专用连接，我们将为 Google API 创建 Private Service Connect 端点。这样，我们就可以使用分配给我们的专用 IP 地址将流量路由到我们需要的 Google API（在本例中为 Vertex）。

  1. 如果 Cloud Shell 尚未打开，请在编辑器视图中打开它。我们将创建以下内容：
  • 为 PSC 端点创建 IP 10.10.100.250 (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 = ""
  }
  1. 切换到 Cloud Shell 终端，确保您位于 terraform-build 文件夹中。然后运行 terraform init，再运行 terraform plan，这将显示将添加 2 个项，
    然后运行 terraform apply 并输入 yes 以创建 IP 和 PSC Google APIs 端点。
  2. 验证端点是否存在
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-ENDPOINT.p.googleapis.com 格式连接到 PSC 端点。示例：aiplatform-pscgemini.p.googleapis.com
  3. 在本例中，我们希望手动创建专用 DNS 条目。配置如下
  • 为“googleapis.com”创建 名为“googleapis-private”的专用 DNS 区域，并将其限制为“python-net”网络。
  • 添加 A 记录，将“googleapis.com”映射到 IP 地址“10.10.100.250”。
  • 添加 CNAME 记录，将“googleapis.com”的所有子网域（例如 www.googleapis.com）重定向到“googleapis.com”。
  1. 如果 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."]  
}
  1. 切换到 Cloud Shell 终端，确保您位于 terraform-build 文件夹中。然后运行 terraform plan，这将显示将添加哪些项，
    然后运行 terraform apply 并输入 yes 以创建专用 DNS 条目。
  2. 您应该会看到如下所示的设置，其中包含 A 记录和 CNAME

a33a4d3d629c54dd.png

  1. 接下来，我们验证 monitor-vm 上这些更改的连接性

8. 任务 7. 通过 IP 地址验证端点连接

让我们使用专用端点连接到 Gemini。

  1. 前往虚拟机实例 monitor-vm 。选择 SSH，然后通过 SSH 连接到虚拟机
  2. 使用 ping 命令检查与 us-east1-aiplatform.googleapis.com 的连接路径。这将 ping 专用 DNS 中的 IP 地址，即 googleapis 的 A 记录。此 IP 是 PSC 端点，您的 ping 将失败。
ping -c 2 us-east1-aiplatform.googleapis.com
  1. 使用 aiplatform-pscvertexgemini.p.googleapis.com 检查与 ping 的连接路径，其中使用为 PSC Google API 自动创建的 DNS 条目。这指向 PSC 端点的 IP 地址，您的 ping 将失败。
ping -c 2 aiplatform-pscgemini.p.googleapis.com
  1. 使用 dig 命令检查与 us-east1-aiplatform.googleapis.com 的连接路径。这应该是 PSC 端点的 IP 地址 (10.10.100.250)。
dig us-east1-aiplatform.googleapis.com

bcb26844349ee775.png

  1. 完成后，您可以关闭 monitor-vm SSH 会话。
  2. 现在，我们可以在 cli-vm 上运行 TCP 转储。我们需要打开与同一虚拟机的两个 SSH 会话。一个会话将运行 tcpdump 命令，另一个会话将使用 Gemini CLI。
  3. 通过 SSH 连接到 cli-vm 上的第一个会话
  4. 输入以下命令，以在 tcpdump 中查看连接
sudo tcpdump -i any port 53 -n or host us-east1-aiplatform.googleapis.com
  1. 现在，通过 SSH 连接到 cli-vm 上的下一个会话
  2. 输入 gemini 以激活 Gemini CLI
  3. 提出以下问题：天空是什么颜色，以生成对 Gemini API 的调用

d6189c2adef69eaf.png

  1. 按 Enter 运行并查看结果。
  2. 切换回 cli-vm 上的第一个会话。您应该会看到 tcpdump 的结果。您会注意到，虚拟机的 IP 地址正在使用 PSC 端点 IP 地址连接到 gemini API

ce99170d9f9c7858.png

关闭与虚拟机实例的所有 SSH 会话

9. 清理

  1. 前往 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 实验：