區域 ID
REGION_ID 是 Google 根據您在建立應用程式時選取的區域指派的縮寫代碼。這個代碼不對應國家/地區或省/市,即使某些區域 ID 可能與常用的國家/地區和省/市代碼相似。如果是 2020 年 2 月後建立的應用程式,App Engine 網址會包含 REGION_ID.r。如果是 2020 年 2 月前建立的現有應用程式,網址中的區域 ID 則為選用。
進一步瞭解區域 ID。
本指南說明如何將標準環境中的現有應用程式部署至 Cloud Run。這些操作說明適用於不使用 App Engine 舊版隨附服務的第二代執行階段。
本指南所述步驟不會影響現有 App Engine 應用程式的功能或流量。新建立的 Cloud Run 服務是 App Engine 服務的副本,可獨立測試。
Cloud Run 使用的基礎架構與 App Engine 標準環境大致相同,因此這兩個平台有許多相似之處。如要進一步瞭解 App Engine 和 Cloud Run 的異同,包括遷移至 Cloud Run 的優點,請參閱比較摘要。 如要部署至 Cloud Run,請選擇下列其中一項策略:使用
app.yaml檔案的本機設定 (建議):選擇這個選項,直接從本機原始碼建構容器映像檔,並部署至 Cloud Run。這可確保您最近對程式碼或設定所做的任何本機修改,都會包含在新的部署作業中。使用先前建構的映像檔:如果您無法存取原始碼,這個選項會很有幫助。選擇這個選項,即可部署與 App Engine 上執行版本完全相同的副本,不必重新建構容器映像檔,或是在不變更程式碼的情況下,驗證有效部署作業的行為。
事前準備
確認 App Engine 應用程式執行時未發生錯誤。如果選擇使用本機設定部署,則需要存取 App Engine 原始碼。
啟用 Cloud Run Admin API 和 Artifact Registry API:
使用下列指令設定專案和區域:
gcloud auth login gcloud config set project PROJECT_ID gcloud config set run/region REGION gcloud components update更改下列內容:
- PROJECT_ID:您的 Google Cloud 專案 ID。
- REGION:要部署 Cloud Run 服務的區域。
檢查應用程式中是否有不相容的功能,並在遷移至 Cloud Run 前移除這些功能。如要檢查應用程式是否不相容,而不執行遷移或部署作業,請在
app.yaml檔案所在的目錄中執行下列指令:gcloud beta app migrate-to-run --dry-run查看相容性檢查結果,並視需要進行建議的變更。
請查看下列 Cloud Run 差異:
Cloud Run 使用「
Revision」一詞,而非「Version」,代表您每次將變更部署至特定服務。首次將應用程式部署至 Cloud Run 中的服務時,會建立第一個修訂版本。每次部署服務都會建立另一個修訂版本。進一步瞭解如何部署至 Cloud Run。您可以使用Google Cloud 控制台或 Google Cloud CLI,將原始碼部署至 Cloud Run,設定及管理應用程式設定。Cloud Run 不需要檔案式設定,但支援 YAML 設定。
您部署至 Cloud Run 的每項服務,都會使用網址中的
run.app網域公開存取服務。App Engine 服務預設為公開,但 Cloud Run 服務預設為私人,您必須設定為公開 (未經驗證) 存取。
必要的角色
您可以選擇建立新的服務帳戶,或使用與標準環境相同的 Cloud Run 使用者自行管理服務帳戶。您或管理員必須將下列 IAM 角色授予部署者帳戶和 Cloud Build 服務帳戶。
按一下即可查看部署者帳戶的必要角色
如要取得從來源建構及部署所需的權限,請要求管理員授予您下列 IAM 角色:
- 專案的 Cloud Run 原始碼開發人員 (
roles/run.sourceDeveloper) - 專案的服務使用情形消費者 (
roles/serviceusage.serviceUsageConsumer) - Cloud Run 服務身分的服務帳戶使用者 (
roles/iam.serviceAccountUser)
按一下即可查看 Cloud Build 服務帳戶的必要角色
Cloud Build 會自動使用 Compute Engine 預設服務帳戶做為預設 Cloud Build 服務帳戶,建構原始碼和 Cloud Run 資源,除非您覆寫這項行為。如要讓 Cloud Build 建構來源,請要求管理員將 Cloud Run 建構工具 (roles/run.builder) 授予專案的 Compute Engine 預設服務帳戶:
gcloud projects add-iam-policy-binding PROJECT_ID \ --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \ --role=roles/run.builder
將 PROJECT_NUMBER 替換為您的 Google Cloud專案編號,並將 PROJECT_ID 替換為您的 Google Cloud專案 ID。如需尋找專案 ID 和專案編號的詳細操作說明,請參閱「建立及管理專案」。
將 Cloud Run 建構工具角色授予 Compute Engine 預設服務帳戶後,需要幾分鐘的時間才能傳播。
如要查看與 Cloud Run 相關聯的 IAM 角色和權限清單,請參閱「Cloud Run IAM 角色」和「Cloud Run IAM 權限」。如果 Cloud Run 服務與Google Cloud API (例如 Cloud 用戶端程式庫) 互動,請參閱服務身分設定指南。如要進一步瞭解如何授予角色,請參閱「部署權限」和「管理存取權」。
使用 app.yaml 檔案的本機設定
使用 Google Cloud 控制台或 Google Cloud CLI,將本機 App Engine 設定部署至 Cloud Run。
控制台
前往 Google Cloud 控制台的「App Engine」頁面。
在導覽選單中,按一下「Migration hub」,將 App Engine 應用程式部署至 Cloud Run。您也可以在遷移中心查看 Cloud Run 的預估節省費用,取得成本建議。
在「Standard to Cloud Run migration」(從標準環境遷移至 Cloud Run) 資訊卡中,選取要遷移的「Service」(服務),然後按一下「Check compatibility」(檢查相容性)。
在「Check compatibility」(檢查相容性) 部分,確認或選取「Version」(版本),即可查看相容性結果。遷移中心會執行相容性檢查工具,找出不相容的功能。
查看結果,確認應用程式沒有任何不相容問題,然後按一下「Continue」(繼續),前往「Review & Deploy」(查看及部署) 專區。
在「Source based deployment」(來源型部署作業) 分頁中,複製「Deploy through Gcloud」(透過 Gcloud 部署) 部分中的指令,將 PATH_TO_APP_YAML 預留位置替換為
app.yaml檔案的路徑,然後從應用程式來源目錄執行指令。按一下「View deployed versions」(查看已部署的版本),即可查看部署在 Cloud Run 的 App Engine 服務。
gcloud
如要使用現有 App Engine 設定的本機 app.yaml 檔案部署 Cloud Run 服務,請按照下列步驟操作:
在終端機中,切換至
app.yaml檔案所在的來源目錄。執行下列指令,將服務部署至 Cloud Run:
gcloud beta app migrate-to-run這個指令會產生 Cloud Run 的
service.yaml檔案設定,並儲存在本機與app.yaml檔案相同的目錄中。詳情請參閱「gcloud beta app migrate-to-run」。- 系統提示
Proceed with the deployment?時,請輸入Y,從原始碼建構容器映像檔,並將服務部署至 Cloud Run。
- 系統提示
測試已部署的 Cloud Run 服務。Cloud Run 服務預設為私人,因此直接在網路瀏覽器中開啟服務網址會傳回
403 Forbidden錯誤。如要查看服務,請執行下列任一操作:- 如要私下測試服務 (建議做法),請執行
gcloud run services proxy指令,然後在網路瀏覽器中開啟本機 Proxy 網址。 - 如要公開提供服務,請啟用公開存取權,然後在網路瀏覽器中開啟服務網址。
選用:
如果
app.yaml檔案位於其他目錄,請使用--appyaml旗標指定路徑:gcloud beta app migrate-to-run --appyaml=PATH將 PATH 替換為
app.yaml檔案的路徑。如要產生及匯出 Cloud Run
service.yaml設定,但不部署服務,請使用--export-only旗標:gcloud beta app migrate-to-run --export-only=EXPORT_PATH將 EXPORT_PATH 替換為要儲存
service.yaml檔案的目錄或路徑。
- 如要私下測試服務 (建議做法),請執行
使用先前建構的映像檔
如要使用先前從已部署 App Engine 版本建構的容器映像檔進行部署,而非從本機 app.yaml 檔案重新建構容器映像檔,請按照下列步驟操作:
這項部署作業不需要應用程式的原始碼。
執行下列指令,將服務部署至 Cloud Run。這個指令會使用有效 App Engine 部署作業的容器映像檔,不會擷取本機
app.yaml檔案的最新變更,因此可能會導致部署作業過時:gcloud beta app migrate-to-run --service=SERVICE --version=VERSION --from-image更改下列內容:
- SERVICE:App Engine 服務的名稱。
- VERSION:服務的版本 ID。
這個指令會擷取指定服務和版本的設定,為 Cloud Run 產生
service.yaml檔案。如要瞭解詳情,請參閱gcloud beta app migrate-to-run。- 看到
Proceed with the deployment?提示時,請輸入Y,匯出現有的 App Engine 容器映像檔,並將服務部署至 Cloud Run。
測試已部署的 Cloud Run 服務。Cloud Run 服務預設為私人,因此直接在網路瀏覽器中開啟服務網址會傳回
403 Forbidden錯誤。如要查看服務,請執行下列其中一項操作:- 如要私下測試服務 (建議做法),請執行
gcloud run services proxy指令,然後在網路瀏覽器中開啟本機 Proxy 網址。 - 如要公開提供服務,請啟用公開存取權,然後在網路瀏覽器中開啟服務網址。
選用:
如要產生 Cloud Run
service.yaml設定,但不部署服務,請執行下列指令:gcloud beta app migrate-to-run --service=SERVICE \ --version=VERSION \ --from-image \ --export-only=EXPORT_PATH將 EXPORT_PATH 替換為要儲存
service.yaml檔案的目錄或路徑。
- 如要私下測試服務 (建議做法),請執行
不相容的功能
如果 app.yaml 檔案包含下列任何不支援的設定,遷移指令會失敗或顯示警告:
傳入服務:
inbound_services: - warmup解決方案:從
app.yaml檔案中刪除inbound_services區段。Cloud Run 會使用容器進入點預熱執行個體,因此您不必設定暖機要求。如要在提供流量前執行初始化程式碼,請將服務設為在啟動時執行,然後再監聽要求或使用啟動探測。您也可以設定執行個體數量下限,讓執行個體維持在暖機狀態。自訂錯誤頁面:
error_handlers: - file: default_error.html - error_code: over_quota file: over_quota.html解決方法:從
app.yaml檔案中刪除error_handlers區段,並採用下列其中一項或兩項策略:- 直接在應用程式程式碼中導入錯誤處理機制。擷取標準 HTTP 錯誤代碼 (例如
404或500),並從應用程式邏輯中提供自訂 HTML 錯誤頁面。 - 如果您將 Cloud Load Balancing 與 Cloud Run 搭配使用,請在負載平衡器層級設定自訂錯誤回應。這樣一來,您就能根據 Cloud Run 服務的回應代碼,從 Cloud Storage 提供自訂錯誤頁面。
- 直接在應用程式程式碼中導入錯誤處理機制。擷取標準 HTTP 錯誤代碼 (例如
網址和靜態檔案處理常式:
handlers: - url: /stylesheets static_dir: stylesheets解決方案:從
app.yaml檔案中刪除handlers區段,或只保留一個 catch-all 處理常式,將所有流量轉送至應用程式 (url: /.*或url: .*搭配script: auto)。Cloud Run 不支援app.yaml要求轉送或靜態檔案處理常式。請改為直接從 Cloud Run 服務或 Cloud Storage 提供靜態檔案,並在應用程式程式碼中或使用 Cloud Load Balancing 處理網址轉送。
第二代執行階段的隨附服務:
app_engine_apis: true解決方法:從
app.yaml檔案中刪除app_engine_apis設定,並改用 Google Cloud API 或第三方替代方案。詳情請參閱「從隨附服務遷移」。第一代執行階段:
runtime: python27解決方法:將應用程式升級至支援的第二代執行階段。詳情請參閱「遷移至第二代執行階段總覽」。
後續步驟
- 瞭解如何管理 Cloud Run 服務。
- 請參閱 Cloud Run 容器執行階段合約,瞭解 Cloud Run 中容器的需求和行為。
- 瞭解如何使用 Secret Manager,為需要 API 金鑰、密碼或其他機密資訊的服務儲存依附元件。