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

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

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

לפעמים צריך לבצע הגדרות נוספות בתהליך 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 שמכילים משתני סביבה פועלים עם App Hosting.

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

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

פקודות לניהול בסיסי של קצה עורפי של 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.