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

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

הגדרה ועדכון של משתני סביבה

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

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

מסוף Firebase

צילום מסך של תיבת הדו-שיח במסוף Firebase להוספת משתני סביבה

apphosting.yaml

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

עדכון משתנים

אפשר להוסיף ולערוך משתני סביבה במסוף Firebase בכרטיסייה הגדרות של קצה עורפי. עוברים אל View Backend (הצגת קצה העורף) >> Settings (הגדרות) >> Environment (סביבה) ואז מוסיפים, עורכים או מוחקים משתני סביבה.

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

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

הגדרת הזמינות של משתנים

משתני סביבה שנוצרו במסוף Firebase זמינים גם בזמן ה-build וגם בזמן הריצה. זה גם התנאי שמוגדר כברירת מחדל למשתנים שמוגדרים ב-apphosting.yaml, אלא אם צמצמתם את ההיקף באמצעות המאפיין availability. ב-apphosting.yaml (אבל לא במסוף), אפשר להגביל את משתנה הסביבה כך שיהיה זמין רק לסביבת ה-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

קובצי dotenv ל-Next.js

באפליקציות Next.js, קבצים מסוג dotenv שמכילים משתני סביבה פועלים עם אירוח אפליקציות.

כשיוצרים או מעדכנים קצה עורפי, אפשר להעביר משתני סביבה מקובץ dotenv אל מסוף Firebase. לשם כך, מעתיקים ומדביקים את כל התוכן של קובץ dotenv בשדה הראשון Key (מפתח) בטופס Add new (הוספה של משתנה חדש) בהגדרות משתני הסביבה.

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

KEY1=value1
KEY2=value2
KEY3=value3

כדי לשלוט במשתני סביבה בצורה מורכבת או מפורטת בכל מסגרת, מומלץ להשתמש ב-apphosting.yaml.

היררכיית משתנים

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

זהו סדר העדיפות המלא:

  1. מסוף Firebase ← משתנים שהוגדרו במסוף
  2. ‫apphosting.<env>.yaml ← משתנים שצוינו בקובץ yaml ספציפי לסביבה, כמו apphosting.staging.yaml (ראו פריסת כמה סביבות)
  3. ‫apphosting.yaml → משתנים שצוינו בקובץ apphosting.yaml
  4. מערכת Firebase ← משתנים שמוגדרים על ידי Firebase ומכילים ערכים של firebase_config json או firebase_webapp_config, וגם משתני סביבה שמגדירים את שמות המארחים והיציאות של אפליקציות SSR (מוגדרים על ידי מתאמי App Hosting ב-bundle.yaml)

שמות שמורים ומגבלות

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

  • מחרוזות ריקות ("")
  • משתנים שמכילים את התו '='
  • כל משתנה שמתחיל ב-X_FIREBASE_
  • PORT
  • K_SERVICE
  • K_REVISION
  • K_CONFIGURATION
  • מפתחות כפולים

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

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

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

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

ביטול של סקריפטים ל-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. אם תעשו זאת, תצטרכו להעניק הרשאות ל-backend של App Hosting באמצעות פקודת ה-CLI‏ firebase apphosting:secrets:grantaccess.

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

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

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

הגדרת תעבורת נתונים יוצאת (egress) ישירה מ-VPC ‏(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

הגדרת מחבר ללא שרת (apphosting.yaml):

runConfig:
  vpcAccess:
    egress: ALL_TRAFFIC
    connector: connector-id

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

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

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

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

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

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

firebase apphosting:backends:create --project PROJECT_ID

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

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

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

  • הגדרת הענף החי

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

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

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

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

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

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

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

‫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.