本頁面說明如何使用 Google Cloud 控制台或 gcloud,為 Cloud Run 服務設定環境變數。
環境變數可用於服務設定,但不建議用來儲存資料庫憑證或 API 金鑰等 Secret。機密值應儲存在原始碼與環境變數以外的地方。建議您使用 Secret Manager 儲存 Secret。如要設定服務,存取儲存在 Secret Manager 中的 Secret,請參閱「設定 Secret」。
任何設定變更都會建立新的修訂版本。除非您明確更新設定,否則後續修訂版本也會自動套用這項設定。
必要的角色
如要取得設定及部署 Cloud Run 服務所需的權限,請要求管理員授予您下列 IAM 角色:
- Cloud Run 服務的 Cloud Run 開發人員 (
roles/run.developer) - 服務身分的服務帳戶使用者 (
roles/iam.serviceAccountUser)
如果您是從原始碼部署服務或函式,則必須在專案和 Cloud Build 服務帳戶中,取得額外角色。
如要查看與 Cloud Run 相關聯的 IAM 角色和權限清單,請參閱「Cloud Run IAM 角色」和「Cloud Run IAM 權限」。如果 Cloud Run 服務與Google Cloud API (例如 Cloud 用戶端程式庫) 互動,請參閱服務身分設定指南。如要進一步瞭解如何授予角色,請參閱「部署權限」和「管理存取權」。
環境變數數量上限和限制
一項 Cloud Run 服務最多可設定 1000 個環境變數。
變數長度上限為 32 KB。
為服務設定環境變數
您可以為新服務和現有服務設定環境變數。請注意,--set-env-vars 旗標是破壞性動作,會刪除先前設定但未包含在新環境變數清單中的環境變數。
環境變數會繫結至特定服務修訂版本, Google Cloud 專案中的其他服務無法存取。
建立新服務或部署新修訂版本時,可以使用 Google Cloud 控制台、gcloud CLI 或 YAML 檔案設定環境變數:
控制台
前往 Google Cloud 控制台的「Cloud Run」頁面:
從 Cloud Run 導覽選單中選取「Services」(服務):
如要設定新服務,請按一下「Deploy container」(部署容器),然後填寫初始服務設定頁面。然後按一下「Containers, Networking, Security」(容器、網路、安全性),展開服務設定頁面。
如要設定現有服務,請按一下該服務。
按一下「容器」分頁標籤。
在「Variables & Secrets」(變數與密鑰) 區段,點選「Add Variable」(新增變數),新增變數。在「Name」(名稱) 和「Value」(值) 欄位中,指定變數的名稱和值。如要進一步瞭解如何設定多個環境變數或逸出特殊字元,請參閱「設定多個環境變數」。
按一下「建立」,建立新服務。依序點選「查看差異並重新部署」和「部署變更」,即可更新現有服務。
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。網址格式為LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG。
如要進一步瞭解如何設定多個環境變數或逸出特殊字元,請參閱「設定多個環境變數」。
YAML
如要建立新服務,請略過這個步驟。如要更新現有服務,請下載其 YAML 設定:
gcloud run services describe SERVICE --format export > service.yaml
更新
containers:下env屬性中的name和value屬性: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。網址格式為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 指令」。
在 Terraform 設定中,將下列內容新增至google_cloud_run_v2_service 資源:上述 google_cloud_run_v2_service 資源會將 foo 環境變數設為 bar,並將 baz 環境變數設為 quux。視需要更新環境變數。
撰寫
如要在 compose.yaml 檔案中指定環境變數,請在服務定義中加入 environment 屬性。您可以使用 = 或 : 做為清單分隔符。如要指定多個環境變數,您也可以使用 env_file 屬性。
services: web: image: IMAGE environment: - KEY1=VALUE1 - KEY2=VALUE2
更改下列內容:
- IMAGE:容器映像檔的網址。
- KEY1=VALUE1,KEY2=VALUE2 或 KEY1:VALUE1,KEY2:VALUE2:變數名稱和值的清單。
部署服務
如要部署服務,請執行
gcloud run compose up指令:gcloud run compose up compose.yaml請按照提示
y安裝必要元件或啟用 API。選用:如要允許未經驗證的使用者存取服務,請公開服務。
部署完成後,系統會顯示 Cloud Run 服務網址。複製這個網址並貼到瀏覽器,即可查看執行中的容器。您可以在 Google Cloud 控制台停用預設驗證。
在容器中設定預設環境變數
您可以在 Dockerfile 中使用 ENV 陳述式,設定環境變數的預設值:
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 控制台、gcloud CLI 或 Compose:
控制台
前往 Google Cloud 控制台的「Cloud Run」頁面:
從 Cloud Run 導覽選單中選取「Services」(服務):
如要設定新服務,請按一下「Deploy container」(部署容器),然後填寫初始服務設定頁面。然後按一下「Containers, Networking, Security」(容器、網路、安全性),展開服務設定頁面。
如要設定現有服務,請按一下該服務。
按一下「容器」分頁標籤。
在「Variables & Secrets」(變數與密鑰) 部分,按一下「Add Variable」(新增變數),然後將
.env檔案或 YAML 檔案的內容貼到「Name」(名稱) 欄位。Cloud Run 會自動填入「Value」(值) 欄位,並為您在檔案中定義的每個鍵/值組合建立新變數。按一下「建立」,建立新服務。依序點選「查看差異並重新部署」和「部署變更」,即可更新現有服務。
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。網址格式為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:容器映像檔的網址。
- ENV_FILE_PATH:
.env檔案的路徑。
部署服務
如要部署服務,請執行
gcloud run compose up指令:gcloud run compose up compose.yaml請按照提示
y安裝必要元件或啟用 API。選用:如要允許未經驗證的使用者存取服務,請公開服務。
部署完成後,系統會顯示 Cloud Run 服務網址。複製這個網址並貼到瀏覽器,即可查看執行中的容器。您可以在 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"
逸出逗號字元
由於半形逗號字元, 是用來分割環境變數,如果環境變數包含半形逗號字元做為值,您需要指定不同的分隔符號字元 (例如 @),逸出這些分隔符號:--set-env-vars "^@^KEY1=value1,value2,value3@KEY2=..."
更新服務的環境變數
您可以更新現有服務的環境變數。這是非破壞性方法,可變更或新增環境變數,但不會刪除先前設定的環境變數。
控制台
如要使用 Google Cloud 控制台更新環境變數,請按照下列步驟操作:
在 Google Cloud 控制台中,前往 Cloud Run 的「Services」(服務) 頁面:
從清單中選取服務,然後按一下「容器」分頁標籤。
在「Variables & Secrets」(變數和 Secret) 區段中,編輯「Name」(名稱) 或「Value」(值) 欄位,然後按一下「Done」(完成)。
依序點選「查看差異並重新部署」和「部署變更」。
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 服務目前的環境變數設定,請按照下列步驟操作:
控制台
在 Google Cloud 控制台中,前往 Cloud Run 的「Services」(服務) 頁面:
按一下您感興趣的服務,開啟「Service details」(服務詳細資料) 頁面。
按一下「容器」分頁標籤查看設定。
gcloud
使用下列指令:
gcloud run services describe SERVICE
在傳回的設定中,找出環境變數設定。
刪除環境變數
您可以刪除現有服務的環境變數。
控制台
如要使用 Google Cloud 控制台刪除環境變數,請按照下列步驟操作:
在 Google Cloud 控制台中,前往 Cloud Run 的「Services」(服務) 頁面:
從清單中選取服務,然後按一下「容器」分頁標籤。
在「Variables and secrets」(變數和密鑰) 分頁中,將游標移至要移除的環境變數「Value」(值) 欄位右側,顯示 「Delete」(刪除) 圖示,然後按一下該圖示。
依序點選「查看差異並重新部署」和「部署變更」。
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 改為您的服務名稱。
最佳做法
以下章節將說明設定環境變數的一些最佳做法。
服務的保留環境變數
容器執行階段合約中定義的環境變數為保留變數,無法設定。具體來說,Cloud Run 會將 PORT 環境變數插入容器中。請勿自行設定。
部署函式時的其他保留環境變數
部署函式時,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。如要瞭解特定語言的詳細資料,請參閱下列建構套件說明文件:
如果您是從來源部署,且需要在建構時自訂變數,請參閱「設定建構環境變數」。