將彈性環境中的 App Engine 應用程式部署至 Cloud Run

區域 ID

REGION_ID 是 Google 根據您在建立應用程式時選取的區域指派的縮寫代碼。這個代碼不對應國家/地區或省/市,即使某些區域 ID 可能與常用的國家/地區和省/市代碼相似。如果是 2020 年 2 月後建立的應用程式,App Engine 網址會包含 REGION_ID.r。如果是 2020 年 2 月前建立的現有應用程式,網址中的區域 ID 則為選用。

進一步瞭解區域 ID。

本指南說明如何將彈性環境中的現有應用程式部署至 Cloud Run。

本指南所述步驟不會影響現有 App Engine 應用程式的功能或流量。新建立的 Cloud Run 服務是 App Engine 服務的副本,可獨立測試。

App Engine 彈性環境和 Cloud Run 都是全代管的容器原生應用程式平台,但兩者的結構不同。 如要進一步瞭解 App Engine 和 Cloud Run 的異同,包括遷移至 Cloud Run 的優點,請參閱比較摘要。

如要部署至 Cloud Run,請使用 app.yaml 檔案的本機設定。這項操作會從本機原始碼建構容器映像檔,因此程式碼或設定的任何近期變更都會納入新的部署作業。

事前準備

  1. 確認 App Engine 應用程式執行時未發生錯誤。您必須能存取 App Engine 原始碼。

  2. 啟用 Cloud Run Admin API 和 Artifact Registry API:

    啟用 API

  3. 使用下列指令設定專案和區域:

    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 服務的區域。
  4. 檢查應用程式中是否有不相容的功能,並在遷移至 Cloud Run 前移除這些功能。如要檢查應用程式是否不相容,而不執行遷移或部署作業,請在 app.yaml 檔案所在的目錄中執行下列指令:

    gcloud beta app migrate-to-run --dry-run
    

    查看相容性檢查結果,並視需要進行建議的變更。

  5. 請查看下列 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 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。

控制台

  1. 前往 Google Cloud 控制台的「App Engine」頁面。

    前往 App Engine

  2. 在導覽選單中,按一下「Migration hub」,將 App Engine 應用程式部署至 Cloud Run。

  3. 在「Flexible to Cloud Run migration」(從彈性環境遷移至 Cloud Run) 資訊卡中,選取要遷移的「Service」(服務) 和「Version」(版本),然後按一下「Check compatibility」(檢查相容性)。

  4. 在「Check compatibility」(檢查相容性) 部分,查看相容性結果。遷移中心會執行相容性檢查工具,找出不相容的功能。

  5. 查看結果,確認應用程式沒有任何不相容問題,然後按一下「Continue」(繼續),前往「Review & Deploy」(查看及部署) 部分。

  6. 複製「Deploy through Gcloud」(透過 Gcloud 部署) 區段中的指令,將 PATH_TO_APP_YAML 預留位置替換為 app.yaml 檔案的路徑,然後從應用程式來源目錄執行指令。

  7. 按一下「View deployed versions」(查看已部署的版本),即可查看部署在 Cloud Run 的 App Engine 服務。

gcloud

如要使用現有 App Engine 設定的本機 app.yaml 檔案部署 Cloud Run 服務,請按照下列步驟操作:

  1. 在終端機中,切換至 app.yaml 檔案所在的來源目錄。

  2. 執行下列指令,將服務部署至 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。
  3. 測試已部署的 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.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 提供自訂錯誤頁面。
  • 網址和靜態檔案處理常式:

    handlers:
    - url: /stylesheets
      static_dir: stylesheets
    

    解決方案:從 app.yaml 檔案中刪除 handlers 區段。Cloud Run 不支援 app.yaml 要求轉送或靜態檔案處理常式。請改為直接從 Cloud Run 服務或 Cloud Storage 提供靜態檔案,並在應用程式程式碼中或使用 Cloud Load Balancing 處理網址轉送。

  • 具有主機通訊埠對應、通訊協定或多個通訊埠的轉送通訊埠:

    network:
      forwarded_ports:
      - 8080:8000
      - 2222/udp
    

    解決方案:更新 app.yaml 檔案中的 network.forwarded_ports,僅指定單一數字容器通訊埠 (例如 8080),或刪除 forwarded_ports 並在 Cloud Run 中設定容器通訊埠。Cloud Run 只接受單一容器通訊埠上的傳入 TCP 流量,不支援主機對容器通訊埠對應或 UDP 流量。遷移工具只接受單純的通訊埠編號,因此主機通訊埠對應和 /tcp 或 /udp 通訊協定後置字串 (例如 8080/tcp) 會導致遷移失敗。如果您指定多個數字通訊埠,遷移工具會記錄警告,並只設定第一個通訊埠。

  • 磁碟大小:

    resources:
      disk_size_gb: 20
    

    解決方法:從 app.yaml 檔案的 resources 區段中刪除 disk_size_gb。Cloud Run 預設為記憶體內檔案系統,寫入檔案會耗用執行個體記憶體,因此遷移工具會顯示警告並忽略這項設定。如果應用程式需要寫入檔案,但不想耗用記憶體,請在 Cloud Run 中設定暫時磁碟磁碟區掛接或 Cloud Storage 磁碟區掛接,以免發生記憶體不足 (OOM) 錯誤。

後續步驟