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

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

יצירה ועריכה של 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 משפיע על הגדרות ההפעלה בו-זמנית. אם מגדירים ערך שהוא פחות מ-1 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. אפשר להשתמש בשם מלא של הרשת או המחבר, או במזהה. שימוש במזהים מאפשר ניידות בין סביבות ביניים וסביבות ייצור עם מחברים או רשתות שונים.

הגדרת תעבורת נתונים יוצאת (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.