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

בדף הזה מוסבר איך להגדיר משתני סביבה לשירות Cloud Run באמצעות מסוף Google Cloud או gcloud.

אפשר להשתמש במשתני סביבה להגדרת השירות, אבל אנחנו לא ממליצים להשתמש בהם כדי לאחסן סודות כמו פרטי כניסה למסד נתונים או מפתחות API. ערכים רגישים צריכים להיות מאוחסנים מחוץ לקוד המקור ומחוץ למשתני הסביבה. כדי לאחסן סודות, מומלץ להשתמש ב-Secret Manager. כדי להגדיר שירותים לגישה לסודות שמאוחסנים ב-Secret Manager, קראו את המאמר הגדרת סודות.

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

התפקידים הנדרשים

כדי לקבל את ההרשאות שנדרשות להגדרה ולפריסה של שירותי Cloud Run, צריך לבקש מהאדמין להקצות לכם את תפקידי ה-IAM הבאים:

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

רשימה של תפקידים והרשאות ב-IAM שמשויכים ל-Cloud Run מופיעה במאמרים תפקידי IAM ב-Cloud Run והרשאות IAM ב-Cloud Run. אם שירות Cloud Run מתממשק עם ממשקי API שלGoogle Cloud , כמו ספריות הלקוח ב-Cloud, עיינו במדריך להגדרת זהות השירות. מידע נוסף על הקצאת תפקידים זמין במאמרים הרשאות פריסה וניהול הגישה.

מספר מקסימלי של משתני סביבה ומגבלות

אפשר להגדיר עד 1,000 משתני סביבה לשירות Cloud Run.

האורך המקסימלי של משתנה הוא 32KB.

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

אפשר להגדיר משתני סביבה לשירותים חדשים וקיימים. חשוב לזכור שהדגל --set-env-vars הוא פעולה הרסנית שמוחקת משתני סביבה שהוגדרו בעבר ולא נכללים ברשימה החדשה של משתני הסביבה.

משתני סביבה קשורים לגרסה ספציפית של שירות, והם לא גלויים לשירותים אחרים בפרויקט ב- Google Cloud .

אתם יכולים להגדיר משתני סביבה באמצעות מסוף Google Cloud , ה-CLI של gcloud או קובץ YAML כשאתם יוצרים שירות חדש או פורסים גרסה חדשה:

המסוף

  1. נכנסים לדף Cloud Run במסוף Google Cloud :

    כניסה ל-Cloud Run

  2. בתפריט הניווט של Cloud Run, לוחצים על Services:

    1. אם אתם מגדירים שירות חדש, לוחצים על Deploy container וממלאים את דף הגדרות השירות הראשוני. ואז לוחצים על Containers, Networking, Security כדי להרחיב את דף הגדרת השירות.

    2. אם אתם מגדירים שירות קיים, לוחצים על השירות.

  3. לוחצים על הכרטיסייה מאגרי תגים.

  4. בקטע Variables & Secrets, לוחצים על Add Variable כדי להוסיף משתנה חדש. בשדות Name ו-Value, מציינים את השם והערך שרוצים לתת למשתנה. למידע נוסף על הגדרת כמה משתני סביבה או הוספת תווי בריחה (escape) לתווים מיוחדים, ראו הגדרת כמה משתני סביבה.

  5. כדי ליצור שירות חדש, לוחצים על יצירה. לוחצים על View diff & redeploy ואז על Deploy changes בשירות קיים.

gcloud

כדי לציין משתני סביבה כשפורסים את השירות, משתמשים בדגל --set-env-vars:

gcloud run deploy SERVICE --image IMAGE_URL --set-env-vars KEY1=VALUE1,KEY2=VALUE2

מחליפים את מה שכתוב בשדות הבאים:

  • ‫SERVICE: שם השירות.
  • ‫KEY1=VALUE1,KEY2=VALUE2: רשימה מופרדת בפסיקים של שמות וערכים של משתנים.
  • ‫IMAGE_URL: הפניה לקובץ האימג' של הקונטיינר, לדוגמה us-docker.pkg.dev/cloudrun/container/hello:latest. אם אתם משתמשים ב-Artifact Registry, המאגר REPO_NAME כבר צריך להיות קיים. כתובת ה-URL צריכה להיות בפורמט LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG.

למידע נוסף על הגדרת כמה משתני סביבה או תווי בריחה (escape) מיוחדים, ראו הגדרת כמה משתני סביבה.

YAML

  1. אם אתם יוצרים שירות חדש, דלגו על השלב הזה. אם אתם מעדכנים שירות קיים, הורידו את הגדרת ה-YAML שלו:

    gcloud run services describe SERVICE --format export > service.yaml
  2. מעדכנים את המאפיינים name ו-value במאפיין env ב-containers::

    apiVersion: serving.knative.dev/v1
    kind: Service
    metadata:
      name: SERVICE
    spec:
      template:
        metadata:
          name: REVISION
        spec:
          containers:
          - image: IMAGE
            env:
            - name: KEY-1
              value: VALUE-1
            - name: KEY-N
              value: VALUE-N

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫SERVICE: השם של שירות Cloud Run.
    • ‫IMAGE_URL: הפניה לקובץ האימג' של הקונטיינר, לדוגמה us-docker.pkg.dev/cloudrun/container/hello:latest. אם אתם משתמשים ב-Artifact Registry, המאגר REPO_NAME כבר צריך להיות קיים. כתובת ה-URL צריכה להיות בפורמט LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG.
    • ‫KEY-1, VALUE-1: משתנה הסביבה והערך. אפשר להוסיף עוד משתנים וערכים לפי הצורך.
    • ‫REVISION: שם גרסה חדש או מחיקה של השם (אם הוא קיים). אם אתם נותנים שם חדש לגרסה, הוא חייב לעמוד בקריטריונים הבאים:
      • מתחיל ב-SERVICE-
      • מכיל רק אותיות קטנות, מספרים ו--
      • לא מסתיים ב--
      • לא חורג מ-63 תווים
  3. יוצרים או מעדכנים את השירות באמצעות הפקודה הבאה:

    gcloud run services replace service.yaml

    כברירת מחדל, הפקודה gcloud run services replace משתמשת בקובץ service.yaml אם הוא קיים.

Terraform

כדי ללמוד איך להחיל הגדרות ב-Terraform או להסיר אותן, ראו פקודות בסיסיות ב-Terraform.

מוסיפים את הקוד הבא למשאב google_cloud_run_v2_service בתצורה של Terraform:

resource "google_cloud_run_v2_service" "default" {
  name     = "cloudrun-service-env-var"
  location = "us-central1"

  deletion_protection = false # set to "true" in production

  template {
    containers {
      image = "us-docker.pkg.dev/cloudrun/container/hello"

      # Environment variables
      env {
        name  = "foo"
        value = "bar"
      }
      env {
        name  = "baz"
        value = "quux"
      }
    }
  }
}

המשאב google_cloud_run_v2_service שלמעלה מגדיר את משתנה הסביבה foo לערך bar, ואת משתנה הסביבה baz לערך quux. מעדכנים את משתני הסביבה לפי הצורך.

פיתוח נייטיב

כדי לציין משתני סביבה בקובץ compose.yaml, מוסיפים את המאפיין environment להגדרת השירות. אפשר להשתמש ב-= או ב-: בתור מפריד הרשימה. כדי לציין כמה משתני סביבה, אפשר גם להשתמש במאפיין env_file.

  services:
    web:
      image: IMAGE
      environment:
        - KEY1=VALUE1
        - KEY2=VALUE2

מחליפים את מה שכתוב בשדות הבאים:

  • ‫IMAGE: כתובת ה-URL של קובץ האימג' של הקונטיינר.
  • ‫KEY1=VALUE1,KEY2=VALUE2 או KEY1:VALUE1,KEY2:VALUE2: רשימת השמות והערכים של המשתנים.

פריסת השירות

  1. כדי לפרוס את השירותים, מריצים את הפקודה gcloud run compose up:

    gcloud run compose up compose.yaml
  2. משיבים y לכל ההנחיות להתקנת הרכיבים הנדרשים או להפעלת ממשקי ה-API.

  3. אופציונלי: הפיכת השירות לציבורי אם רוצים לאפשר גישה לשירות ללא אימות.

אחרי הפריסה, כתובת ה-URL של שירות Cloud Run מוצגת. מעתיקים את כתובת ה-URL הזו ומדביקים אותה בדפדפן כדי לראות את הקונטיינר שפועל. אפשר להשבית את אימות ברירת המחדל במסוף Google Cloud .

הגדרת משתני סביבה כברירת מחדל בקונטיינר

אתם יכולים להשתמש בהצהרה ENV בקובץ Docker כדי להגדיר ערכי ברירת מחדל למשתני סביבה:

ENV KEY1=VALUE1,KEY2=VALUE2

סדר קדימויות: משתנים של מאגר תגים לעומת משתנים של שירות

אם מגדירים משתנה סביבה כברירת מחדל בקונטיינר וגם מגדירים משתנה סביבה עם אותו שם בשירות Cloud Run, הערך שמוגדר בשירות מקבל קדימות.

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

אפשר להגדיר כמה משתני סביבה באמצעות קובץ תצורה או הדגל --set-env-vars.

הגדרה של כמה משתני סביבה באמצעות קובץ תצורה

כדי להגדיר כמה משתני סביבה, משתמשים בקובץ .env או בקובץ YAML. מציינים את משתני הסביבה בפורמט הבא:

קובץ .env

KEY-1=VALUE-1
KEY-2=VALUE-2
KEY-3=VALUE-3

מחליפים את KEY ו-VALUE בשמות ובערכים של המשתנים. לדוגמה, APP_NAME="My app".

קובץ YAML

KEY-1: VALUE-1
KEY-2: VALUE-2
KEY-3: VALUE-3

מחליפים את KEY ו-VALUE בשמות ובערכים של המשתנים. לדוגמה, APP_NAME: "My app".

כדי להגדיר את המשתנים האלה כשאתם יוצרים שירות חדש או פורסים גרסה חדשה, אתם יכולים להשתמש במסוף Google Cloud , ב-CLI של gcloud או ב-Compose:

המסוף

  1. נכנסים לדף Cloud Run במסוף Google Cloud :

    כניסה ל-Cloud Run

  2. בתפריט הניווט של Cloud Run, לוחצים על Services:

    1. אם אתם מגדירים שירות חדש, לוחצים על Deploy container וממלאים את דף הגדרות השירות הראשוני. ואז לוחצים על Containers, Networking, Security כדי להרחיב את דף הגדרת השירות.

    2. אם אתם מגדירים שירות קיים, לוחצים על השירות.

  3. לוחצים על הכרטיסייה מאגרי תגים.

  4. בקטע Variables & Secrets, לוחצים על Add Variable ומדביקים את התוכן של קובץ ה-.env או קובץ ה-YAML בשדה Name. ‫Cloud Run מאכלס באופן אוטומטי את השדה Value ויוצר משתנים חדשים לכל צמד מפתח/ערך שאתם מגדירים בקובץ.

  5. כדי ליצור שירות חדש, לוחצים על יצירה. לוחצים על View diff & redeploy ואז על Deploy changes בשירות קיים.

gcloud

כדי לציין כמה משתני סביבה מקובץ התצורה, מריצים את הפקודה הבאה:

gcloud run deploy SERVICE --image=IMAGE_URL --env-vars-file=ENV_FILE_PATH

מחליפים את מה שכתוב בשדות הבאים:

  • ‫SERVICE: השם של שירות Cloud Run.
  • ‫IMAGE_URL: הפניה לקובץ האימג' של הקונטיינר, לדוגמה us-docker.pkg.dev/cloudrun/container/hello:latest. אם אתם משתמשים ב-Artifact Registry, המאגר REPO_NAME כבר צריך להיות קיים. כתובת ה-URL צריכה להיות בפורמט LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG.
  • ‫ENV_FILE_PATH: הנתיב לקובץ .env או לקובץ YAML. לדוגמה: production.env או config/production-variables.yaml.

פיתוח נייטיב

כדי לציין כמה משתני סביבה בקובץ compose.yaml, מוסיפים את המאפיין env_file להגדרת השירות.

  services:
    web:
      image: IMAGE
      env_file:
        - ENV_FILE_PATH

מחליפים את מה שכתוב בשדות הבאים:

  • ‫IMAGE: כתובת ה-URL של קובץ האימג' של הקונטיינר.
  • ‫ENV_FILE_PATH: הנתיב לקובץ .env.

פריסת השירות

  1. כדי לפרוס את השירותים, מריצים את הפקודה gcloud run compose up:

    gcloud run compose up compose.yaml
  2. משיבים y לכל ההנחיות להתקנת הרכיבים הנדרשים או להפעלת ממשקי ה-API.

  3. אופציונלי: הפיכת השירות לציבורי אם רוצים לאפשר גישה לשירות ללא אימות.

אחרי הפריסה, כתובת ה-URL של שירות Cloud Run מוצגת. מעתיקים את כתובת ה-URL הזו ומדביקים אותה בדפדפן כדי לראות את הקונטיינר שפועל. אפשר להשבית את אימות ברירת המחדל במסוף Google Cloud .

הגדרה של כמה משתני סביבה באמצעות הדגל --set-env-vars

אם יש לכם כמה משתני סביבה שאי אפשר לציין בפורמט KEY1=VALUE1,KEY2=VALUE2, אתם יכולים לחזור על הדגל --set-env-vars כמה פעמים:
   [...]
   --set-env-vars "KEY1=VALUE1" \
   --set-env-vars "KEY2=VALUE2" \
   --set-env-vars "KEY3=VALUE3"

תו בריחה (escape) לתווי פסיק

התו פסיק , משמש לפיצול משתני סביבה. אם משתנה הסביבה מכיל תווים של פסיקים כערכים, צריך להחליף את התווים המפרידים האלה בתו מפריד אחר, למשל @:
--set-env-vars "^@^KEY1=value1,value2,value3@KEY2=..."

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

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

המסוף

כדי לעדכן משתני סביבה באמצעות מסוף Google Cloud :

  1. נכנסים לדף Services של Cloud Run במסוף Google Cloud :

    כניסה ל-Cloud Run

  2. בוחרים את השירות מהרשימה ולוחצים על הכרטיסייה Containers.

  3. בקטע Variables & Secrets, עורכים את השדות Name או Value ולוחצים על Done.

  4. לוחצים על View diff & redeploy ואז על Deploy changes.

gcloud

כדי לעדכן משתני סביבה של שירות קיים, משתמשים בדגל --update-env-vars:

gcloud run services update SERVICE --update-env-vars KEY1=VALUE1,KEY2=VALUE2

מחליפים את מה שכתוב בשדות הבאים:

  • ‫SERVICE: שם השירות.
  • ‫KEY1=VALUE1,KEY2=VALUE2: רשימה מופרדת בפסיקים של שמות וערכים של משתנים.

כדי לעדכן את משתני הסביבה של שירות קיים במספר אזורים, משתמשים בפקודה gcloud run multi-region-services update.

הצגת ההגדרות של משתני הסביבה

כדי לראות את ההגדרות הנוכחיות של משתני הסביבה בשירות Cloud Run:

המסוף

  1. נכנסים לדף Services של Cloud Run במסוף Google Cloud :

    כניסה ל-Cloud Run

  2. לוחצים על השירות הרצוי כדי לפתוח את הדף Service details.

  3. לוחצים על הכרטיסייה מאגרי תגים כדי לראות את ההגדרות.

gcloud

  1. משתמשים בפקודה הבאה:

    gcloud run services describe SERVICE
  2. מאתרים את ההגדרה של משתני הסביבה בתצורה שהוחזרה.

מחיקת משתני סביבה

אתם יכולים למחוק משתני סביבה של שירותים קיימים.

המסוף

כדי למחוק משתני סביבה באמצעות מסוף Google Cloud :

  1. נכנסים לדף Services של Cloud Run במסוף Google Cloud :

    כניסה ל-Cloud Run

  2. בוחרים את השירות מהרשימה ולוחצים על הכרטיסייה Containers.

  3. בכרטיסייה Variables and secrets, מעבירים את הסמן ימינה מהשדה Value של משתנה הסביבה שרוצים להסיר, כדי להציג את סמל המחיקה Delete, ולוחצים עליו.

  4. לוחצים על View diff and redeploy ואז על Deploy changes.

gcloud

כדי להסיר משתני סביבה ספציפיים של שירות קיים,משתמשים בדגל --remove-env-vars:

gcloud run services update SERVICE --remove-env-vars KEY1,KEY2

מחליפים את מה שכתוב בשדות הבאים:

  • ‫SERVICE: שם השירות.
  • ‫KEY1,KEY2: רשימה מופרדת בפסיקים של שמות המשתנים.

לחלופין, אפשר למחוק את כל משתני הסביבה שהוגדרו קודם באמצעות הדגל --clear-env-vars:

gcloud run services update SERVICE --clear-env-vars

מחליפים את SERVICE בשם השירות.

שיטות מומלצות

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

משתני סביבה שמורים לשירותים

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

משתני סביבה שמורים נוספים כשפורסים פונקציות

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

  • ‫FUNCTION_TARGET: הפונקציה שצריך להפעיל.
  • ‫FUNCTION_SIGNATURE_TYPE: סוג הפונקציה: http לפונקציות HTTP ו-event לפונקציות מבוססות-אירועים.

חלק ממשתני הסביבה הנוספים מוגדרים באופן אוטומטי בהתאם לסביבת זמן הריצה שבה הפונקציה משתמשת. הם מבוססים על מערכת ההפעלה של סביבת זמן הריצה, למשל DEBIAN_FRONTEND,‏ SHLVL או PATH, ועל סביבת זמן הריצה של השפה, למשל NODE_ENV,‏ VIRTUAL_ENV או GOPATH.

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

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

משתני סביבה לא תקינים

אי אפשר להשתמש במשתני הסביבה הבאים:

מפתח תיאור
ריק ('') המפתחות לא יכולים להיות מחרוזת ריקה.
= המפתחות לא יכולים להכיל את התו '='.
X_GOOGLE_ מפתחות לא יכולים להכיל את הקידומת X_GOOGLE_.

קוד לדוגמה

במדריך אימות משתמשי קצה, בקטע טיפול בהגדרות רגישות באמצעות Secret Manager , יש דוגמת קוד שמראה איך לגשת למשתני סביבה בקוד.

המאמרים הבאים

אתם יכולים להשתמש במשתני סביבה כדי להגדיר את חבילות ה-build. לפרטים ספציפיים לשפה, עיינו במסמכי התיעוד של buildpacks:

אם אתם פורסים מקוד המקור וצריכים להתאים אישית משתנים בזמן ה-build, קראו את המאמר הגדרת משתני סביבה של build.