‫Antigravity CLI ב-GCE עם נקודת קצה (endpoint) של Private Service Connect

1. סקירה כללית

אפשר להשתמש ב-Antigravity CLI בסביבות מקומיות וגם בסביבות וירטואליות. ‫Antigravity משלב את היכולות של Gemini ישירות בטרמינל. מבחינת רשת, כשמשתמשים ב-Antigravity CLI, מתבצעת קריאה ל-Gemini API דרך כתובת ה-IP של ה-API, שנגישה לציבור.

מה קורה אם רוצים להשתמש ב-Antigravity CLI במכונת Google Compute Engine, אבל רוצים להתחבר ל-API באופן פרטי? בשיעור Codelab הזה נסביר איך להגדיר נקודת קצה של Private Service Connect ל-Google APIs, כדי לנתב את התנועה לכתובת IP פנימית שאתם מציינים.

ההגדרות יהיו שילוב של Terraform, ‏ gcloud והמסוף.

בשיעור ה-Lab הזה תלמדו איך לבצע את המשימה הבאה:

  • הגדרה של מכונה וירטואלית ו-Cloud NAT
  • התקנה של Antigravity CLI ואימות
  • הגדרת נקודת קצה מסוג Private Service Connect כדי להתחבר ל-Googleapis
  • אימות נתיב הקישוריות אל ‎ *.googleapis
  • הגדרת רשומות DNS ידניות

בשיעור ה-Lab הזה תיצרו את התבנית הבאה.

איור 1.

8b7f6e48b615e266.png

2. הגדרה של שירותי Google Cloud

הגדרת סביבה בקצב אישי

  1. נכנסים ל-מסוף Google Cloud ויוצרים פרויקט חדש או משתמשים בפרויקט קיים. אם עדיין אין לכם חשבון Gmail או Google Workspace, אתם צריכים ליצור חשבון.

295004821bab6a87.png

37d264871000675d.png

96d86d3d5655cdbe.png

  • שם הפרויקט הוא השם המוצג של הפרויקט הזה למשתתפים. זו מחרוזת תווים שלא נמצאת בשימוש ב-Google APIs. תמיד אפשר לעדכן את המיקום.
  • מזהה הפרויקט הוא ייחודי לכל הפרויקטים ב-Google Cloud, והוא קבוע (אי אפשר לשנות אותו אחרי שהוא מוגדר). מסוף Cloud יוצר באופן אוטומטי מחרוזת ייחודית, ובדרך כלל לא צריך לדעת מה היא. ברוב ה-Codelabs, תצטרכו להפנות למזהה הפרויקט (בדרך כלל מסומן כ-PROJECT_ID). אם אתם לא אוהבים את המזהה שנוצר, אתם יכולים ליצור מזהה אקראי אחר. אפשר גם לנסות שם משתמש משלכם ולבדוק אם הוא זמין. אי אפשר לשנות את ההגדרה הזו אחרי השלב הזה, והיא נשארת לאורך הפרויקט.
  • לידיעתכם, יש ערך שלישי, מספר פרויקט, שחלק מממשקי ה-API משתמשים בו. מידע נוסף על שלושת הערכים האלה מופיע במאמרי העזרה.
  1. בשלב הבא, תצטרכו להפעיל את החיוב במסוף Cloud כדי להשתמש במשאבי Cloud או בממשקי API של Cloud. השלמת ה-codelab הזה לא תעלה לכם הרבה, אם בכלל. כדי להשבית את המשאבים ולמנוע חיובים נוספים אחרי שתסיימו את המדריך הזה, תוכלו למחוק את המשאבים שיצרתם או למחוק את הפרויקט. משתמשים חדשים ב-Google Cloud זכאים לתוכנית תקופת ניסיון בחינם בשווי 300$.

מפעילים את Cloud Shell

אפשר להפעיל את Google Cloud מרחוק מהמחשב הנייד, אבל ב-Codelab הזה נשתמש ב-Google Cloud Shell, סביבת שורת פקודה שפועלת בענן.

ב-מסוף Google Cloud, לוחצים על סמל Cloud Shell בסרגל הכלים שבפינה הימנית העליונה:

הפעלת Cloud Shell

יחלפו כמה רגעים עד שההקצאה והחיבור לסביבת העבודה יושלמו. בסיום התהליך, אמור להופיע משהו כזה:

צילום מסך של טרמינל Google Cloud Shell שבו מוצג שהסביבה מחוברת

המכונה הווירטואלית הזו כוללת את כל הכלים שדרושים למפתחים. יש בה ספריית בית בנפח מתמיד של 5GB והיא פועלת ב-Google Cloud, מה שמשפר מאוד את הביצועים והאימות ברשת. אפשר לבצע את כל העבודה ב-codelab הזה בדפדפן. לא צריך להתקין שום דבר.

3. הגדרת סביבה באמצעות Terraform

ניצור VPC בהתאמה אישית עם כללי חומת אש ותת-רשת. פותחים את מסוף Cloud ובוחרים את הפרויקט שבו רוצים להשתמש.

  1. פותחים את Cloud Shell בפינה השמאלית העליונה של המסוף, מוודאים שמופיע מזהה הפרויקט הנכון ב-Cloud Shell ומאשרים את כל ההנחיות למתן גישה. b51b80043d3bac90.png
  2. יוצרים תיקייה בשם terraform-build ועוברים לתיקייה
mkdir terraform-build && cd terraform-build 
  1. יוצרים קובץ main.tf וקובץ variable.tf.
touch main.tf variable.tf 
  1. עוברים לתצוגה של Cloud Shell Editor. בוחרים באפשרות עורך ומוודאים שמאשרים את כל ההנחיות הנדרשות כדי שהממשק ייטען.
  2. אחרי הטעינה, עוברים אל File > Open Folder (קובץ > פתיחת תיקייה), אל /home/your-user-name/terraform-build ולוחצים על Ok (אישור) כדי לפתוח את התיקייה בעורך. 39b3eb9a3e077bfd.png
  3. בוחרים את הקובץ variable.tf ומוסיפים את הקוד הבא. מחליפים את הטקסט your-project-id-here במזהה הפרויקט בפועל בתוך מרכאות.
variable "project_id" {
  type = string
  default = "your-project-id-here"
}

variable "network_id" {
  type = string
  default = "antigravity-vpc-net"
}
  1. לאחר מכן פותחים את הקובץ 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"

  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: יצירת שער NAT ומכונות וירטואליות באמצעות Terraform

אנחנו צריכים לתת גישה חיצונית לאינטרנט, אז ניצור שער Cloud NAT ונצרף אותו.

  1. פותחים את Cloud Shell, עוברים לתיקייה terraform-build ויוצרים את הקבצים הבאים (סה"כ שלושה קבצים). נערוך אותם בהמשך.
touch nat-vm.tf psc.tf dns.tf
  1. עוברים לתצוגה Cloud Shell editor, בוחרים את הקובץ 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 terminal, מוודאים שאתם בתיקייה terraform-build ומריצים את הפקודה terraform plan. הפקודה הזו תראה לכם ש-4 פריטים יתווספו. לאחר מכן מריצים את הפקודה terraform apply ומקלידים yes כדי ליצור את שער ה-NAT ושני מכונות וירטואליות.

5. משימה 3: הגדרת מכונות וירטואליות של CLI ובדיקה

  1. עוברים אל VM instances. בוחרים את המכונה הווירטואלית שמתחילה ב-cli-vm. בוחרים באפשרות SSH.
  2. אחרי שמתחברים באמצעות SSH, אמורה להיות לכם גישה למכונה הווירטואלית. עכשיו ניצור תיקייה להרצת Gemini CLI.
mkdir antigravitycli && cd antigravitycli
  1. כדי להתקין את Antigravity CLI, משתמשים בפקודה הבאה
curl -fsSL https://antigravity.google/cli/install.sh | bash && source ~/.bashrc

בדיקת הגרסה

agy --version
  1. נתחבר ונאמת את זה כדי שנוכל לבצע בדיקות בהמשך.
agy
  1. בוחרים באפשרות 1 Google OAuth . עכשיו צריך לבצע אימות. 928a0429cae0c48e.png
  2. לאחר מכן מעתיקים את כתובת ה-URL שמתחילה ב-https://, פותחים כרטיסייה חדשה בחלון הדפדפן של המעבדה ומדביקים את כתובת ה-URL. מאשרים את ההנחיות.

a90c48f580c091c5.png

  1. כשמופיעה ההודעה הבאה, בוחרים באפשרות 'העתקה ללוח', חוזרים להפעלה של מכונת ה-VM‏ cli-vm, ובשדה Enter authorization code:‎ מדביקים את הקוד שהעתקתם ולוחצים על Enter כדי לבצע אימות.

d62366d799a8b341.png

  1. חוזרים להפעלה של cli-vm במכונה הווירטואלית, מדביקים את הקוד שהעתקתם בשורה Enter authorization code: (הזנת קוד הרשאה) ולוחצים על Enter כדי לבצע אימות.

afe6355fb124f264.png

  1. יוצג המסך שבו אפשר להתאים אישית את ההסכם ולאשר אותו, ואז לעבור לספריית הבית. בוחרים את האפשרויות הרלוונטיות להשלמה.

9dd9cb8ab457916a.png

1b9720010c71563c.png

  1. אחרי שתשלימו את התהליך, תוכלו להתחיל להשתמש ב-Antigravity CLI.

134e58b581adf1f3.png

מעקב אחר נתיב התנועה אל Gemini באמצעות monitor vm

  1. עוברים אל VM instances. בוחרים את המכונה הווירטואלית שמתחילה ב-monitor-vm. בוחרים באפשרות SSH.
  2. אחרי שמתחברים ב-SSH אל monitor-vm, אמורה להיות לכם גישה
  3. נשתמש בפקודה dig כדי לבדוק את נתיב החיבור ל-Gemini API. נשתמש ב-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    216.239.38.223
us-east1-aiplatform.googleapis.com. 300 IN A    216.239.34.223
us-east1-aiplatform.googleapis.com. 300 IN A    216.239.36.223
us-east1-aiplatform.googleapis.com. 300 IN A    216.239.32.223
  1. עכשיו נבצע בדיקה מהירה של ping כדי לראות אם אפשר להתחבר ל-Gemini API. הפקודה הזו תשתמש ב-4 פינגים ל-us-east1-aiplatform.googleapis.com, כך שנקבל תגובה מהכתובת הציבורית של ה-API.
ping -c 4 us-east1-aiplatform.googleapis.com
  1. נחזור לבדוק את המכונה הווירטואלית הזו בהמשך. סוגרים את סשן ה-SSH וממשיכים.

6. משימה 4: יצירת נקודת קצה של PSC ל-googleapis באמצעות Terraform

כדי להפעיל קישוריות פרטית לנקודת קצה ל-API של Vertex, ניצור נקודת קצה של Private Service Connect ל-Google APIs. כך נוכל להשתמש בכתובת IP פרטית שהקצנו לניתוב תעבורה לממשקי Google API שאנחנו צריכים, במקרה הזה Vertex.

  1. אם Cloud Shell לא פתוח, פותחים אותו בתצוגת עריכה. ניצור את הפריטים הבאים:
  • יוצרים כתובת IP לנקודת הקצה של PSC‏ 10.10.100.250 (resource "google_compute_global_address" "default")
  • יצירת נקודת קצה של PSC ל-Google APIs ‏ (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 = ""
  
  service_directory_registrations {
    namespace                = "googleapis"
    service_directory_region = "us-east1"
  }
}
  1. עוברים אל הטרמינל של Cloud Shell ומוודאים שאתם נמצאים בתיקייה terraform-build. לאחר מכן מריצים את הפקודה terraform init ואז את הפקודה terraform plan כדי לראות שיתווספו 2 פריטים,
    ואז מריצים את הפקודה terraform apply ומקלידים yes כדי ליצור את נקודת הקצה של כתובת ה-IP ושל Google APIs ב-PSC.
  2. אימות קיום של נקודת קצה
gcloud compute addresses list --filter="name=( 'gemini-ip' ...)"
gcloud compute forwarding-rules describe pscgemini --global

7. משימה 5: יצירת רשומת DNS ידנית ל-googleapis באמצעות Terraform

אפשר ליצור רשומת DNS ידנית כדי להפנות לנקודת הקצה של PSC באמצעות שרת DNS פרטי. השינוי ישפיע על כל הרשתות שמשויכות אליו.

  1. עוברים אל Network services (שירותי רשת) ובוחרים באפשרות Cloud DNS.
  2. באזורים, אמור להופיע אזור שנוצר באופן אוטומטי עבור Private Service Connect ל-Google APIs, עם סוג האזור service directory. אפשר להשתמש בכתובת הזו כדי להתחבר לנקודת הקצה (endpoint) של PSC בפורמט **SERVICE-ENDPOINT.p.googleapis.com לדוגמה: aiplatform-pscgemini.p.googleapis.com
  3. במקרה הזה, אנחנו רוצים ליצור באופן ידני רשומה של שרת DNS פרטי. ההגדרה תהיה כדלקמן
  • יוצרים תחום DNS פרטי בשם googleapis-private עבור googleapis.com ומגבילים אותו לרשת antigravity-vpc-net.
  • מוסיפים רשומת A כדי למפות את 'googleapis.com' לכתובת ה-IP ‏'10.10.100.250'.
  • מוסיפים רשומת CNAME כדי להפנות את כל תתי-הדומיין של googleapis.com (לדוגמה, www.googleapis.com) אל googleapis.com.
  1. אם 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."]  
}
  1. עוברים אל הטרמינל של Cloud Shell ומוודאים שאתם נמצאים בתיקייה terraform-build. אחר כך מריצים את הפקודה terraform plan כדי לראות אילו פריטים יתווספו,
    ואז מריצים את הפקודה terraform apply ומקלידים yes כדי ליצור את רשומת ה-DNS הפרטית.
  2. ההגדרה אמורה לכלול רשומת A ורשומת CNAME, כמו בדוגמה הבאה

498d44c7ca0a5ac4.png

  1. לאחר מכן, אנחנו מאמתים את הקישוריות עם השינויים האלה ב-monitor-vm

8. משימה 7: אימות הקישוריות של נקודת הקצה באמצעות כתובת IP

נתחבר ל-Gemini באמצעות נקודת הקצה הפרטית.

  1. עוברים אל VM Instance monitor-vm. בוחרים באפשרות SSH ומתחברים למכונה הווירטואלית באמצעות SSH
  2. בודקים את נתיב הקישוריות אל us-east1-aiplatform.googleapis.com באמצעות הפקודה ping. הפעולה הזו תבצע פינג לכתובת ה-IP בשרת ה-DNS הפרטי, רשומת A עבור googleapis. כתובת ה-IP הזו היא נקודת קצה של PSC, והפינגים שלכם ייכשלו.
ping -c 2 us-east1-aiplatform.googleapis.com
  1. בודקים את נתיב הקישוריות אל us-east1-aiplatform.googleapis.com באמצעות הפקודה dig. זו צריכה להיות כתובת ה-IP של נקודת הקצה (endpoint) של PSC ‏(10.10.100.250).
dig us-east1-aiplatform.googleapis.com

1dbd3d34dd788335.png

  1. אחרי שמסיימים, אפשר לסגור את סשן ה-SSH של monitor-vm.
  1. עוברים אל VM Instance‏ cli-vm. בוחרים באפשרות SSH ומתחברים למכונה הווירטואלית באמצעות SSH
  2. עכשיו אפשר להריץ TCP dump ב-cli-vm. צריך לפתוח שני סשנים של SSH לאותה מכונה וירטואלית. בסשן אחד נריץ את הפקודה tcpdump ובסשן השני נשתמש ב-Gemini CLI.
  3. מקלידים את הפקודה הבאה כדי לראות את הקישוריות ב-tcpdump
sudo tcpdump -i any port 53 -n or host us-east1-aiplatform.googleapis.com
  1. עכשיו מתחברים ב-SSH לסשן הבא ב-cli-vm
  2. עוברים לתיקייה antigravitycli cd antigravitycli
  3. מפעילים את Antigravity CLI על ידי הקלדת agy
  4. שואלים את השאלה הבאה: what color is the sky? כדי ליצור קריאה ל-Gemini API

ac0844f649077814.png

  1. מקישים על Enter כדי להריץ את הבדיקה ולראות את התוצאה.
  2. חוזרים לסשן הראשון ב-cli-vm. אמורה להופיע תוצאה של tcpdump. תראו שהתנועה נכנסת ויוצאת, וכתובת ה-IP של המכונה הווירטואלית משתמשת בכתובת ה-IP של נקודת הקצה של PSC כדי להתחבר אל Gemini API.

9dbdca7b05f07483.png

סגירת כל סשני ה-SSH למכונות וירטואליות

9. הסרת המשאבים

  1. עוברים אל Cloud Shell, מוודאים שאתם בספרייה terraform-build cd terraform-build, מריצים את הפקודה הבאה terraform destroy ומקלידים yes. כל המשאבים שיצרתם בפרויקט באמצעות Terraform יוסרו.

10. מזל טוב

הצלחתם להתחבר ל-Antigravity CLI באמצעות כתובת API ציבורית ובאופן פרטי באמצעות נקודת קצה (endpoint) של Private Service Connect ל-Google APIs. הפונקציונליות הזו יכולה להרחיב את הקישוריות הפרטית של ה-API לסביבה המקומית או לסביבת ענן אחרת שמחוברת באמצעות (Interconnect, ‏ Cross-Cloud Interconnect ו-VPC).

השלבים הבאים / מידע נוסף

מידע נוסף זמין במסמכי התיעוד של Antigravity CLI

אל שיעור ה-Lab הבא

אתם יכולים להמשיך את יחידת ה-Quest ב-Google Cloud או לנסות את שיעורי ה-Lab הבאים של Google Cloud: