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

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

1. Обзор

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

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

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

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

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

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

Рисунок1.

2. Настройка облачных сервисов Google

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

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

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

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

Запустить Cloud Shell

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

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

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

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

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 и тестирование

Перейдите к экземплярам виртуальных машин. Выберите виртуальную машину, имя которой начинается с 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

Перезагрузить Баш

source ~/.bashrc

Теперь давайте пройдём аутентификацию. Выполните следующую команду в виртуальной машине и нажмите y при появлении запроса.

gcloud auth application-default login

Затем скопируйте URL-адрес, начинающийся с https://, откройте новую вкладку в окне браузера вашей лаборатории и вставьте URL-адрес. Примите приглашения.
Когда вы увидите следующее, выберите копию, вернитесь в сеанс vm 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

Вы должны увидеть что-то похожее (адрес будет другим). Обратите внимание, что путь проложен через публичные IP-адреса, поскольку 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

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

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

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

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

Чтобы обеспечить приватное подключение к нашей конечной точке API Vertex, мы создадим приватную конечную точку подключения к сервисам для 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 . Добавьте в файл следующий код.

Терраформировать 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 Это покажет, что будут добавлены два элемента.
затем запустите terraform apply и введите yes , чтобы создать конечную точку IP и PSC Google API.
Проверить существование конечной точки

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

gcloud compute forwarding-rules describe pscgemini --global

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

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

Перейдите в раздел Сетевые службы и выберите Cloud DNS.
В разделе «Зоны» вы увидите автоматически созданную зону для Private Service Connect для API Google с типом зоны «Каталог сервисов». Её можно использовать для подключения к конечной точке 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. Добавьте в файл следующий код.

Терраформ 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 Instance monitor-vm" . Выберите 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-запись для PSC Google API с помощью 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-дамп на cli-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 CLI, введя gemini
Задайте следующий вопрос: какого цвета небо, чтобы сгенерировать вызов API Gemini

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

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

9. Уборка

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

10. Поздравления

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

Дальнейшие шаги / Узнать больше

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

Возьмите вашу следующую лабораторную работу

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