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

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

פיתוח נייטיב

כדי לציין משתני סביבה בקובץ 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 בקובץ 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".

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

המסוף

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

   כניסה ל-Cloud Run

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

3. אם אתם מגדירים שירות חדש, ממלאים את דף ההגדרות הראשוניות של השירות ואז לוחצים על Containers, 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.

פיתוח נייטיב

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

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

   כניסה ל-Cloud Run

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

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

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

gcloud

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

   gcloud run services describe SERVICE

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

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

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

המסוף

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

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

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

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

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

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

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