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.
2. Google Cloud 服务设置
自定进度的环境设置
- 登录 Google Cloud 控制台，然后创建一个新项目或重复使用现有项目。如果您还没有 Gmail 或 Google Workspace 账号，则必须创建一个。
- 项目名称是此项目参与者的显示名称。它是 Google API 尚未使用的字符串。您可以随时对其进行更新。
- 项目 ID 在所有 Google Cloud 项目中是唯一的，并且是不可变的（一经设置便无法更改）。Cloud 控制台会自动生成一个唯一字符串；通常情况下，您无需关注该字符串。在大多数 Codelab 中，您都需要引用项目 ID（通常用
PROJECT_ID标识）。如果您不喜欢生成的 ID，可以再随机生成一个 ID。或者，您也可以尝试自己的项目 ID，看看是否可用。完成此步骤后便无法更改该 ID，并且此 ID 在项目期间会一直保留。 - 此外，还有第三个值，即部分 API 使用的项目编号，供您参考。如需详细了解所有这三个值，请参阅文档。
- 接下来，您需要在 Cloud 控制台中启用结算功能，以便使用 Cloud 资源/API。运行此 Codelab 应该不会产生太多的费用（如果有的话）。若要关闭资源以避免产生超出本教程范围的结算费用，您可以删除自己创建的资源或删除项目。Google Cloud 新用户符合参与 300 美元免费试用计划的条件。
启动 Cloud Shell
虽然可以通过笔记本电脑对 Google Cloud 进行远程操作，但在此 Codelab 中，您将使用 Google Cloud Shell，这是一个在云端运行的命令行环境。
在 Google Cloud 控制台 中，点击右上角工具栏中的 Cloud Shell 图标：
预配和连接到环境应该只需要片刻时间。完成后，您应该会看到如下内容：
这个虚拟机已加载了您需要的所有开发工具。它提供了一个持久的 5 GB 主目录，并且在 Google Cloud 中运行，大大增强了网络性能和身份验证功能。您在此 Codelab 中的所有工作都可以在浏览器中完成。您无需安装任何程序。
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 编辑器视图。选择编辑器，确保允许任何必要的提示，以便加载界面。
- 加载完成后，依次前往文件 > 打开文件夹，然后前往 /home/your-user-name/terraform-build 并选择确定以在编辑器中打开该文件夹。
- 选择 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 |
|
创建名为 python-net 的 VPC |
|
添加子网 |
|
添加两条防火墙规则 |
|
- 将以下内容复制并粘贴到 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 网关和虚拟机
我们需要授予出站外部互联网访问权限，因此我们来创建 Cloud NAT 网关并将其附加。
- 打开 Cloud Shell，前往 terraform-build 文件夹，然后创建以下文件（共三个文件）。我们稍后会修改这些内容。
touch nat-vm.tf psc.tf dns.tf
- 切换到 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
}
- 切换到 Cloud Shell 终端，确保您位于 terraform-build 文件夹中，然后运行
terraform plan，系统会显示将添加 4 个项目，然后运行terraform apply并输入yes以创建 NAT 网关和两个虚拟机。
5. 任务 3. 配置 CLI 虚拟机并进行测试
- 前往“虚拟机实例”。选择以 cli-vm 开头的虚拟机。选择 SSH。
- 通过 SSH 连接后，您应该可以访问虚拟机了。接下来，我们创建一个文件夹，以便在运行 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
- 现在，我们来验证一下。在虚拟机中运行以下命令，并在系统提示时按 y。
gcloud auth application-default login
- 接下来，复制以 https:// 开头的网址，在实验浏览器窗口中打开一个新标签页，然后粘贴该网址。接受提示。
- 看到以下内容后，选择“复制”，然后切换回虚拟机 cli-vm 会话，在 Enter authorization code:（输入授权代码：）提示处粘贴您复制的代码，然后按 Enter 键进行身份验证。
- 现在，我们来安装 Gemini CLI，运行以下命令
sudo npm install -g @google/gemini-cli
完成后，输入 gemini 以启动界面，选择您喜欢的主题，然后在选择身份验证方法下选择 Vertex AI
- 完成身份验证后，您就可以开始使用 Gemini CLI 了
通过监控虚拟机监控 Gemini 的流量路由
- 前往“虚拟机实例”。选择以 monitor-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。此命令将使用 4 个 ping 来测试 us-east1-aiplatform.googleapis.com，因此我们将收到来自该 API 公共地址的响应。
ping -c 4 us-east1-aiplatform.googleapis.com
- 稍后我们将回来测试此虚拟机。关闭 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 创建指向 PSC 端点的手动 DNS 条目。这会影响您为其分配的所有媒体文件。
- 前往“网络服务”，然后选择“Cloud DNS”。
- 在相应区域中，您应该会看到一个自动创建的 Private Service Connect 区域（适用于 Google API），其区域类型为 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。
- 前往虚拟机实例 monitor-vm。选择“SSH”，并通过 SSH 连接到虚拟机
- 使用
ping命令检查与 us-east1-aiplatform.googleapis.com 的连接路径。这将对专用 DNS 中 googleapis 的 A 记录中的 IP 地址执行 ping 操作。此 IP 是 PSC 端点，因此您的 ping 将失败。
ping -c 2 us-east1-aiplatform.googleapis.com
- 使用自动创建的 DNS 条目（适用于具有
aiplatform-pscvertexgemini.p.googleapis.com的 PSC Google API）通过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 转储。我们需要打开两个与同一虚拟机的 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 的结果。您会注意到，虚拟机的入站和出站流量以及 IP 地址正在使用 PSC 端点 IP 地址连接到 Gemini API
关闭与虚拟机实例的所有 SSH 会话
9. 清理
- 前往 Cloud Shell，确保您位于 terraform-build 目录
cd terraform-build中，然后运行以下命令terraform destroy并输入yes，这样一来，您在项目中通过 Terraform 创建的所有资源都将被移除。
10. 恭喜
恭喜！您已成功使用公共 API 地址和 Private Service Connect 端点（用于 Google API）以非公开方式连接到 Gemini CLI。此功能可将专用 API 连接扩展到通过（互连、Cross-Cloud Interconnect 和 VPC）连接的本地/其他云环境。
后续步骤/了解详情
您可以详细了解 Vertex AI 网络，并查看 Gemini CLI 代码库
参与下一项实验
继续探索 Google Cloud，并查看以下其他 Google Cloud 实验：