Эта страница переведена с помощью Cloud Translation API.

Gemini CLI на GCE с конечной точкой Private Service Connect

1. Обзор

Вы можете использовать Gemini CLI как в локальной, так и в виртуальной среде. Gemini CLI — это агент искусственного интеллекта с открытым исходным кодом, который переносит возможности Gemini непосредственно в ваш терминал. С точки зрения сети, при использовании Gemini CLI он будет обращаться к API Gemini через общедоступный IP-адрес API.

Что произойдет, если вы захотите использовать Gemini CLI на машине Google Compute Engine, но при этом хотите подключиться к API через приватный интерфейс? В этом руководстве вы узнаете, как настроить конечную точку Private Service Connect для подключения к API Google, чтобы направлять трафик на указанный вами внутренний IP-адрес.

Конфигурации будут представлять собой комбинацию Terraform, gcloud и консоли.

В этой лабораторной работе вы научитесь выполнять следующее задание:

Настройка экземпляра виртуальной машины и облачного NAT.
Установите Gemini CLI и выполните аутентификацию.
Настройте конечную точку Private Service Connect для подключения к Googleapis.
Проверьте путь подключения к *.googleais
Настройка записей DNS вручную

В этой лабораторной работе вы создадите следующий узор.

Рисунок 1.

2. Настройка сервисов Google Cloud

Настройка среды для самостоятельного обучения

Войдите в консоль Google Cloud и создайте новый проект или используйте существующий. Если у вас еще нет учетной записи Gmail или Google Workspace, вам необходимо ее создать .

Название проекта — это отображаемое имя участников данного проекта. Это строка символов, не используемая API Google. Вы всегда можете его изменить.
Идентификатор проекта уникален для всех проектов Google Cloud и является неизменяемым (его нельзя изменить после установки). Консоль Cloud автоматически генерирует уникальную строку; обычно вам неважно, какая она. В большинстве практических заданий вам потребуется указать идентификатор вашего проекта (обычно обозначается как PROJECT_ID ). Если сгенерированный идентификатор вас не устраивает, вы можете сгенерировать другой случайный идентификатор. В качестве альтернативы вы можете попробовать свой собственный и посмотреть, доступен ли он. После этого шага его нельзя изменить, и он сохраняется на протяжении всего проекта.
К вашему сведению, существует третье значение — номер проекта , которое используется некоторыми API. Подробнее обо всех трех значениях можно узнать в документации .

Далее вам потребуется включить оплату в консоли Cloud для использования ресурсов/API Cloud. Выполнение этого практического задания не потребует больших затрат, если вообще потребует. Чтобы отключить ресурсы и избежать дополнительных расходов после завершения этого урока, вы можете удалить созданные ресурсы или удалить проект. Новые пользователи Google Cloud имеют право на бесплатную пробную версию стоимостью 300 долларов США .

Запустить Cloud Shell

Хотя Google Cloud можно управлять удаленно с ноутбука, в этом практическом занятии вы будете использовать Google Cloud Shell — среду командной строки, работающую в облаке.

В консоли Google Cloud нажмите на значок Cloud Shell на панели инструментов в правом верхнем углу:

Подготовка и подключение к среде займут всего несколько минут. После завершения вы должны увидеть примерно следующее:

Эта виртуальная машина содержит все необходимые инструменты разработки. Она предоставляет постоянный домашний каталог объемом 5 ГБ и работает в облаке Google, что значительно повышает производительность сети и аутентификацию. Вся работа в этом практическом задании может выполняться в браузере. Вам не нужно ничего устанавливать.

3. Задание 1. Настройка среды с помощью Terraform.

Мы создадим пользовательскую VPC с правилами брандмауэра и подсетью. Откройте консоль облака и выберите проект, который будете использовать.

Откройте Cloud Shell, расположенный в верхней части консоли справа, убедитесь, что в Cloud Shell отображается правильный идентификатор проекта , и подтвердите все запросы на предоставление доступа.
Создайте папку с именем 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 на фактический идентификатор вашего проекта в кавычках.

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"`
*Создайте VPC с именем python-net.*	`resource` `"google_compute_network"` `"default"`
*Добавить подсеть*	`resource` `"google_compute_subnetwork"` `"default"`
*Добавьте два правила брандмауэра.*	`resource` `"google_compute_firewall"` `"allow_icmp"resource` `"google_compute_firewall"` `"allow_ssh"`

Скопируйте и вставьте следующий текст в основной файл .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. Создание NAT-шлюза и виртуальных машин с помощью Terraform.

Нам необходимо разрешить исходящий внешний доступ к интернету, поэтому давайте создадим шлюз 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-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 для проведения тестирования в дальнейшем. P.S. Замените 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

Далее скопируйте URL-адрес, который начинается с https://, откройте новую вкладку в окне браузера вашей лаборатории и вставьте URL-адрес. Подтвердите запросы.
Когда вы увидите следующее поле «Выберите и скопируйте», вернитесь в сессию vm cli-vm и в поле «Введите код авторизации» вставьте скопированный код и нажмите Enter для аутентификации.

Теперь давайте установим Gemini CLI и выполним команду.

sudo npm install -g @google/gemini-cli

После завершения введите gemini , чтобы запустить интерфейс, выберите предпочитаемую тему и в разделе «Выберите способ аутентификации » выберите Vertex AI

После аутентификации вы сможете начать использовать Gemini CLI.

Отслеживание маршрута трафика к Gemini через виртуальную машину мониторинга.

Перейдите к экземплярам виртуальных машин. Выберите виртуальную машину, начинающуюся с monitor-vm . Выберите SSH.
После подключения к monitor-vm по SSH у вас должен появиться доступ.
Давайте воспользуемся командой dig , чтобы проверить путь подключения к API Gemini. Мы будем использовать us-east1-aiplatform.googleapis.com

dig us-east1-aiplatform.googleapis.com

Вы должны увидеть что-то похожее (адрес будет отличаться). Обратите внимание, что путь проходит через публичные IP-адреса, поскольку API является публичным API.

НЕ КОПИРОВАТЬ

; <<>> 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

Теперь давайте быстро проверим подключение к API Gemini с помощью ping . Эта команда выполнит 4 пинга к адресу us-east1-aiplatform.googleapis.com, поэтому мы получим ответ от публичного адреса API.

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

Мы вернёмся к тестированию этой виртуальной машины позже. Закройте SSH-сессию и продолжим.

6. Задание 4. Создайте конечную точку PSC для googleapis с помощью Terraform.

Для обеспечения частного подключения к нашей конечной точке API Vertex мы создадим конечную точку Private Service Connect для API Google. Это позволит нам использовать назначенный нами частный IP-адрес для маршрутизации трафика к необходимым нам API Google, в данном случае Vertex.

Откройте Cloud Shell в режиме редактора, если он еще не открыт. Мы собираемся создать следующее:

Создайте IP-адрес для конечной точки PSC 10.10.100.250 ( resource "google_compute_global_address" "default")
Создайте конечную точку PSC для API Google ( resource "google_compute_global_forwarding_rule" "default")

Откройте файл psc.tf в папке terraform-build . Добавьте в него следующий код.

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 , чтобы создать конечные точки Google API для IP-адреса и PSC.
Проверьте существование конечной точки.

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

gcloud compute forwarding-rules describe pscgemini --global

7. Задание 5. Создание записи DNS вручную для googleapis с помощью Terraform.

Вы можете создать запись DNS вручную, указывающую на конечную точку PSC, используя частный DNS. Это повлияет на все сети, которые вы к ней назначите.

Перейдите в раздел «Сетевые службы» и выберите «Облачный DNS».
В разделе «Зоны» вы должны увидеть автоматически созданную зону для Private Service Connect for Google APIs с типом зоны «каталог служб». Ее можно использовать для подключения к конечной точке PSC в формате ** SERVICE-ENDPOINT **. p.googleapis.com Пример: aiplatform-pscgemini.p.googleapis.com
В данном случае нам нужно вручную создать частную DNS-запись. Конфигурация будет следующей:

Создайте частную DNS-зону с именем "googleapis-private" для "googleapis.com" и ограничьте ее доступом только для сети "python-net".
Добавьте запись типа A, чтобы сопоставить "googleapis.com" с IP-адресом "10.10.100.250".
Добавьте запись CNAME для перенаправления всех поддоменов "googleapis.com" (например, www.googleapis.com) на "googleapis.com".

Откройте Cloud Shell в режиме редактора, если он еще не открыт. Откройте файл dns.tf в папке terraform-build. Добавьте в файл следующий код.

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, используя частную конечную точку.

Перейдите в меню « Монитор экземпляра виртуальной машины» — «Виртуальная машина» . Выберите SSH и подключитесь к виртуальной машине по SSH.
Проверьте путь подключения к us-east1-aiplatform.googleapis.com с помощью команды ping . Эта команда отправит ping на IP-адрес в частной DNS-записи A для googleapis. Этот IP-адрес является конечной точкой PSC, и ваши ping-запросы будут неуспешными.

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

Проверьте путь подключения с помощью ping , используя автоматически созданную запись DNS для API Google PSC с адресом aiplatform-pscvertexgemini.p.googleapis.com . Эта запись указывает на IP-адрес конечной точки PSC, и ваши команды ping будут неуспешными.

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

Проверьте путь подключения к us-east1-aiplatform.googleapis.com с помощью команды dig . Это должен быть IP-адрес конечной точки PSC (10.10.100.250).

dig us-east1-aiplatform.googleapis.com

После завершения вы можете закрыть SSH-сессию monitor-vm .
Теперь мы можем выполнить дамп TCP-трафика на виртуальной машине с командной строкой . Для этого нам потребуется открыть две SSH-сессии к одной и той же виртуальной машине. В одной сессии будет выполняться команда tcpdump, в другой мы будем использовать Gemini CLI.
Подключитесь по SSH к первой сессии на виртуальной машине командной строки.
Введите следующую команду, чтобы увидеть состояние подключения в файле tcpdump.

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

Теперь подключитесь по SSH к следующей сессии на виртуальной машине командной строки.
Активируйте интерфейс командной строки Gemini, набрав команду gemini
Задайте следующий вопрос: какого цвета небо, чтобы сгенерировать вызов API Gemini.

Нажмите Enter , чтобы запустить программу и увидеть результат.
Вернитесь к первой сессии на виртуальной машине с командной строкой. Вы должны увидеть результат выполнения команды tcpdump. Вы заметите, что входящие и исходящие соединения, а также IP-адрес виртуальной машины использует IP-адрес конечной точки PSC для подключения к API Gemini.

Закройте все SSH-сессии с экземплярами виртуальных машин.

9. Уборка

Перейдите в Cloud Shell, убедитесь, что вы находитесь в каталоге terraform-build , перейдите cd terraform-build и выполните следующую команду: terraform destroy , затем введите yes Все ресурсы, созданные в вашем проекте с помощью Terraform, будут удалены.

10. Поздравляем!

Поздравляем, вы успешно подключились к Gemini CLI, используя как публичный API-адрес, так и частный API-интерфейс через конечную точку Private Service Connect для Google API. Эта функциональность позволяет расширить возможности подключения к частным API в вашей локальной/другой облачной среде, подключенной через (межоблачное соединение, межоблачное соединение и VPC).

Следующие шаги / Узнать больше

Вы можете узнать больше о сетевых технологиях Vertex AI и ознакомиться с репозиторием Gemini CLI.

Пройдите следующую лабораторную работу.

Продолжите свое знакомство с Google Cloud и ознакомьтесь с другими лабораториями Google Cloud: