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

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

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

כדי להשתמש בהגדרות מתקדמות כמו משתני סביבה או הגדרות זמן ריצה, כמו בו-זמניות (concurrency), מעבד (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, אבל הגדלה של מגבלת הזיכרון עשויה לחייב הגדלת מגבלות של המעבד (CPU):

  • יותר מ-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. לבקרה מפורטת של משתני סביבה באמצעות כל framework מומלץ להשתמש ב-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 Auth כדאי להשתמש ב-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. (אופציונלי) בכרטיסייה של מסוף Google Cloud של Artifact Registry, מוחקים את התמונה של הקצה העורפי ב-"firebaseapphosting-images".

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