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

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

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

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

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

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

עדכון משתנים

אפשר להוסיף, לערוך או למחוק משתני סביבה במסוף Firebase או באמצעות apphosting.yaml:

• Firebase מסוף:

  1. במסוף Firebase, עוברים אל Hosting & Serverless >‏ App Hosting.

  2. עוברים אל View Backend > Settings > Environment.

  3. להוסיף, לערוך או למחוק משתני סביבה.

• 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 בשדה הראשון 'מפתח' בטופס 'הוספת משתנה חדש' בהגדרות משתני הסביבה.

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

KEY1=value1
KEY2=value2
KEY3=value3

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

משתני סביבה שאוכלסו באופן אוטומטי

יש משתני סביבה שמאוכלסים אוטומטית על ידי App Hosting. הם כוללים את המשתנים שמאוכלסים על ידי Google Cloud, וגם משתני סביבה ספציפיים ל-Firebase כש-appId מוגדר בשרת העורפי במהלך ההגדרה:

• ‫FIREBASE_CONFIG: (זמין בסביבות build ו-runtime) מספק את פרטי ההגדרה הבאים של פרויקט Firebase:

  {
    "databaseURL": 'https://DATABASE_NAME.firebaseio.com',
    "storageBucket": 'PROJECT_ID.firebasestorage.app',
    "projectId": 'PROJECT_ID'
  }
  

  ההגדרה הזו מוחלת באופן אוטומטי כשמפעילים את Firebase Admin SDK ללא ארגומנטים.

• ‫FIREBASE_WEBAPP_CONFIG: (זמין רק בסביבת build) מספק את פרטי ההגדרה הבאים של פרויקט Firebase:

  {
    "apiKey": 'API_KEY',
    "appId": 'APP_ID',
    "authDomain": 'AUTH_DOMAIN.firebaseapp.com',
    "databaseURL": 'https://DATABASE_NAME.firebaseio.com',
    "messagingSenderId": 'PROJECT_NUMBER',
    "projectId": 'PROJECT_ID',
    "storageBucket": 'PROJECT_ID.firebasestorage.app',
  }
  

  ‫Firebase JS SDK בודק אוטומטית את FIREBASE_WEBAPP_CONFIGמשתנה הסביבה הזה בסקריפט postinstall במהלך הבנייה, כך שאתם יכולים גם לאתחל את ה-SDK של הלקוח ללא ארגומנטים.

במאמר הפעלה אוטומטית של SDK של Firebase לאדמינים וערכות SDK לאינטרנט מוסבר איך להשתמש במשתני הסביבה האלה כדי להפעיל את ערכות ה-SDK.

שימו לב שהערכים בהגדרת Firebase בפועל יתאימו למשאבים הספציפיים שהקציתם בפרויקט.

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

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

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

1. ‫Firebase console → משתנים שהוגדרו במסוף
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)

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

משתני הסביבה שמוגדרים בCloud Run חוזה זמן הריצה של הקונטיינר הם שמורים ואי אפשר להגדיר אותם.

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

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

• מחרוזות ריקות ("")
• מפתחות שמכילים '='
• מקשים שמתחילים ב-X_FIREBASE_, X_GOOGLE_ או CLOUD_RUN_
• 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 כדי להגדיל את מגבלת הזיכרון:

• כדי להשתמש בזיכרון של יותר מ-4GiB, צריך לפחות 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‏ Firebasefirebase apphosting:secrets:set, ותתבקשו להוסיף את ההרשאות הנדרשות. בתהליך הזה יש אפשרות להוסיף באופן אוטומטי את ההפניה לסוד ל-apphosting.yaml.

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

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

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

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

הגדרת Direct VPC Egress ‏ (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 וב-FirebaseCLI. בקטע הזה מתוארות כמה ממשימות הניהול הנפוצות יותר, כולל יצירה ומחיקה של שרתים עורפיים.

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

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

Firebase console: עוברים אל Hosting & Serverless > App Hosting, ואז לוחצים על Create backend (אם זה ה-backend הראשון בפרויקט Firebase, לוחצים על Get started).

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

firebase apphosting:backends:create --project PROJECT_ID

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

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

  בדרך כלל, כאן נמצא קובץ ה-package.json.

• הגדרת הענף הפעיל

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

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

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

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

• בוחרים את סביבת זמן הריצה. כברירת מחדל, הגרסה המומלצת הכי חדשה של Node.js נבחרת מראש בשבילכם.

  • מגדירים עדכונים אוטומטיים של תמונת הבסיס (ABIU). התכונה ABIU מופעלת כברירת מחדל ומחילת תיקוני אבטחה באופן אוטומטי על הסביבה הבסיסית שלכם. כדי לבטל את ההסכמה לשימוש ב-ABIU, בוחרים באפשרות Not specified (לא צוין) עבור זמן הריצה.

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

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

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

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

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