התקנת Agent Substrate ב-GKE

‫Agent Substrate מריץ ביעילות עומסי עבודה סוכניים באשכולות GKE על ידי השהיית סוכנים בלי פעילות ושחזור הסוכנים האלה כשהם צריכים לפעול שוב. Agent Substrate היא תוכנת קוד פתוח שאפשר להתקין באשכול GKE Standard.

במאמר הזה מוסבר איך להכין את פרויקט Google Cloud ואת אשכול GKE ל-Agent Substrate, איך להריץ את קובץ ההתקנה ומהם המשאבים שנוצרים במהלך ההתקנה.

תמחור

השימוש ב-Agent Substrate לא כרוך בתשלום נוסף ב-GKE. התמחור של GKE חל על המשאבים שאתם יוצרים.

מגבלות

יש הגבלות על ההתקנה של Agent Substrate:

  • ‫Cloud Shell: אי אפשר להתקין את Agent Substrate ב-Cloud Shell כי הוא מספק 5 GB של אחסון בדיסק מתמיד, וזה לא מספיק להתקנה. צריך להריץ את קובץ ההתקנה במחשב המקומי.
  • מצב אשכול: אפשר להתקין את Agent Substrate רק באשכולות GKE Standard. אין תמיכה באשכולות Autopilot.
  • קלאסטרים קיימים וממשקי API בגרסת בטא: אם מפעילים את ממשקי ה-API הנדרשים בגרסת בטא (podcertificaterequests ו-clustertrustbundles) בקלאסטר קיים שמופעלת בו גרסה 1.36, צריך להחליף את הצמתים הקיימים לפני שמתקינים את Agent Substrate. בצמתים שנוצרו לפני העדכון לא מופעלת הקרנה של אישור Pod ‏(MountVolume.SetUp failed: unimplemented). באשכולות שמופעלת בהם גרסה 1.37 ואילך, אין צורך להחליף צמתים קיימים.
  • סוגי מכונות: אי אפשר להשתמש בסדרות מכונות שפועלות על ארכיטקטורות מעורבות של מעבדים (כמו סוגי מכונות E2).

לפני שמתחילים

לפני שמתחילים, חשוב לוודא שביצעתם את הפעולות הבאות:

  • מפעילים את ממשק Google Kubernetes Engine API.
    • הפעלת Google Kubernetes Engine API
  • כדי להשתמש ב-CLI של Google Cloud למשימה הזו, צריך להתקין ואז לאתחל את ה-CLI של gcloud. אם התקנתם בעבר את ה-CLI של gcloud, מריצים את הפקודה gcloud components update כדי לקבל את הגרסה העדכנית. יכול להיות שגרסאות קודמות של ה-CLI של gcloud לא יתמכו בהרצת הפקודות שמופיעות במסמך הזה.
  • מתקינים את הרכיבים הבאים ב-CLI של gcloud:
    • kubectl
    • gke-gcloud-auth-plugin
  • מוודאים שהכלים הבאים מותקנים במחשב המקומי:
    • ‫Git כדי לשכפל את מאגר Agent Substrate.
    • עוברים להרצת התוכניות של קובץ ההתקנה, שמופצות כקוד מקור.
    • make כדי להפעיל את קובץ ההתקנה.

  • מכיוון שהתוכנה להתקנה פועלת בשמכם כדי להפעיל ממשקי API ולספק משאבים, צריך להגדיר Application Default Credentials‏ (ADC) על ידי הרצת הפקודה הבאה:

    gcloud auth application-default login

    מידע נוסף על אימות באמצעות ADC זמין במאמר הגדרת Application Default Credentials.

התפקידים הנדרשים

כדי לקבל את ההרשאות שדרושות להתקנת Agent Substrate, צריך לבקש מהאדמין להקצות לכם את תפקידי ה-IAM הבאים בפרויקט:

להסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

יכול להיות שאפשר לקבל את ההרשאות הנדרשות גם באמצעות תפקידים בהתאמה אישית או תפקידים מוגדרים מראש.

הדרישות לגבי אשכולות

אם מאפשרים לתוכנת ההתקנה ליצור אשכול בשבילכם, היא מגדירה באופן אוטומטי אשכול שעומד בכל הדרישות של Agent Substrate.

אם בוחרים להתקין את Agent Substrate באשכול קיים, האשכול הזה צריך לעמוד בדרישות הבאות:

  • פועל ב-GKE Standard (ה-Agent Substrate נתמך רק באשכולות Standard).
  • פועלת ב-GKE בגרסה 1.36 (עם הפעלת דגלי בטא) או בגרסה 1.37 ואילך.
  • משתמש בסוגי מכונות בגודל c3-standard-4 או גדול יותר לצמתים.

  • הפעלתם את ממשקי ה-API של PodCertificateRequest ו-ClusterTrustBundle Kubernetes (certificates.k8s.io/v1beta1/podcertificaterequests ו-certificates.k8s.io/v1beta1/clustertrustbundles). כדי להפעיל את ממשקי ה-API האלה באשכול קיים, מריצים את הפקודה הבאה:

    gcloud container clusters update CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --enable-kubernetes-unstable-apis=certificates.k8s.io/v1beta1/podcertificaterequests,certificates.k8s.io/v1beta1/clustertrustbundles
    • גרסה 1.36: אחרי הפעלת ממשקי ה-API, צריך להחליף את הצמתים הקיימים – למשל, על ידי שדרוג מאגר הצמתים או יצירה מחדש של הצמתים שלו. הקרנת אישורים של Pod לא מופעלת בצמתים שהיו קיימים לפני העדכון (MountVolume.SetUp failed: unimplemented).
    • גרסה 1.37 ואילך: הקרנת אישורים של Pod כבר מופעלת בצמתים קיימים, כך שלא צריך להחליף צמתים אחרי הפעלת ממשקי ה-API.

התקנת Agent Substrate

כדי להתקין את Agent Substrate, מריצים את הפקודה הבאה בטרמינל המקומי:

curl -sSL https://raw.githubusercontent.com/ai-on-gke/substrate-gke/main/install.sh | bash

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

  • מזהה פרויקט (חובה): מציינים את Google Cloud הפרויקט שבו יוקצו משאבים. אם הגדרתם פרויקט ברירת מחדל ל-CLI של gcloud, תוכנת ההתקנה תשתמש במזהה הפרויקט הזה.
  • אשכול (חובה): בוחרים אם לאפשר לתוכנת ההתקנה ליצור אשכול GKE חדש עם הגדרות ברירת מחדל מומלצות, או להתקין את Agent Substrate באשכול קיים. אם בחרתם להתקין באשכול קיים, צריך לוודא שהוא עומד בדרישות שמפורטות בקטע דרישות האשכול.
  • קטגוריית תמונת מצב (אופציונלי): מציינים שם מותאם אישית של קטגוריה ב-Cloud Storage, או משאירים את השדה ריק כדי לאפשר לתוכנת ההתקנה ליצור קטגוריית ברירת מחדל בשם ate-snapshots-<project>-<zone>.

כשמוצגת בקשה לבחור מקור קובץ אימג' של קונטיינר, אפשר לבחור מבין האפשרויות הבאות:

  • תמונות מוכנות מראש: משיכת תמונות שפורסמו מ-Container Registry. מכיוון שלא נבנה או נדחף שום דבר, לא צריך מאגר תמונות משלו לפרויקט Google Cloud .
  • Build from source: יוצר את קובצי האימג' ממאגר Agent Substrate (או מענף בהתאמה אישית) במעלה הזרם ומעלה אותם למאגר Artifact Registry של הפרויקט.

מה תוכנת ההתקנה עושה

תוכנת ההתקנה מפעילה את התוכנות הבאות בשמכם:

  • ‫setup-gcp: יוצר או מאמת את המשאבים הנדרשים Google Cloud , מפעיל ממשקי API, יוצר את אשכול GKE (אם בחרתם לא להשתמש באשכול קיים) ואת קטגוריית Cloud Storage, ומגדיר את מדיניות IAM.
  • ‫ate-setup: פריסת תמונות קונטיינר ופקדים של Agent Substrate שנבנו מראש באשכול GKE.

קודם כול, תוכנת ההתקנה מבצעת את השינויים הבאים בפרויקט Google Cloud :

  1. הפעלת ממשקי ה- Google Cloud API שנדרשים ל-Agent Substrate.
  2. יוצר אשכול GKE Standard (אם לא משתמשים באשכול קיים) עם ההגדרות הבאות:
    • איחוד זהויות של עומסי עבודה ל-GKE: מאפשר ל-Agent Substrate לגשת ל-Cloud Storage בלי לאחסן מפתחות בצמתים.
    • ‫GKE Dataplane V2: מטפל ברישות שנדרש לניתוב בקשות נכנסות לסוכנים.
    • ‫Certificate APIs (PodCertificateRequest ו-ClusterTrustBundle): מאפשרים לממשקי ה-API האלה של Kubernetes בגרסת בטא להנפיק אישורים לתקשורת TLS בין רכיבי Agent Substrate.
    • ‫Managed OpenTelemetry: אוסף מדדים ומעקבים מהאשכול.
  3. יוצר את הקטגוריה של Cloud Storage שאליה Agent Substrate כותב את התמונות שלכם.
  4. נותנת ל-Agent Substrate גישה ל-Cloud Storage כדי לאחסן תמונות מצב. אם בוחרים לבנות מהמקור, מקבלים גם גישה ל-Artifact Registry עבור תמונות של קונטיינרים.
  5. יוצר לוחות בקרה של Cloud Monitoring שכוללים תרשימים של זמן האחזור של הניתוב של Agent Substrate, גודל התמונה ונתוני התנועה של gRPC.

לאחר מכן, תוכנת ההתקנה מבצעת את השינויים הבאים באשכול:

  1. הוספה של קבוצת Agent Substrate API ומשאבים לאשכול. אלה משאבים מותאמים אישית של Kubernetes, כמו ActorTemplate (שמגדיר את קובצי האימג' בקונטיינר והמשאבים שבהם הסוכנים משתמשים) ו-WorkerPool (שמגדיר כמה ארגזי חול לא פעילים מוכנים לשימוש).
  2. הגדרת רשויות האישורים שמנפיקות את האישורים שמזהים את הרכיבים של Agent Substrate ואת השחקנים שלכם. הרכיבים מציגים את האישורים האלה כדי לאמת אחד את השני באמצעות mTLS.
  3. פריסת הרכיבים של Agent Substrate באשכול, יחד עם מסד נתונים של PostgreSQL שעוקב אחרי המצב של השחקנים והעובדים. תוכנת ההתקנה מחכה שמסד הנתונים וכל ה-Pods של מישור הבקרה יהיו מוכנים.

רכיבי Agent Substrate נפרסים כעומסי עבודה רגילים במרחבי השמות ate-system ו-podcertificate-controller-system. ההתקנה לא משנה את מישור הבקרה של GKE.

הרכיבים שנפרסים כוללים את זמן הריצה שמבוסס על gVisor, ש-Agent Substrate משתמש בו כברירת מחדל כדי לבודד כל אחד מהסוכנים מהצומת שבו הוא פועל. תוכנת ההתקנה לא מגדירה סביבות זמן ריצה של מכונות וירטואליות מיקרו. כדי להשתמש בזמני ריצה של מכונות וירטואליות מיקרו, צריך לפרוס אותם באופן ידני במאגר צמתים שמופעלת בו וירטואליזציה מקוננת. פרטים נוספים מופיעים בהוראות ההפעלה של microVM במאגר Agent Substrate.

אם ההתקנה נכשלת בשלב כלשהו (לדוגמה, בגלל שגיאה זמנית ברשת או בגלל שפג התוקף של האסימון), מריצים את הפקודה מחדש. תוכנת ההתקנה שומרת את המשאבים הקיימים וממשיכה מהמקום שבו היא הפסיקה.

כדי לשדרג את Agent Substrate באשכול קיים, מריצים את קובץ ההתקנה ובוחרים באפשרות שדרוג אשכול מותקן. פרטים נוספים מופיעים בקובץ README של substrate-gke בקטע Upgrading an installed cluster.

שלבים אופציונליים

אחרי פריסת רכיבי הליבה, תוכנת ההתקנה מציעה את השלבים האופציונליים הבאים:

  • ‫Filestore CSI driver: מתקין את Filestore CSI driver שהוגדר ל-Agent Substrate. בוחרים באפשרות הזו אם הסוכנים צריכים אחסון קבצים משותף בין פודים, כמו סביבות עבודה משותפות או מאגרי מידע. אם התוסף המנוהל GKE Filestore מופעל באשכול, תוכנת ההתקנה משביתה אותו לפני פריסת מנהל ההתקן.
  • התאמה אוטומטית לעומס (autoscaling) במאגר הצמתים: מאפשרת התאמה אוטומטית לעומס (autoscaling) באשכול של GKE במאגר הצמתים. מציינים את מספר הצמתים המינימלי והמקסימלי במאגר. בוחרים באפשרות הזו אם רוצים ש-GKE יוסיף צמתים באופן אוטומטי בזמן עלייה בביקוש, ויסיר צמתים כשהסוכנים מושעים. אפשר לדלג על האפשרות הזו אם אתם מעדיפים מספר קבוע של צמתים עם עלויות צפויות של מחשוב.
  • הדגמה של מונה: פריסה של עומס עבודה לדוגמה שמדגים השהיה ושחזור של סוכן. בוחרים באפשרות הזו אם רוצים לבדוק את האשכול אחרי ההתקנה. פרטים נוספים זמינים במאמר בנושא התנסות בהדגמה של מונה.

אימות ההתקנה

כדי לוודא שההתקנה בוצעה בהצלחה ורכיבי הליבה פועלים, מריצים את הפקודות הבאות ומוודאים שכל ה-Pods הם בסטטוס Running:

kubectl get pods -n ate-system
kubectl get pods -n podcertificate-controller-system

תוויות וגרסאות של צמתים

התוכנה להתקנה מחילה את התווית ate.dev/substrate-version על כל צומת באשכול. התווית הזו מציינת איזו גרסה של Agent Substrate מותקנת באשכול, ו-Agent Substrate מפעיל Workers רק בצמתים שיש להם את תווית הגרסה הזו.

כדי לבדוק איזו גרסה של Agent Substrate מותקנת באשכול, מריצים את הפקודה הבאה:

kubectl get ds -n ate-system -l app=atelet -L ate.dev/substrate-version

כדאי לשים לב לפרטים הבאים לגבי תיוג צמתים:

  • מאגרי עובדים: כשיוצרים WorkerPool, מגדירים אותו כך שיטרגט את תג הגרסה הזה. דוגמאות מופיעות במאמר Pin pools to the installed substrate version במדריך Substrate API.
  • צמתים חדשים: תוכנת ההתקנה מסמנת צמתים בודדים ולא מאגר צמתים. לכן, כל צומת חדש שנוסף אחרי ההתקנה – גם במאגר צמתים שנוצר על ידי כלי ההתקנה – מתחיל בלי תווית הגרסה. כדאי להוסיף תווית למאגר הצמתים של GKE כדי שצמתים חדשים יקבלו את התווית באופן אוטומטי.

התנסות בהדגמה של מונה

אם בחרתם לפרוס את הדמו של Counter כשנשאלתם על ידי תוכנת ההתקנה, תוכלו לראות את היכולות של Agent Substrate להשהות ולשחזר. ההדגמה מפעילה שרת אינטרנט קטן ששומר את הספירה בזיכרון.

אחרי פריסת WorkerPool ו-ActorTemplate של ההדגמה, תוכנת ההתקנה מדפיסה את הפקודות שצריך כדי ליצור Actor מ-ActorTemplate וכדי לשלוח בקשה ל-Actor הזה. במאגר Agent Substrate של מעלה הזרם, בקובץ Counter demo README מוסבר מה צריך לעשות בשלב הבא.

הסרת ההתקנה של Agent Substrate

כשההתקנה מסתיימת והמתקין יוצא, הוא מדפיס פקודות ניקוי מותאמות אישית לסביבה שלכם.

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

  • הסרת Agent Substrate מקלאסטר קיים: אם התקנתם בקלאסטר קיים ואתם רוצים לשמור את הקלאסטר ואת עומסי העבודה האחרים שלו, אתם יכולים למחוק רק את רכיבי Agent Substrate. לשם כך, מריצים את הפקודה ate-setup delete ate-system שהתוכנה להתקנה מדפיסה. התוכנה להתקנה מאכלסת מראש את הפקודה הזו עם ערכי הפרויקט, האשכול והמיקום שהוגדרו במהלך ההתקנה.

  • מחיקת כל המשאבים (כולל האשכול): כדי למחוק את אשכול GKE, את קטגוריית התמונות, את הקישורים של IAM ואת לוחות הבקרה, מריצים את הפקודה cleanup-gcp שהתוכנה להתקנה מדפיסה. התוכנה להתקנה מאכלסת מראש את הפקודה הזו עם ערכי הפרויקט, האשכול, המיקום והקטגוריה שהוגדרו במהלך ההתקנה. פרטים נוספים זמינים בקטע 'הסרת התשתית' בקובץ ה-README של substrate-gke.

המאמרים הבאים