הגדרה וניהול של קצוות עורפי של אירוח אפליקציות

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

הגדרת קצה עורפי

כדי להגדיר פרטים מתקדמים כמו משתני סביבה או הגדרות של זמן ריצה, כמו מגבלות על בו-זמניות, מעבד (CPU) וזיכרון, צריך ליצור ולערוך את הקובץ apphosting.yaml בתיקיית השורש של האפליקציה. הקובץ הזה תומך גם בהפניות לסודות שמנוהלים באמצעות Cloud Secret Manager, כך שאפשר להעביר אותו בבטחה למערכת לניהול גרסאות.

כדי ליצור את apphosting.yaml, מריצים את הפקודה הבאה:

firebase init apphosting

הפקודה הזו יוצרת קובץ apphosting.yaml בסיסי להתחלה עם תצורה לדוגמה (עם הערות). אחרי העריכה, קובץ apphosting.yaml טיפוסי עשוי להיראות כך, עם הגדרות לשירות Cloud Run בקצה העורפי, כמה משתני סביבה והפניות מסוימות לסודות שמנוהלים על ידי Cloud Secret Manager:

# Settings for Cloud Run
runConfig:
  minInstances: 2
  maxInstances: 100
  concurrency: 100
  cpu: 2
  memoryMiB: 1024

# Environment variables and secrets
env:
  - variable: STORAGE_BUCKET
    value: mybucket.appspot.com
    availability:
      - BUILD
      - RUNTIME

  - variable: API_KEY
    secret: myApiKeySecret

    # Same as API_KEY above but with a pinned version.
  - variable: PINNED_API_KEY
    secret: myApiKeySecret@5

    # Same as API_KEY above but with the long form secret reference as defined by Cloud Secret Manager.
  - variable: VERBOSE_API_KEY
    secret: projects/test-project/secrets/secretID

    # Same as API_KEY above but with the long form secret reference with pinned version.
  - variable: PINNED_VERBOSE_API_KEY
    secret: projects/test-project/secrets/secretID/versions/5

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

הגדרת הגדרות השירות של Cloud Run

בעזרת ההגדרות של apphosting.yaml תוכלו לקבוע איך השירות של Cloud Run יוקצה. ההגדרות הזמינות לשירות Cloud Run מפורטות באובייקט runConfig:

  • cpu – מספר המעבדים (CPU) שבהם נעשה שימוש בכל מכונה להצגת תוכן (ברירת המחדל היא 0).
  • memoryMiB – נפח הזיכרון שהוקצה לכל מכונה להצגת מודעות ב-MiB (ברירת המחדל היא 512)
  • maxInstances – המספר המקסימלי של קונטיינרים שפועלים בו-זמנית (ברירת המחדל היא 100, והם מנוהלים לפי מכסה)
  • minInstances – מספר הקונטיינרים שתמיד יישארו פעילים (ברירת המחדל היא 0).
  • concurrency – מספר הבקשות המקסימלי שכל מכונה להצגת מודעות יכולה לקבל (ברירת המחדל היא 80).

חשוב לשים לב לקשר החשוב בין cpu ל-memoryMiB. אפשר להגדיר את הזיכרון לכל ערך שלם בין 128 ל-32768, אבל כדי להגדיל את מגבלת הזיכרון יכול להיות שיהיה צורך להגדיל את מגבלות המעבד:

  • יותר מ-4GB דורשים לפחות 2 מעבדים (CPU)
  • כדי להשתמש ב-8GB זיכרון או יותר, נדרשים לפחות 4 מעבדים
  • כדי להשתמש ב-16GB זיכרון או יותר, נדרשים לפחות 6 מעבדים
  • יותר מ-24GB דורשים לפחות 8 מעבדים (CPU)

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

הגדרת סביבת ה-build

לפעמים תצטרכו הגדרות נוספות לתהליך ה-build, כמו מפתחות API של צד שלישי או הגדרות שניתן לשנות. ב-App Hosting יש הגדרת סביבה ב-apphosting.yaml כדי לאחסן ולשלוף את סוג הנתונים הזה בפרויקט.

env:
-   variable: STORAGE_BUCKET
    value: mybucket.appspot.com

באפליקציות Next.js, קובצי dotenv שמכילים משתני סביבה יפעלו גם עם App Hosting. מומלץ להשתמש ב-apphosting.yaml כדי לשלוט באופן מפורט במשתני הסביבה בכל מסגרת.

ב-apphosting.yaml, אפשר לציין אילו תהליכים יש להם גישה למשתנה הסביבה באמצעות המאפיין availability. אפשר להגביל את הזמינות של משתנה סביבה לסביבת ה-build בלבד או לסביבת זמן הריצה בלבד. כברירת מחדל, הוא זמין לשניהם.

env:
-   variable: STORAGE_BUCKET
    value: mybucket.appspot.com
    availability:
    -   BUILD
    -   RUNTIME

באפליקציות Next.js, אפשר גם להשתמש בתחילית NEXT_PUBLIC_ באותו אופן שבו משתמשים בה בקובץ dotenv כדי לאפשר גישה למשתנה בדפדפן.

env:
-   variable: NEXT_PUBLIC_STORAGE_BUCKET
    value: mybucket.appspot.com
    availability:
    -   BUILD
    -   RUNTIME

מפתחות משתנים תקינים מורכבים מתווים A-Z או מקווים תחתונים. חלק ממפתחות משתני הסביבה שמורים לשימוש פנימי בלבד. אין להשתמש באף אחד מהמפתחות האלה בקובצי התצורה:

  • כל משתנה שמתחיל ב-X_FIREBASE_
  • PORT
  • K_SERVICE
  • K_REVISION
  • K_CONFIGURATION

אחסון פרמטרים סודיים וגישה אליהם

מידע רגיש כמו מפתחות API צריך להיות מאוחסן כסודות. אפשר להפנות לסודות ב-apphosting.yaml כדי להימנע מהכנסת מידע רגיש למערכת בקרת הגרסאות.

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

  -   variable: API_KEY
      secret: myApiKeySecret

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

  - variable: PINNED_API_KEY
    secret: myApiKeySecret@5

אפשר ליצור סודות באמצעות הפקודה firebase apphosting:secrets:set ב-CLI, ותתבקשו להוסיף את ההרשאות הנדרשות. התהליך הזה מאפשר לכם להוסיף את ההפניה הסודית ל-apphosting.yaml באופן אוטומטי.

כדי להשתמש בחבילת הפונקציונליות המלאה של Cloud Secret Manager, אפשר להשתמש במקום זאת במסוף Cloud Secret Manager. אם תעשו זאת, תצטרכו להעניק הרשאות לקצה העורפי של App Hosting באמצעות פקודת ה-CLI firebase apphosting:secrets:grantaccess.

סנכרון המצב של Firebase Auth

באפליקציות שמשתמשות באימות של Firebase, מומלץ להשתמש ב-Firebase Web SDK כדי לשמור על סנכרון של מצב האימות בין הלקוח לשרת. כדי לעשות זאת, אפשר להטמיע את FirebaseServerApp באמצעות שירות עובד (service worker). תהליך המשימה הבסיסי הוא:

  1. מטמיעים קובץ שירות (service worker) שמוסיף את הכותרות המתאימות לאפליקציה בבקשות לשרת.
  2. מקבלים את הכותרות מהבקשה בשרת וממירים אותן למשתמש מאומת באמצעות FirebaseServerApp.

ניהול הקצוות העורפיים

פקודות לניהול בסיסי של הקצוות העורפי של App Hosting זמינות ב-CLI של Firebase. חלק מהפעולות זמינות גם במסוף Firebase. בקטע הזה מתוארות כמה מהמשימות הנפוצות יותר בניהול, כולל יצירת קצות עורפי ומחיקה שלהם.

יצירת קצה עורפי

הקצה העורפי של App Hosting הוא האוסף של המשאבים המנוהלים שנוצרים על ידי App Hosting כדי ליצור ולהפעיל את אפליקציית האינטרנט. אפשר ליצור ולפרט את הקצוות העורפיים של App Hosting באמצעות מסוף Firebase או CLI של Firebase.

מסוף Firebase: בתפריט Build, בוחרים באפשרות App Hosting ואז באפשרות Get started.

CLI: (גרסה 13.15.4 ואילך) כדי ליצור קצה עורפי, מריצים את הפקודה הבאה מהשורש של ספריית הפרויקט המקומי, ומספקים את projectID ואת region המועדף כארגומנטים:

firebase apphosting:backends:create --project PROJECT_ID --location us-central1

במסוף או ב-CLI, פועלים לפי ההנחיות כדי להקצות שם לקצה העורפי, להגדיר חיבור ל-GitHub ולהגדיר את הגדרות הפריסה הבסיסיות הבאות:

  • מגדירים את ספריית השורש של האפליקציה (ברירת המחדל היא /)

    בדרך כלל זהו המיקום של הקובץ package.json.

  • הגדרת הענף הפעיל

    זו ההסתעפות של מאגר GitHub שמופיעה בכתובת ה-URL הפעילה. לרוב, זהו ההסתעפות שבה מתבצעת המיזוג של ההסתעפויות של התכונות או ההסתעפויות של הפיתוח.

  • אישור או דחייה של השקות אוטומטיות

    השקות אוטומטיות מופעלות כברירת מחדל. בסיום יצירת הקצה העורפי, תוכלו לבחור לפרוס את האפליקציה ב-App Hosting באופן מיידי.

מחיקת קצה עורפי

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

  1. מריצים את הפקודה הבאה כדי למחוק את הקצה העורפי של App Hosting. הפעולה הזו משביתה את כל הדומיינים לקצה העורפי ומוחקת את השירות המשויך Cloud Run:

    firebase apphosting:backends:delete BACKEND_ID --project PROJECT_ID --location us-central1

  2. (אופציונלי) בכרטיסייה של Artifact Registry במסוף Google Cloud, מוחקים את התמונה של הקצה העורפי בקטע firebaseapphosting-images.

  3. ב-Cloud Secret Manager, מוחקים את כל הסודות שכוללים את 'apphosting' בשם הסוד, תוך הקפדה מיוחדת לוודא שאין שימוש בסודות האלה על ידי קצוות עורפיים אחרים או היבטים אחרים של פרויקט Firebase.