התקנת Agent Substrate ב-GKE

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

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

תמחור

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

מגבלות

אלה מגבלות ההתקנה של Agent Substrate ב-GKE:

  • ‫Cloud Shell: אי אפשר להתקין את Agent Substrate ב-GKE ב-Cloud Shell כי Cloud Shell מספק 5GB של אחסון בדיסק מתמיד (persistent disk), וזה לא מספיק להתקנה. צריך להריץ את תוכנת ההתקנה במחשב המקומי.
  • מצב אשכול: אפשר להתקין את Agent Substrate ב-GKE רק באשכולות GKE Standard. אין תמיכה באשכולות Autopilot.
  • אשכולות קיימים וממשקי API בגרסת בטא: אם אתם מפעילים את ממשקי ה-API הנדרשים בגרסת בטא (podcertificaterequests ו-clustertrustbundles) באשכול קיים שפועלת בו גרסה 1.36, אתם צריכים להחליף את הצמתים הקיימים לפני שאתם מתקינים את Agent Substrate ב-GKE. בצמתים שנוצרו לפני העדכון, לא מופעלת הקרנה של אישור 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 ב-GKE, בקשו מהאדמין להקצות לכם את התפקידים הבאים ב-IAM בפרויקט:

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

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

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

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

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

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

  • ממשקי ה-API של Kubernetes‏ PodCertificateRequest ו-ClusterTrustBundle מופעלים (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 ב-GKE

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

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

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

  • מזהה פרויקט (חובה): מציינים את Google Cloud הפרויקט שבו יוקצו משאבים. אם הגדרתם פרויקט ברירת מחדל ל-CLI של gcloud, תוכנת ההתקנה תשתמש במזהה הפרויקט הזה.
  • אשכול (חובה): בוחרים אם לאפשר לתוכנת ההתקנה ליצור אשכול GKE חדש עם הגדרות ברירת מחדל מומלצות, או להתקין את Agent Substrate ב-GKE באשכול קיים. אם בחרתם להתקין באשכול קיים, ודאו שהוא עומד בדרישות שמפורטות בקטע דרישות האשכול.
  • קטגוריית תמונת מצב (אופציונלי): מציינים שם מותאם אישית לקטגוריה של 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 באשכול GKE.

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

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

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

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

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

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

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

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

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

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

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

אימות ההתקנה

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

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

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

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

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

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 כדי שצמתים חדשים יקבלו את התווית באופן אוטומטי.

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

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

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

הסרת Agent Substrate ב-GKE

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

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

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

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

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