פריסת אפליקציות במהירות באמצעות Application Design Center

1. מבוא

ב-Codelab הזה נסביר איך לפרוס אפליקציית פול סטאק באמצעות Application Design Center (ADC) של Google Cloud. תפרסו את האפליקציה The Cymbal London Concierge, שכוללת חזית עורפית (frontend) של Vue 3, קצה אחורי (backend) של FastAPI ושרת MCP שמכיל את הנתונים של האפליקציה.

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

הפעולות שתבצעו:

• מגדירים את Application Design Center.
• הרכבת רכיבי האפליקציה באופן ויזואלי.
• פורסים את ארכיטקטורת האפליקציה.
• מאמתים את האפליקציה שפועלת.
• מוודאים שהאפליקציה נרשמה במרכז האפליקציות.
• מאמתים את מדדי האפליקציה, העקבות והיומנים ב'ניטור אפליקציות'.

הדרישות

• דפדפן אינטרנט כמו Chrome.
• פרויקט ב-Google Cloud שהחיוב בו מופעל.

שיעור ה-Codelab הזה מיועד למפתחים בכל הרמות, כולל מתחילים.

משך משוער: 45 דקות עלות משוערת: פחות מ-2.00$

2. הגדרה

הגדרת הפרויקט

יצירת פרויקט ב-Google Cloud

1. במסוף Google Cloud, בדף לבחירת הפרויקט, בוחרים פרויקט ב-Google Cloud או יוצרים פרויקט.
2. הקפידו לוודא שהחיוב מופעל בפרויקט שלכם ב-Cloud. כך בודקים אם החיוב מופעל בפרויקט

הפעלת Cloud Shell

‫Cloud Shell היא סביבת שורת פקודה שפועלת ב-Google Cloud וכוללת מראש את הכלים הנדרשים.

1. לוחצים על Activate Cloud Shell בחלק העליון של מסוף Google Cloud.
2. אחרי שמתחברים ל-Cloud Shell, מאמתים את האימות:

   gcloud auth list
   

3. מוודאים שהפרויקט מוגדר:

   gcloud config get project
   

4. אם הפרויקט לא מוגדר כמו שציפיתם, מגדירים אותו:

   export PROJECT_ID=<YOUR_PROJECT_ID>
   gcloud config set project $PROJECT_ID
   

3. הגדרת Application Design Center

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

1. במסוף Google Cloud, מחפשים את Application Design Center ועוברים אליו.
2. אם זו הפעם הראשונה שאתם משתמשים ב-ADC בפרויקט הזה, יוצג לכם מסך הגדרה.
3. לוחצים על Go to Setup (מעבר להגדרה).

4. אם ממשקי ה-API הנדרשים לא מופעלים, תופיע בקשה להפעיל אותם. לוחצים על הפעלה כדי להמשיך.

4. התכונות של ADC

במשימה הזו תלמדו על הרכיבים העיקריים של ADC: מרחבים, קטלוגים ותבניות.

מרחבים ב-ADC

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

כדי לראות את המרחבים דרך הטרמינל, מבצעים את השלבים הבאים:

1. לוחצים על Open Editor בסרגל הכלים של Cloud Shell או משתמשים בטרמינל.
2. מריצים את הפקודה הבאה:

gcloud alpha design-center spaces list \
--project="your PROJECT ID" \
--location=us-central1

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

createTime: '20XXXX-XX-XXT09:19:29.456016967Z'
displayName: default-space
enableGcpSharedTemplates: true
name: projects/your-project-id/locations/us-central1/spaces/default-space

5. הרכבת התבנית

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

1. יצירת עיצוב חדש

1. במסוף ADC, לוחצים על Templates > Create Template.
2. נותנים שם לתבנית simple-3-tier-agentic-app כי התבנית הזו תשמש לפריסת האפליקציה Cymbal London Concierge ולאפליקציות דומות אחרות.

2. הוספת שרת ה-MCP של הנתונים

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

1. לוחצים על הוספת רכיב > Cloud Run (שירות). אם לוחצים על הרכיב הזה, מזהה הרכיב component id מופיע בפינה השמאלית העליונה. הפורמט יהיה cloud-run-1. אפשר לשנות את זה ל-data-mcp-server על ידי עריכה בתצוגת הקוד (שנרחיב עליה בהמשך), אבל נשאיר את זה כמו שזה.
2. מזינים את שם השירות: data-mcp-server.
3. בקטע הצגת הגדרות מתקדמות, מגדירים את החברים ל: allUsers. (הערה: בסביבת ייצור, סביר להניח שתגבילו את זה, אבל אנחנו משתמשים בזה כאן כדי לפשט את ה-codelab).
4. בקטע הצגת הגדרות מתקדמות, מגדירים את VPC ACCESS ואת Egress כך: PRIVATE_RANGES_ONLY.
5. אופציונלי: בקטע הצגת הגדרות מתקדמות, מבטלים את הסימון של הפעלת Prometheus Sidecar.
6. לוחצים על שמירה.

3. הוספת קצה העורפי של הסוכן

זו אפליקציית FastAPI שמנהלת את ההתנהגות האקטיבית.

1. לוחצים על הוספת רכיב > Cloud Run (שירות).
2. נותנים לו את השם agent-backend.
3. בקטע הצגת שדות מתקדמים, מסמנים את האפשרות יצירת חשבון שירות ומוסיפים את התפקידים הבאים בקטע תפקידים בפרויקט של חשבון השירות, אחד בכל פעם:
   • roles/monitoring.metricWriter
   • roles/logging.logWriter
   • roles/cloudtrace.agent
   • roles/telemetry.writer
   • roles/serviceusage.serviceUsageConsumer. התפקידים האלה יאפשרו לסוכן להשתמש ב-Cloud Monitoring, ב-Cloud Logging וב-Cloud Trace. הגדרת תאימות: צוות הפלטפורמה אוכף את העיקרון של הרשאות מינימליות על ידי רישום מפורש של התפקידים הנדרשים.
   
4. בקטע הצגת הגדרות מתקדמות, מגדירים את החברים ל: allUsers.
5. בקטע הצגת הגדרות מתקדמות, מגדירים את VPC ACCESS ואת Egress כך: PRIVATE_RANGES_ONLY.
6. אופציונלי: בקטע הצגת הגדרות מתקדמות, מבטלים את הסימון של הפעלת Prometheus Sidecar.
7. מחברים את agent-backend אל data-mcp-server על ידי גרירת קו חיבור מ-agent-backend אל data-mcp-server.
8. לוחצים על שמירה.

4. הוספת קצה קדמי

ממשק קצה

1. לוחצים על הוספת רכיב > Cloud Run (שירות).
2. מזינים את שם השירות: frontend.
3. בקטע הצגת הגדרות מתקדמות, מבטלים את הסימון של יצירת חשבון שירות.
4. בקטע הצגת הגדרות מתקדמות, מגדירים את הכניסה לערך INGRESS_TRAFFIC_INTERNAL_LOADBALANCER. הגדרת תאימות: גישה ציבורית ישירה למאגר הקצה הקדמי חסומה, והתנועה עוברת דרך איזון העומסים.
5. בקטע הצגת הגדרות מתקדמות, מגדירים את החברים ל: allUsers.
6. אופציונלי: בקטע הצגת הגדרות מתקדמות, מבטלים את הסימון של הפעלת Prometheus Sidecar.
7. לוחצים על שמירה.
8. מחברים את frontend אל agent-backend על ידי גרירת קו חיבור מ-frontend אל agent-backend.

5. הוספת רכיב Vertex AI

1. לוחצים על הוספת רכיב > Vertex AI.
2. נותנים לו את השם vertex-ai.
3. מחברים אותו ל-agent-backend ול-data-mcp-server על ידי גרירת שני חיבורים מ-vertex-ai ל-agent-backend ול-data-mcp-server בהתאמה. התפקידים aiplatform.user כבר יוקצו לחשבונות השירות של agent-backend ושל data-mcp-server, כי הם מקושרים לרכיב Vertex AI.

6. הוספת מאזן עומסים גלובלי

מאזן העומסים חושף את חזית האתר שלכם לאינטרנט הציבורי. ב-ADC, הרכיב הזה מחולק לרכיב Backend ולרכיב Frontend.

א. הוספת קצה עורפי של מאזן עומסים

1. לוחצים על **Add Component > Global Cloud Load Balancing (Backend).
2. נותנים לו את השם galb-backend.
3. לוחצים על הוספת חיבור ומקשרים אותו אל frontend.

ב. הוספת חזית של מאזן עומסים

1. לוחצים על **Add Component > Global Cloud Load Balancing (Frontend).
2. נותנים לו את השם galb-frontend.
3. לוחצים על הוספת חיבור ומקשרים אותו אל galb-backend.
4. מחברים את galb-frontend אל galb-backend על ידי גרירת קו חיבור מ-galb-frontend אל galb-backend.

שיתוף התבנית בקטלוג

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

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

1. לוחצים על הכרטיסייה קטלוגים.
2. לוחצים על הוספת תבניות ובוחרים את התבנית simple-3-tier-agentic-app.
3. לוחצים על הוספה לקטלוג.

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

6. פריסת האפליקציה

עכשיו הגיע הזמן לשחק בתפקיד של מפתח אפליקציות שרוצה להשתמש בתבנית הזו כדי לפרוס את האפליקציה cymbal-london-concierge.

1. במסוף ADC, פותחים מחדש את התבנית בכרטיסייה Templates (תבניות) ולוחצים על הלחצן Configure app (הגדרת האפליקציה).
2. לוחצים על יצירת אפליקציה חדשה.
3. מגדירים את האפליקציה:
   • שם האפליקציה: cymbal-london-concierge
   • פרויקט הפריסה: מזהה הפרויקט
   • אזור: us-central1
   • מאפייני קלט> סביבה: Development
   • מאפייני קלט>חשיבות: Low
4. לוחצים על Create Application (יצירת אפליקציה). כדי לפרוס בסביבת ייצור, בוחרים באפשרות Production (ייצור) בשדה Environment (סביבה) ובאפשרות High (גבוהה) בשדה Criticality (חשיבות). אלה תגים שיעזרו למהנדסי ה-SRE ולצוות התפעול למיין ולתעדף את העבודה על בעיות שמתרחשות.
5. ייפתח דף פרטי הפריסה עם תבנית האפליקציה. מכיוון שזו רק תבנית, עדיין צריך להוסיף הגדרה שספציפית לאפליקציה שלנו.
6. נתחיל להגדיר את הקצה הקדמי. לוחצים על הרכיב frontend.
   1. לוחצים על מאגרי תגים > עריכת מאגר תגים.
   2. צריך להחליף את קובץ האימג' של הקונטיינר הגנרי בקובץ האימג' שרוצים להשתמש בו לאפליקציה.
   3. מגדירים את Container Image (קובץ אימג' של קונטיינר) לערך: us-central1-docker.pkg.dev/o11y-movie-guru/london-travel-agency/frontend:codelab-c2c6-v1
   4. מגדירים את היציאה http1 לערך 80.
   5. מגדירים את משתני הסביבה הבאים:
      • ‫API_BASE_URL: module.cloud-run-2.service_uri (חשוב לוודא ש-cloud-run-2 הוא השם של רכיב ה-Backend של הסוכן. אם לא, צריך להחליף אותו בשם האמיתי של הרכיב)
   6. לוחצים על שמירה.
7. נתחיל להגדיר את הקצה העורפי של הסוכן. לוחצים על הרכיב agent-backend.
   1. לוחצים על מאגרי תגים > עריכת מאגר תגים.
   2. צריך להחליף את קובץ האימג' של הקונטיינר הגנרי בקובץ האימג' שרוצים להשתמש בו לאפליקציה.
   3. מגדירים את Container Image (קובץ אימג' של קונטיינר) לערך us-central1-docker.pkg.dev/o11y-movie-guru/london-travel-agency/agent:codelab-c2c6-v1.
   4. מגדירים את משתני הסביבה הבאים:
   5. GOOGLE_CLOUD_PROJECT:
   6. GOOGLE_CLOUD_LOCATION: us-central1
   7. ‫DATA_BACKEND_URL: module.cloud-run-1.service_uri (חשוב לוודא ש-cloud-run-1 הוא השם של רכיב השרת של ה-MCP של הנתונים. אם לא, צריך להחליף אותו בשם בפועל של הרכיב)
   8. מגדירים את היציאה http1 לערך 8000.
   9. לוחצים על שמירה.
8. בואו נגדיר את שרת ה-MCP של הנתונים. לוחצים על הרכיב data-mcp-server.
   1. לוחצים על מאגרי תגים > עריכת מאגר תגים.
   2. צריך להחליף את קובץ האימג' של הקונטיינר הגנרי בקובץ האימג' שרוצים להשתמש בו לאפליקציה.
   3. מגדירים את Container Image (קובץ אימג' של קונטיינר) לערך us-central1-docker.pkg.dev/o11y-movie-guru/london-travel-agency/data_mcp:codelab-c2c6-v1.
   4. מגדירים את משתני הסביבה הבאים:
   5. GOOGLE_CLOUD_PROJECT:
   6. GOOGLE_CLOUD_LOCATION: ‏us-central1
   7. DB_TYPE: ‏sqlite
   8. EMBEDDING_MODEL: text-embedding-005
   9. מגדירים את היציאה http1 לערך 8002.
   10. לוחצים על שמירה.
   בתרחיש ייצור אמיתי, צריך גם להגדיר מסד נתונים כמו CloudSQL או AlloyDB ולספק את מחרוזת החיבור למסד הנתונים עבור שרת ה-MCP של הנתונים. אבל בשיעור ה-Lab הזה נשתמש במסד נתונים בזיכרון. כדאי גם להגדיר את שרת ה-MCP ואת מסד הנתונים כפרטיים, כך שהגישה אליהם תתאפשר רק מהקצה העורפי של Agent או מתוך הרשת.
9. לוחצים על הלחצן Code (קוד) בחלק העליון של הדף כדי לראות את קוד ה-Terraform של האפליקציה. אפשר גם להוריד את קוד ה-Terraform של האפליקציה על ידי לחיצה על הלחצן קבלת קוד כדי לאחסן אותו בבסיס הקוד.
10. לוחצים על הלחצן Deploy (פריסה) בפינה השמאלית העליונה של הדף כדי לפרוס את האפליקציה.
11. בדף הפריסה תתבקשו ליצור חשבון שירות לפייפליין הפריסה או לבחור חשבון קיים. לוחצים על Create Service Account (שם ימולא אוטומטית) ואז על Proceed. ייקח כמה שניות ליצור חשבון שירות חדש.

12. אחרי שיוצרים את חשבון השירות, הדף מתרענן ומופיע סימן וי ליד האפשרות Select Service Account.

13. אחר כך לוחצים על פריסה בתחתית הדף.
14. התהליך יימשך כמה דקות. אחרי שהפריסה תושלם, יופיע סימן וי ירוק ליד כל רכיב. אפשר גם לבדוק את סטטוס הפריסה בלחיצה על הלחצן קישור ליומנים, שפותח את יומני ה-build בענן. יכול להיות שיחלפו כמה דקות עד שהלחצן יופיע.

![Deployment Logs](./img/10b_logs.png)

15. אפשר לראות את יומני ה-Cloud Build כדי לבדוק את סטטוס הפריסה או אם יש שגיאות שעלולות להתרחש בזמן פריסת האפליקציה. אפשר גם לעבור ישירות ליומני ה-Build בענן על ידי חיפוש של Cloud Build במסוף Google Cloud ולחיצה על היסטוריה. פריסת האפליקציה תימשך כ-5-8 דקות.

![Cloud Build](./img/10c_cloudbuild.png)

16. בסיום הפריסה, יופיע סימן וי ירוק ליד השדה סטטוס הפריסה.

![Deployment Complete](./img/11_deployed.png)

7. אימות האפליקציה

בואו נבדוק אם הסוכן פעיל. בקטע outputs בדף פרטי הפריסה, תופיע כתובת ה-URL של רכיב ה-frontend. מעתיקים את כתובת ה-URL ומדביקים אותה בדפדפן. חשוב להשתמש ב-http ולא ב-https. בנוסף, צריך לאשר את כל האזהרות שמופיעות בדפדפן כי ה-frontend משתמש ב-http.

משוחחים עם האפליקציה ומבקשים ממנה ליצור מסלול לטיול בלונדון.

8. מרכז האפליקציות ומעקב אחרי אפליקציות

1. במסוף ADC, לוחצים על הלחצן View app in App Hub (הצגת האפליקציה במרכז האפליקציות) בפינה השמאלית העליונה של הדף.

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

3. לוחצים על הלחצן View in Observability (הצגה ב-Observability). האפליקציה אמורה להיפתח במסוף Observability.
4. פותחים את תצוגת מרכז הבקרה. לוח הבקרה מספק סקירה כללית של הביצועים והתקינות של האפליקציה באמצעות מדדים כמו 4 אותות הזהב: קצב הבקשות, שיעור השגיאות, זמן האחזור והרוויה. המעקב הזה, שמתמקד באפליקציה, חיוני לשמירה על מהימנות. אפשר גם להציג את היומנים והעקבות של האפליקציה, כדי להשוות בין האותות ולזהות צווארי בקבוק. זה חשוב במיוחד באפליקציה מורכבת כמו זו, שבה תגובות איטיות מ-Vertex AI או משרת ה-MCP של הנתונים עלולות לפגוע בחוויית המשתמש.

5. הסבר מודרך: שואלים את הסוכן שאלה ספציפית באפליקציה (לדוגמה, "What are the best places to visit in London?‎"). לאחר מכן, חוזרים למסוף Observability וצופים ברשימה Traces. מאתרים את המעקב שמתאים לבקשה. כדי לראות את תצוגת המפל המפורטת, לוחצים עליו. שימו לב שאפשר לראות את הזמן שחלף בקצה הקדמי, בבק-אנד של הסוכן ובקריאות ל-Vertex AI. כך תוכלו לזהות בדיוק איפה נוצר זמן טעינה.

9. מזל טוב

מעולה! פרסתם ארכיטקטורת אפליקציה בת 3 רמות באמצעות ADC.

מה למדתם

• איך מרכיבים חזותית ארכיטקטורת ענן באמצעות ADC.
• איך מגדירים ADC ומפעילים ממשקי API באמצעות ממשק המשתמש.
• איך פורסים אפליקציות באמצעות ADC.
• איך משתמשים במרכז האפליקציות כדי לראות את המשאבים שלכם מנקודת מבט של אפליקציה.
• איך עוקבים אחרי תקינות האפליקציה באמצעות לוח הבקרה Observability.

מסמכי עזר

• מסמכי תיעוד של ADC
• מסמכי App Hub
• מעקב אחרי אפליקציות