בדף הזה מוסבר איך להגדיר משתני סביבה לשירות Cloud Run באמצעות מסוף Google Cloud או gcloud.
אפשר להשתמש במשתני סביבה להגדרת השירות, אבל אנחנו לא ממליצים להשתמש בהם כדי לאחסן סודות כמו פרטי כניסה למסד נתונים או מפתחות API. ערכים רגישים צריכים להיות מאוחסנים מחוץ לקוד המקור ומחוץ למשתני הסביבה. כדי לאחסן סודות, מומלץ להשתמש ב-Secret Manager. כדי להגדיר שירותים לגישה לסודות שמאוחסנים ב-Secret Manager, קראו את המאמר הגדרת סודות.
כל שינוי בהגדרות יוצר גרסה חדשה. גם גרסאות עתידיות יקבלו את הגדרת התצורה הזו באופן אוטומטי, אלא אם תבצעו עדכונים מפורשים כדי לשנות אותה.
התפקידים הנדרשים
כדי לקבל את ההרשאות שנדרשות להגדרה ולפריסה של שירותי Cloud Run, צריך לבקש מהאדמין להקצות לכם את תפקידי ה-IAM הבאים:
- מפתח ב-Cloud Run (
roles/run.developer) בשירות Cloud Run - משתמש בחשבון שירות (
roles/iam.serviceAccountUser) בזהות השירות
אם אתם פורסים שירות או פונקציה מקוד מקור, אתם צריכים גם תפקידים נוספים בפרויקט ובחשבון השירות של 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 כשאתם יוצרים שירות חדש או פורסים גרסה חדשה:
המסוף
נכנסים לדף Cloud Run במסוף Google Cloud :
בתפריט הניווט של Cloud Run, לוחצים על Services:
אם אתם מגדירים שירות חדש, לוחצים על Deploy container וממלאים את דף הגדרות השירות הראשוני. ואז לוחצים על Containers, Networking, Security כדי להרחיב את דף הגדרת השירות.
אם אתם מגדירים שירות קיים, לוחצים על השירות.
לוחצים על הכרטיסייה מאגרי תגים.
בקטע Variables & Secrets, לוחצים על Add Variable כדי להוסיף משתנה חדש. בשדות Name ו-Value, מציינים את השם והערך שרוצים לתת למשתנה. למידע נוסף על הגדרת כמה משתני סביבה או הוספת תווי בריחה (escape) לתווים מיוחדים, ראו הגדרת כמה משתני סביבה.
כדי ליצור שירות חדש, לוחצים על יצירה. לוחצים על 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
אם אתם יוצרים שירות חדש, דלגו על השלב הזה. אם אתם מעדכנים שירות קיים, הורידו את הגדרת ה-YAML שלו:
gcloud run services describe SERVICE --format export > service.yaml
מעדכנים את המאפיינים
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 תווים
- מתחיל ב-
יוצרים או מעדכנים את השירות באמצעות הפקודה הבאה:
gcloud run services replace service.yaml
כברירת מחדל, הפקודה
gcloud run services replaceמשתמשת בקובץservice.yamlאם הוא קיים.
Terraform
כדי ללמוד איך להחיל הגדרות ב-Terraform או להסיר אותן, ראו פקודות בסיסיות ב-Terraform.
מוסיפים את הקוד הבא למשאבgoogle_cloud_run_v2_service בתצורה של Terraform:המשאב 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: רשימת השמות והערכים של המשתנים.
פריסת השירות
כדי לפרוס את השירותים, מריצים את הפקודה
gcloud run compose up:gcloud run compose up compose.yamlמשיבים
yלכל ההנחיות להתקנת הרכיבים הנדרשים או להפעלת ממשקי ה-API.אופציונלי: הפיכת השירות לציבורי אם רוצים לאפשר גישה לשירות ללא אימות.
אחרי הפריסה, כתובת ה-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:
המסוף
נכנסים לדף Cloud Run במסוף Google Cloud :
בתפריט הניווט של Cloud Run, לוחצים על Services:
אם אתם מגדירים שירות חדש, לוחצים על Deploy container וממלאים את דף הגדרות השירות הראשוני. ואז לוחצים על Containers, Networking, Security כדי להרחיב את דף הגדרת השירות.
אם אתם מגדירים שירות קיים, לוחצים על השירות.
לוחצים על הכרטיסייה מאגרי תגים.
בקטע Variables & Secrets, לוחצים על Add Variable ומדביקים את התוכן של קובץ ה-
.envאו קובץ ה-YAML בשדה Name. Cloud Run מאכלס באופן אוטומטי את השדה Value ויוצר משתנים חדשים לכל צמד מפתח/ערך שאתם מגדירים בקובץ.כדי ליצור שירות חדש, לוחצים על יצירה. לוחצים על 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.
פריסת השירות
כדי לפרוס את השירותים, מריצים את הפקודה
gcloud run compose up:gcloud run compose up compose.yamlמשיבים
yלכל ההנחיות להתקנת הרכיבים הנדרשים או להפעלת ממשקי ה-API.אופציונלי: הפיכת השירות לציבורי אם רוצים לאפשר גישה לשירות ללא אימות.
אחרי הפריסה, כתובת ה-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 :
נכנסים לדף Services של Cloud Run במסוף Google Cloud :
בוחרים את השירות מהרשימה ולוחצים על הכרטיסייה Containers.
בקטע Variables & Secrets, עורכים את השדות Name או Value ולוחצים על Done.
לוחצים על 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:
המסוף
נכנסים לדף Services של Cloud Run במסוף Google Cloud :
לוחצים על השירות הרצוי כדי לפתוח את הדף Service details.
לוחצים על הכרטיסייה מאגרי תגים כדי לראות את ההגדרות.
gcloud
משתמשים בפקודה הבאה:
gcloud run services describe SERVICE
מאתרים את ההגדרה של משתני הסביבה בתצורה שהוחזרה.
מחיקת משתני סביבה
אתם יכולים למחוק משתני סביבה של שירותים קיימים.
המסוף
כדי למחוק משתני סביבה באמצעות מסוף Google Cloud :
נכנסים לדף Services של Cloud Run במסוף Google Cloud :
בוחרים את השירות מהרשימה ולוחצים על הכרטיסייה Containers.
בכרטיסייה Variables and secrets, מעבירים את הסמן ימינה מהשדה Value של משתנה הסביבה שרוצים להסיר, כדי להציג את סמל המחיקה Delete, ולוחצים עליו.
לוחצים על 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.