התקנת 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 של אחסון בדיסק מתמיד (persistent disk), וזה לא מספיק להתקנה. צריך להריץ את קובץ ההתקנה במחשב המקומי.
  • מצב אשכול: אפשר להתקין את Agent Substrate רק באשכולות GKE Standard. אין תמיכה באשכולות Autopilot.
  • אשכולות קיימים וממשקי API בגרסת בטא: אי אפשר להפעיל את ממשקי ה-API הנדרשים בגרסת בטא (podcertificaterequests ו-clustertrustbundles) באשכול קיים. אם מתקינים באשכול קיים שפועלת בו גרסה 1.36, צריך לוודא שממשקי ה-API האלה הופעלו כשנוצר האשכול.
  • סוגי מכונות: אי אפשר להשתמש בסדרות מכונות שפועלות על ארכיטקטורות מעורבות של מעבדים (כמו סוגי מכונות 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).
  • פועלת בגרסה 1.36 של GKE (עם הפעלת דגלי בטא) או בגרסה 1.37 ואילך.
  • משתמש בסוגי מכונות בגודל c3-standard-4 או גדול יותר לצמתים.
  • ממשקי ה-API של Kubernetes‏ PodCertificateRequest ו-ClusterTrustBundle מופעלים (certificates.k8s.io/v1beta1/podcertificaterequests ו-certificates.k8s.io/v1beta1/clustertrustbundles). ממשקי ה-API האלה זמינים בגרסה כללית ב-Kubernetes בגרסה 1.37 ואילך, כלומר הם מופעלים בכל אשכול שפועלת בו גרסה 1.37 ואילך. צריך להפעיל אותם באופן ידני רק באשכולות קיימים שפועלות בהם גרסאות תיקון של גרסה 1.36. הוראות מפורטות מופיעות במאמר הפעלת ממשקי API בגרסת בטא באשכול קיים.

התקנת Agent Substrate

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

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

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

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

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

  • תמונות מוכנות מראש: משיכת תמונות שפורסמו מ-Container Registry. מכיוון שלא נבנה או נדחף שום דבר, לא צריך מאגר תמונות משלו לפרויקט Google Cloud .
  • Build from source (יצירת גרסת build ממקור): יוצר גרסאות build של התמונות ממאגר 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): מאפשרים לממשקי Kubernetes beta APIs האלה להנפיק אישורים לתקשורת TLS בין רכיבי Agent Substrate.
    • ‫Managed OpenTelemetry: אוסף מדדים ומעקבים מהאשכול.
  3. יוצר את הקטגוריה של Cloud Storage שבה Agent Substrate כותב את התמונות שלכם.
  4. מעניק לסוכן Substrate גישה ל-Cloud Storage כדי לאחסן תמונות מצב. אם בוחרים ליצור מ-source, מקבלים גם גישה ל-Artifact Registry לקובצי אימג' של קונטיינרים.
  5. יוצרת לוחות בקרה של Cloud Monitoring שמציגים תרשימים של זמן האחזור של ניתוב Agent Substrate, גודל התמונה ונתוני התעבורה של gRPC.

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

  1. הוספה של קבוצת ה-API והמשאבים של Agent Substrate לאשכול. אלה משאבים מותאמים אישית של 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 באשכול קיים, מריצים את קובץ ההתקנה ובוחרים באפשרות Upgrade an installed cluster (שדרוג של אשכול מותקן). פרטים נוספים מופיעים בקובץ 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.

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