1. Übersicht
Sie können die Gemini-Befehlszeile sowohl in Ihrer lokalen als auch in Ihrer virtuellen Umgebung verwenden. Gemini CLI ist ein Open-Source-KI-Agent, der die Leistungsfähigkeit von Gemini direkt in Ihr Terminal bringt. Aus Netzwerksicht wird bei der Verwendung der Gemini CLI ein Aufruf an die Gemini API über die öffentlich zugängliche API-IP-Adresse gesendet.
Was passiert, wenn Sie die Gemini CLI auf einer Google Compute Engine-Maschine verwenden, aber eine private Verbindung zur API herstellen möchten? In diesem Codelab erfahren Sie, wie Sie einen Private Service Connect-Endpunkt für Google APIs konfigurieren, um den Traffic an eine von Ihnen angegebene interne IP-Adresse weiterzuleiten.
Die Konfigurationen sind eine Kombination aus Terraform, gcloud und Console.
In diesem Lab lernen Sie Folgendes:
- VM-Instanz und Cloud NAT einrichten
- Gemini CLI installieren und authentifizieren
- Private Service Connect-Endpunkt für die Verbindung zu Googleapis konfigurieren
- Verbindungspfad zu *.googleais prüfen
- Manuelle DNS-Einträge konfigurieren
In diesem Lab erstellen Sie das folgende Muster.
Abbildung 1:
2. Google Cloud-Dienste einrichten
Einrichtung der Umgebung im eigenen Tempo
- Melden Sie sich in der Google Cloud Console an und erstellen Sie ein neues Projekt oder verwenden Sie ein vorhandenes. Wenn Sie noch kein Gmail- oder Google Workspace-Konto haben, müssen Sie eins erstellen.
- Der Projektname ist der Anzeigename für die Teilnehmer dieses Projekts. Es handelt sich um einen String, der nicht von Google APIs verwendet wird. Sie können sie jederzeit aktualisieren.
- Die Projekt-ID ist für alle Google Cloud-Projekte eindeutig und kann nach dem Festlegen nicht mehr geändert werden. In der Cloud Console wird automatisch ein eindeutiger String generiert. Normalerweise ist es nicht wichtig, wie dieser String aussieht. In den meisten Codelabs müssen Sie auf Ihre Projekt-ID verweisen (in der Regel als
PROJECT_ID
angegeben). Wenn Ihnen die generierte ID nicht gefällt, können Sie eine andere zufällige ID generieren. Alternativ können Sie es mit einem eigenen Namen versuchen und sehen, ob er verfügbar ist. Sie kann nach diesem Schritt nicht mehr geändert werden und bleibt für die Dauer des Projekts bestehen. - Zur Information: Es gibt einen dritten Wert, die Projektnummer, die von einigen APIs verwendet wird. Weitere Informationen zu diesen drei Werten
- Als Nächstes müssen Sie die Abrechnung in der Cloud Console aktivieren, um Cloud-Ressourcen/-APIs zu verwenden. Die Durchführung dieses Codelabs kostet wenig oder gar nichts. Wenn Sie Ressourcen herunterfahren möchten, um weitere Kosten zu vermeiden, können Sie die erstellten Ressourcen oder das Projekt löschen. Neue Google Cloud-Nutzer können am Programm Kostenlose Testversion mit einem Guthaben von 300$ teilnehmen.
Cloud Shell starten
Während Sie Google Cloud von Ihrem Laptop aus per Fernzugriff nutzen können, wird in diesem Codelab Google Cloud Shell verwendet, eine Befehlszeilenumgebung, die in der Cloud ausgeführt wird.
Klicken Sie in der Google Cloud Console in der Symbolleiste oben rechts auf das Cloud Shell-Symbol:
Die Bereitstellung und Verbindung mit der Umgebung dauert nur einen Moment. Anschließend sehen Sie in etwa Folgendes:
Diese virtuelle Maschine verfügt über sämtliche Entwicklertools, die Sie benötigen. Sie bietet ein Basisverzeichnis mit 5 GB nichtflüchtigem Speicher und läuft in Google Cloud, was die Netzwerkleistung und Authentifizierung erheblich verbessert. Alle Aufgaben in diesem Codelab können in einem Browser ausgeführt werden. Sie müssen nichts installieren.
3. Aufgabe 1: Umgebung mit Terraform einrichten
Wir erstellen eine benutzerdefinierte VPC mit Firewallregeln und einem Subnetz. Öffnen Sie die Cloud Console und wählen Sie das Projekt aus, das Sie verwenden möchten.
- Öffnen Sie Cloud Shell oben rechts in der Konsole. Prüfen Sie, ob die richtige Projekt-ID in Cloud Shell angezeigt wird, und bestätigen Sie alle Aufforderungen zum Zulassen des Zugriffs.
- Erstellen Sie einen Ordner mit dem Namen „terraform-build“ und wechseln Sie in den Ordner.
mkdir terraform-build && cd terraform-build
- Erstellen Sie die Dateien main.tf und variable.tf.
touch main.tf variable.tf
- Wechseln Sie zur Ansicht Cloud Shell-Editor. Wählen Sie Editor aus und bestätigen Sie alle erforderlichen Aufforderungen, damit die Benutzeroberfläche geladen werden kann.
- Rufen Sie nach dem Laden Datei > Ordner öffnen auf, wechseln Sie zu /home/Ihr-Nutzername/terraform-build und wählen Sie Ok aus, um den Ordner im Editor zu öffnen.
- Wählen Sie die Datei variable.tf aus und fügen Sie Folgendes hinzu. Ersetzen Sie den Text
your-project-id-here
durch Ihre tatsächliche Projekt-ID in Anführungszeichen.
variable "project_id" { type = string default = "your-project-id-here" } variable "network_id" { type = string default = "gemini-vpc-net" }
- Öffnen Sie als Nächstes die Datei main.tf. Wir fügen nun Terraform-Code hinzu, um verschiedene Aktionen auszuführen, wie unten beschrieben.
APIs aktivieren |
|
VPC mit dem Namen „python-net“ erstellen |
|
Subnetz hinzufügen |
|
Zwei Firewallregeln hinzufügen |
|
- Kopieren Sie den folgenden Code in die Datei 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"] }
- Wechseln Sie zurück zum Cloud Shell-Terminal, achten Sie darauf, dass Sie sich im Verzeichnis terraform-build
cd terraform-build
befinden, und führen Sie die folgenden Befehle aus.
terraform init
Initialisiert das Arbeitsverzeichnis. In diesem Schritt werden die für die angegebene Konfiguration erforderlichen Anbieter heruntergeladen.
terraform plan
Erstellt einen Ausführungsplan, der zeigt, welche Aktionen Terraform zum Bereitstellen Ihrer Infrastruktur ausführt.
- Führen Sie nun den Befehl
terraform apply
aus und geben Sieyes
ein, um die Ressourcen zu erstellen.
4. Aufgabe 2: NAT-Gateway und VMs mit Terraform erstellen
Wir müssen ausgehenden externen Zugriff auf das Internet gewähren. Erstellen wir also ein Cloud NAT-Gateway und hängen wir es an.
- Öffnen Sie Cloud Shell, rufen Sie den Ordner „terraform-build“ auf und erstellen Sie die folgenden Dateien (insgesamt drei Dateien). Wir werden diese später bearbeiten.
touch nat-vm.tf psc.tf dns.tf
- Wechseln Sie zur Ansicht Cloud Shell-Editor, wählen Sie die Datei nat-vm.tf aus und fügen Sie den folgenden Terraform-Code hinzu. Dadurch werden ein NAT-Gateway und zwei VMs erstellt.
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
}
- Wechseln Sie zum Cloud Shell-Terminal, achten Sie darauf, dass Sie sich im Ordner terraform-build befinden, und führen Sie
terraform plan
aus. Dadurch wird angezeigt, dass 4 Elemente hinzugefügt werden. Führen Sie dannterraform apply
aus und geben Sieyes
ein, um das NAT-Gateway und zwei VMs zu erstellen.
5. Aufgabe 3: CLI-VMs konfigurieren und testen
- Rufen Sie „VM-Instanzen“ auf. Wählen Sie die VM aus, die mit cli-vm beginnt. Wählen Sie SSH aus.
- Sobald Sie eine SSH-Verbindung hergestellt haben, sollten Sie Zugriff auf die VM haben. Erstellen wir einen Ordner für die Ausführung der Gemini CLI.
mkdir geminicli && cd geminicli
- Für die Installation der Gemini CLI ist Node.js erforderlich. Installieren Sie Node.js mit dem folgenden Befehl:
curl -fsSL https://deb.nodesource.com/setup_24.x -o nodesource_setup.sh
Script ausführen
sudo -E bash nodesource_setup.sh
Node.js installieren
sudo apt-get install -y nodejs
- Wir legen einige Variablen fest, die bei der Verwendung der Vertex AI-Authentifizierungsoption helfen, um später einige Tests durchzuführen. Ersetzen Sie
YOUR_PROJECT_ID
durch Ihre tatsächlicheproject 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 neu laden
source ~/.bashrc
- Jetzt authentifizieren wir uns. Führen Sie den folgenden Befehl in der VM aus und drücken Sie bei Aufforderung y.
gcloud auth application-default login
- Kopieren Sie als Nächstes die URL, die mit https:// beginnt, öffnen Sie einen neuen Tab in Ihrem Lab-Browserfenster und fügen Sie die URL ein. Nehmen Sie die Aufforderungen an.
- Kopieren Sie den angezeigten Code, wechseln Sie zurück zur Sitzung der VM cli-vm und fügen Sie den kopierten Code bei Autorisierungscode eingeben ein. Drücken Sie dann die Eingabetaste, um sich zu authentifizieren.
- Installieren Sie jetzt die Gemini CLI, indem Sie den folgenden Befehl ausführen:
sudo npm install -g @google/gemini-cli
Geben Sie nach Abschluss gemini
ein, um die Benutzeroberfläche zu starten, wählen Sie ein gewünschtes Design aus und wählen Sie unter Select Auth method (Authentifizierungsmethode auswählen) die Option Vertex AI
aus.
- Nach der Authentifizierung können Sie Gemini CLI verwenden.
Traffic-Route zu Gemini über die Monitor-VM überwachen
- Rufen Sie „VM-Instanzen“ auf. Wählen Sie die VM aus, die mit monitor-vm beginnt. Wählen Sie „SSH“ aus.
- Sobald Sie eine SSH-Verbindung zu monitor-vm hergestellt haben, sollten Sie Zugriff haben.
- Wir verwenden den Befehl
dig
, um den Verbindungspfad zur Gemini API zu testen. Wir verwenden us-east1-aiplatform.googleapis.com.
dig us-east1-aiplatform.googleapis.com
Die Ausgabe sollte in etwa so aussehen (die Adresse ist jedoch anders). Hinweis: Der Pfad verläuft über öffentliche IP-Adressen, da die API eine öffentliche API ist.
NICHT KOPIEREN
; <<>> 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
- Führen wir nun einen kurzen
ping
-Test durch, um zu prüfen, ob wir eine Verbindung zur Gemini API herstellen können. Mit diesem Befehl werden vier Pings an us-east1-aiplatform.googleapis.com gesendet, damit wir eine Antwort von der öffentlichen Adresse der API erhalten.
ping -c 4 us-east1-aiplatform.googleapis.com
- Wir werden diese VM später noch einmal testen. Schließen Sie die SSH-Sitzung und fahren Sie fort.
6. Aufgabe 4: PSC-Endpunkt für googleapis mit Terraform erstellen
Um eine private Verbindung zu unserem Vertex API-Endpunkt zu ermöglichen, erstellen wir einen Private Service Connect-Endpunkt für Google APIs. So können wir eine private IP-Adresse verwenden, die wir zuweisen, um Traffic an die benötigten Google APIs weiterzuleiten, in diesem Fall Vertex.
- Öffnen Sie Cloud Shell in der Editoransicht, falls sie noch nicht geöffnet ist. Wir erstellen Folgendes:
- Erstellen Sie eine IP-Adresse für den PSC-Endpunkt 10.10.100.250 (
resource "google_compute_global_address" "default")
- PSC-Endpunkt für Google APIs erstellen (
resource "google_compute_global_forwarding_rule" "default")
Öffnen Sie die Datei psc.tf im Ordner terraform-build. Fügen Sie den folgenden Code in die Datei ein.
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 = ""
}
- Wechseln Sie zum Cloud Shell-Terminal und prüfen Sie, ob Sie sich im Ordner
terraform-build
befinden. Führen Sie dannterraform init
aus. Führen Sie dannterraform plan
aus. Dadurch wird angezeigt, dass zwei Elemente hinzugefügt werden.
Führen Sie dannterraform apply
aus und geben Sieyes
ein, um den IP- und PSC-Google APIs-Endpunkt zu erstellen. - Vorhandensein des Endpunkts prüfen
gcloud compute addresses list --filter="name=( 'gemini-ip' ...)"
gcloud compute forwarding-rules describe pscgemini --global
7. Aufgabe 5: Manuellen DNS-Eintrag für googleapis mit Terraform erstellen
Sie können einen manuellen DNS-Eintrag erstellen, der mit privatem DNS auf den PSC-Endpunkt verweist. Dies wirkt sich auf alle Netzwerke aus, die Sie ihm zuweisen.
- Rufen Sie „Netzwerkdienste“ auf und wählen Sie „Cloud DNS“ aus.
- In Zonen sollte eine automatisch erstellte Zone für Private Service Connect für Google APIs mit dem Zonentypservicedirectory angezeigt werden. Damit kann eine Verbindung zum PSC-Endpunkt im Format **SERVICE-ENDPOINT.p.googleapis.com hergestellt werden. Beispiel:
aiplatform-pscgemini.p.googleapis.com
- In diesem Fall möchten wir manuell einen privaten DNS-Eintrag erstellen. Die Konfiguration sieht so aus:
- Erstellen Sie eine private DNS-Zone mit dem Namen „googleapis-private“ für „googleapis.com“ und beschränken Sie sie auf das Netzwerk „python-net“.
- Fügen Sie einen A-Eintrag hinzu, um „googleapis.com“ der IP-Adresse „10.10.100.250“ zuzuordnen.
- Fügen Sie einen CNAME-Eintrag hinzu, um alle Subdomains von „googleapis.com“ (z.B. www.googleapis.com) zu „googleapis.com“ weiterzuleiten.
- Öffnen Sie Cloud Shell in der Editoransicht, falls sie noch nicht geöffnet ist. Öffnen Sie die Datei dns.tf im Ordner „terraform-build“. Fügen Sie der Datei den folgenden Code hinzu.
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."]
}
- Wechseln Sie zum Cloud Shell-Terminal und prüfen Sie, ob Sie sich im Ordner
terraform-build
befinden. Führen Sie dannterraform plan
aus. Dadurch wird angezeigt, welche Elemente hinzugefügt werden.
Führen Sie dannterraform apply
aus und geben Sieyes
ein, um den privaten DNS-Eintrag zu erstellen. - Sie sollten eine Einrichtung mit einem A-Eintrag und einem CNAME-Eintrag wie diesem sehen:
- Als Nächstes prüfen wir die Konnektivität mit diesen Änderungen auf monitor-vm.
8. Aufgabe 7: Endpunktverbindung über IP-Adresse prüfen
Wir stellen eine Verbindung über den privaten Endpunkt her, um eine Verbindung zu Gemini herzustellen.
- Rufen Sie die VM-Instanz monitor-vm auf. Wählen Sie „SSH“ aus und stellen Sie eine SSH-Verbindung zur VM her
- Prüfen Sie den Verbindungspfad zu us-east1-aiplatform.googleapis.com mit dem Befehl
ping
. Dadurch wird die IP-Adresse im privaten DNS, A-Eintrag für googleapis, angepingt. Diese IP-Adresse ist ein PSC-Endpunkt und Ihre Pings schlagen fehl.
ping -c 2 us-east1-aiplatform.googleapis.com
- Prüfen Sie den Verbindungspfad mit einem
ping
über den automatisch erstellten DNS-Eintrag für PSC Google APIs mitaiplatform-pscvertexgemini.p.googleapis.com
. Dies verweist auf die IP-Adresse des PSC-Endpunkts und Ihre Pings sind nicht erfolgreich.
ping -c 2 aiplatform-pscgemini.p.googleapis.com
- Prüfen Sie den Verbindungspfad zu us-east1-aiplatform.googleapis.com mit dem Befehl
dig
. Dies sollte die IP-Adresse des PSC-Endpunkts (10.10.100.250) sein.
dig us-east1-aiplatform.googleapis.com
- Wenn Sie fertig sind, können Sie die monitor-vm-SSH-Sitzung schließen.
- Jetzt können wir einen TCP-Dump auf der cli-vm ausführen. Wir müssen zwei SSH-Sitzungen zur selben VM öffnen. In einer Sitzung wird der Befehl „tcpdump“ ausgeführt, in der anderen verwenden wir die Gemini CLI.
- Stellen Sie eine SSH-Verbindung zur ersten Sitzung auf der cli-vm her.
- Geben Sie den folgenden Befehl ein, um die Verbindung in einem tcpdump zu sehen.
sudo tcpdump -i any port 53 -n or host us-east1-aiplatform.googleapis.com
- Stellen Sie nun eine SSH-Verbindung zur nächsten Sitzung auf der cli-vm her.
- Aktivieren Sie die Gemini CLI, indem Sie
gemini
eingeben. - Stellen Sie die folgende Frage: „Welche Farbe hat der Himmel?“, um einen Aufruf der Gemini API zu generieren.
- Drücken Sie die Eingabetaste, um die Suche auszuführen und das Ergebnis zu sehen.
- Wechseln Sie zurück zur ersten Sitzung auf der cli-vm. Sie sollten das Ergebnis von tcpdump sehen. Sie sehen, dass die IP-Adresse der VM die IP-Adresse des PSC-Endpunkts verwendet, um eine Verbindung zur Gemini API herzustellen.
Alle SSH-Sitzungen zu VM-Instanzen schließen
9. Bereinigen
- Rufen Sie Cloud Shell auf, achten Sie darauf, dass Sie sich im Verzeichnis terraform-build
cd terraform-build
befinden, und führen Sie den folgenden Befehl austerraform destroy
. Geben Sieyes
ein. Alle Ressourcen, die Sie in Ihrem Projekt mit Terraform erstellt haben, werden entfernt.
10. Glückwunsch
Sie haben erfolgreich eine Verbindung zu Gemini CLI hergestellt, sowohl über die öffentliche API-Adresse als auch privat über den Private Service Connect-Endpunkt für Google APIs. Mit dieser Funktion können Sie private API-Verbindungen auf Ihre lokale Umgebung oder andere Cloud-Umgebungen ausweiten, die über Interconnect, Cross-Cloud Interconnect und VPC verbunden sind.
Weitere Informationen
Weitere Informationen finden Sie unter Vertex AI-Netzwerk und im Gemini CLI-Repository.
Nächstes Lab absolvieren
Setzen Sie Ihre Aufgabenreihe mit Google Cloud fort und sehen Sie sich diese anderen Google Cloud-Labs an: