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

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

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

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

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

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

• ‫Cloud Run Developer (roles/run.developer) בשירות Cloud Run
• משתמש בחשבון שירות (roles/iam.serviceAccountUser) בזהות השירות

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

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

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

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

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

3. אם אתם מגדירים שירות חדש, ממלאים את דף ההגדרות הראשוניות של השירות ואז לוחצים על Container(s), Volumes, Networking, Security (מאגרים, אמצעי אחסון, רשתות, אבטחה) כדי להרחיב את דף הגדרות השירות.

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

   

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

5. לוחצים על יצירה או על פריסה.

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

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

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

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

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:

המסוף

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

   כניסה ל-Cloud Run

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

3. אם אתם מגדירים שירות חדש, ממלאים את דף ההגדרות הראשוניות של השירות ואז לוחצים על Container(s), Volumes, Networking, Security (מאגרים, אמצעי אחסון, רשתות, אבטחה) כדי להרחיב את דף הגדרות השירות.

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

   

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

5. לוחצים על יצירה או על פריסה.

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.

הגדרת כמה משתני סביבה באמצעות הדגל --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. במסוף Google Cloud , נכנסים לדף Services של Cloud Run:

   כניסה ל-Cloud Run

2. בוחרים את השירות מהרשימה ולוחצים על עריכה ופריסה של גרסה חדשה.

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

4. בכרטיסייה משתנים וסודות, עורכים את השדות שם או ערך ולוחצים על סיום.

5. לוחצים על פריסה.

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. במסוף Google Cloud , נכנסים לדף Services של Cloud Run:

   כניסה ל-Cloud Run

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

3. לוחצים על הכרטיסייה עדכונים.

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

gcloud

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

   gcloud run services describe SERVICE

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

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

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

המסוף

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

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

   כניסה ל-Cloud Run

2. בוחרים את השירות מהרשימה ולוחצים על עריכה ופריסה של גרסה חדשה.

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

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

5. לוחצים על סיום.

6. לוחצים על פריסה.

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 במדריך בנושא אימות משתמשי קצה.

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

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

• Node.js
• Python
• Go
• Ruby
• PHP
• Java

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