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

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

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

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

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

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

הגדרת הסביבה

לפעמים תצטרכו הגדרות נוספות לתהליך ה-build, כמו מפתחות 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 מסיק את הפקודות build ו-start של האפליקציה על סמך המסגרת שזוהתה. אם רוצים להשתמש בפקודת build או פקודת start בהתאמה אישית, אפשר לשנות את הגדרות ברירת המחדל של App Hosting ב-apphosting.yaml.

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

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

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

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

ניהול הקצוות העורפיים

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

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

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

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

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

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

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

   firebase apphosting:backends:delete BACKEND_ID --project PROJECT_ID --location us-central1
   

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

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