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

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

יצירה ועריכה apphosting.yaml

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

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

firebase init apphosting

פעולה זו יוצרת קובץ apphosting.yaml בסיסי עם תצורה לדוגמה (בתוך הערות). אחרי העריכה, קובץ apphosting.yaml טיפוסי יכול להיראות כך, עם הגדרות לשירות Cloud Run של ה-Backend, כמה משתני סביבה וכמה הפניות לסודות שמנוהלים על ידי 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.firebasestorage.app
    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 כדי להגדיל את מגבלת הזיכרון:

  • כדי להשתמש בזיכרון של יותר מ-4GiB, צריך לפחות 2 מעבדים
  • כדי להשתמש בנפח של יותר מ-8GiB, צריך לפחות 4 מעבדים
  • אם הזיכרון גדול מ-16GiB, צריך לפחות 6 מעבדים
  • כדי להשתמש בזיכרון של יותר מ-24GiB, צריך לפחות 8 מעבדים

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

הגדרת הסביבה

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

env:
-   variable: STORAGE_BUCKET
    value: mybucket.firebasestorage.app

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

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

env:
-   variable: STORAGE_BUCKET
    value: mybucket.firebasestorage.app
    availability:
    -   BUILD
    -   RUNTIME

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

env:
-   variable: NEXT_PUBLIC_STORAGE_BUCKET
    value: mybucket.firebasestorage.app
    availability:
    -   BUILD
    -   RUNTIME

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

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

ביטול של סקריפטים ל-build ולהרצה

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

scripts:
  buildCommand: next build --no-lint
  runCommand: node dist/index.js

פקודת ה-build שמבטלת את ההגדרות הקודמות מקבלת עדיפות על פני כל פקודת build אחרת, וגורמת לכך שהאפליקציה לא תשתמש במתאמי המסגרת וכל האופטימיזציות הספציפיות למסגרת ש-App Hosting מספקת יושבתו. הכי מומלץ להשתמש בשיטה הזו אם המתאמים לא תומכים היטב בתכונות של האפליקציה. אם רוצים לשנות את פקודת ה-build אבל עדיין להשתמש במתאמים שסיפקנו, צריך להגדיר את סקריפט ה-build ב-package.json, כמו שמתואר במאמר מתאמי framework‏ App Hosting.

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

הגדרת פלט ה-build

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

outputFiles:
  serverApp:
    include: [dist, server.js]

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

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

מידע רגיש כמו מפתחות 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

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

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

הגדרת גישה ל-VPC

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

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

runConfig:
  vpcAccess:
    egress: PRIVATE_RANGES_ONLY # Default value
    networkInterfaces:
      # Specify at least one of network and/or subnetwork
      - network: my-network-id
        subnetwork: my-subnetwork-id

ניהול מערכות עורפיות

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

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

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

מסוף Firebase: בתפריט Build (פיתוח), בוחרים באפשרות App Hosting (אירוח אפליקציות) ואז באפשרות Get started (תחילת העבודה).

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

firebase apphosting:backends:create --project PROJECT_ID

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

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

    בדרך כלל זה המקום שבו נמצא קובץ ה-package.json.

  • הגדרת הענף של השידור החי

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

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

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

  • נותנים שם לשרת העורפי.

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

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

מסוף Firebase: בתפריט הגדרות, בוחרים באפשרות מחיקת ה-Backend.

‫CLI: (גרסה 13.15.4 ואילך)

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

    firebase apphosting:backends:delete BACKEND_ID --project PROJECT_ID

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

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