容器執行階段合約

本頁面列出 Cloud Run 中容器的重要規定和行為。Cloud Run 服務和 Cloud Run 工作之間有一些差異：這些差異會在適當位置標示。

支援的語言和圖片

容器映像檔可執行以您選擇的程式設計語言編寫的程式碼，並使用任何基礎映像檔，前提是該映像檔必須遵守本頁所列的限制。

容器映像檔中的可執行檔必須針對 64 位元 Linux 編譯。Cloud Run 特別支援 Linux x86_64 ABI 格式。

Cloud Run 接受 Docker Image Manifest V2、Schema 1、Schema 2 和 OCI 映像檔格式的容器映像檔。Cloud Run 也接受 Zstd 壓縮容器映像檔。

如果部署多架構映像檔，資訊清單必須包含 linux/amd64。

如果是透過 Cloud Run 部署的函式，您可以使用 Google Cloud 的 Buildpack 發布的 Cloud Run 執行階段基礎映像檔，接收自動安全性和維護更新。請參閱執行階段支援時程，瞭解支援的執行階段。

在正確的通訊埠 (服務) 上接聽要求

Cloud Run 服務會啟動 Cloud Run 執行個體，以便處理傳入的要求。Cloud Run 執行個體一律會有一個用於監聽要求的單一入口容器，以及一或多個選用的附屬容器。下列詳細的連接埠設定僅適用於入口容器，不適用於附屬程式。

在執行個體內，入口容器必須在傳送要求的通訊埠上，監聽 0.0.0.0 上的要求。請注意，入口容器「不應」監聽 127.0.0.1。根據預設，要求會傳送至 8080，但您可以設定 Cloud Run，將要求傳送至所選的通訊埠。Cloud Run 會將 PORT 環境變數注入入口容器。

在工作執行期間執行的容器必須在工作完成後退出

對於 Cloud Run 工作，容器必須在工作成功完成時以結束代碼 0 結束，並在工作失敗時以非零的結束代碼結束。

由於工作不應提供要求，因此容器不應監聽通訊埠或啟動網路伺服器。

傳輸層加密 (TLS)

容器不應直接實作任何傳輸層安全性。Cloud Run 會為 HTTPS 和 gRPC 終止 TLS，然後將要求以 HTTP/1 或 gRPC 形式轉送至沒有 TLS 的容器。

如果您設定 Cloud Run 服務以便使用端對端 HTTP/2，容器就必須以 HTTP/2 純文字 (h2c) 格式處理要求，因為 Cloud Run 仍會自動終止 TLS。

回應 (服務)

對於 Cloud Run 服務，容器必須在收到要求後，在要求逾時設定中指定的時間內傳送回應，包括容器啟動時間。否則要求會結束，並傳回 504 錯誤。

回應快取和 Cookie

如果 Cloud Run 服務的回應包含 Set-Cookie 標頭，Cloud Run 會將 Cache-Control 標頭設為 private，以便系統不會快取回應。這麼做可防止其他使用者擷取 Cookie。

環境變數

Cloud Run 服務和工作可使用不同的環境變數組合。

服務的環境變數

下列環境變數會自動新增至所有執行中的容器 (PORT 除外)。PORT 變數只會新增至輸入容器：

名稱 說明 範例
PORT HTTP 伺服器應監聽的通訊埠。 8080
K_SERVICE 正在執行的 Cloud Run 服務名稱。 hello-world
K_REVISION 正在執行的 Cloud Run 修訂版本名稱。 hello-world.1
K_CONFIGURATION 建立修訂版本的 Cloud Run 設定名稱。 hello-world

工作環境變數

針對 Cloud Run 工作，系統會設定下列環境變數：

名稱 說明 範例
CLOUD_RUN_JOB 正在執行的 Cloud Run 工作名稱。 hello-world
CLOUD_RUN_EXECUTION 正在執行的 Cloud Run 執行作業名稱。 hello-world-abc
CLOUD_RUN_TASK_INDEX 此工作的索引。第一項工作為 0，後續每項工作都會增加 1，直到工作數量上限減 1 為止。如果您將 --parallelism 設為大於 1，任務可能不會按照索引順序執行。舉例來說，工作 2 可能會在工作 1 之前開始。 0
CLOUD_RUN_TASK_ATTEMPT 這個工作的已重試次數。第一次嘗試時為 0，每次重試時遞增 1，直到達到重試次數上限為止。 0
CLOUD_RUN_TASK_COUNT --tasks 參數中定義的工作數量。 1

要求和回應標頭規定 (服務)

對於 Cloud Run 服務，標頭名稱只能使用可顯示的非空白 ASCII 字元，且不得包含半形冒號。標頭值僅限於可顯示的 ASCII 字元，加上空格和水平定位符號，如 IETF RFC 7230 所述

檔案系統存取權

每個容器中的檔案系統皆可寫入，並遵循下列行為：

  • 這是記憶體內檔案系統，因此寫入此檔案系統會使用執行個體的記憶體。
  • 執行個體停止時，寫入檔案系統的資料不會保留。

請注意，您無法為這個檔案系統指定大小限制，因此您可能會透過寫入記憶體內檔案系統的方式，使用用於執行個體的所有記憶體，進而導致執行個體當機。如要避免這個問題，請使用設有大小限制的專屬記憶體內磁碟區。

執行個體生命週期

Cloud Run 作業和服務的生命週期特徵不同，因此我們會在下列各節中分別說明。

服務

以下僅適用於服務。

服務資源調度

根據預設，Cloud Run 服務會自動調度資源，以便處理所有傳入要求、事件或 CPU 使用率所需的執行個體數量。如要進一步控管調整資源配置的行為，可以選擇使用手動調整資源配置。

每個執行個體都會執行固定數量的容器，包括一個入口容器和一或多個附屬容器。

如果修訂版本未收到任何流量，系統會將其縮減至所設定的執行個體數量下限 (預設為零)。

啟動

對於 Cloud Run 服務，執行個體必須在啟動後的 4 分鐘內開始聆聽要求，且執行個體中的所有容器都必須處於正常狀態。在這個啟動期間，系統會為執行個體分配 CPU。您可以啟用啟動時 CPU 效能強化功能，在執行個體啟動期間暫時增加 CPU 分配，以便減少啟動延遲時間。

只要入口容器監聽已設定的通訊埠，系統就會將要求傳送至該容器。

等待執行個體的要求會保留在待處理佇列中，如下所示：

要求會處於待處理狀態，最長為這項服務容器執行個體平均啟動時間的 3.5 倍，或 10 秒，以較長者為準。

您可以設定啟動探測，判斷容器是否已啟動，且是否已準備好處理要求。

如果 Cloud Run 服務包含多個容器執行個體，您可以設定容器啟動順序，指定在執行個體中啟動容器的順序。

處理要求

對於 Cloud Run 服務，只要 Cloud Run 修訂版本處理至少一項要求，就會一律將 CPU 分配給所有容器，包括執行個體中的附屬程式。

閒置

對於 Cloud Run 服務而言，閒置的例項是指未處理任何要求的例項。

閒置執行個體中分配給所有容器的 CPU 數量，取決於所設定的帳單設定。

除非執行個體因執行個體數量下限設定而必須保持閒置，否則不會閒置超過 15 分鐘。

關閉

對於 Cloud Run 服務，閒置的執行個體隨時可以關閉，包括因設定執行個體數量下限而保持暖機的執行個體。如果需要關閉處理要求的執行個體，系統會給予已處理要求的時間，並將新的要求傳送至其他執行個體。在特殊情況下，Cloud Run 可能會啟動關閉程序，並傳送 SIGTERM 信號至仍在處理要求的容器。

在關閉執行個體之前，Cloud Run 會向執行個體中的所有容器傳送 SIGTERM 信號，表示開始 10 秒的期間，然後才會實際關閉，此時 Cloud Run 會傳送 SIGKILL 信號。在這段期間內，系統會為執行個體分配 CPU 並計費。在使用第一代執行環境的服務中，如果執行個體未擷取 SIGTERM 信號，就會立即關閉。在使用第二代執行環境的服務中，建議您在容器上安裝 SIGTERM 處理常式，以便在 Cloud Run 即將關閉執行個體時收到警告。

強制終止

如果一或多個 Cloud Run 容器超出容器記憶體總量上限，系統就會終止執行個體。在執行個體上仍在處理的所有要求，都會結束並顯示 HTTP 500 錯誤。

工作

對於 Cloud Run 工作，容器執行個體會持續執行，直到容器執行個體結束、達到工作逾時，或容器發生當機為止。

結束代碼

您可以使用工作結束代碼，查看工作是否順利完成，或是否遇到任何錯誤。離開代碼是數值值，可對應至成功完成或特定類型的錯誤。

下表列出常見的結束代碼及其定義：

結束代碼 信號 說明
0 工作已順利完成。
4 SIGILL 工作嘗試存取錯誤位址的記憶體。
7 SIGBUS 工作嘗試存取超出其指派邊界範圍的記憶體。
9 SIGKILL 工作會在使用者操作或手動介入下強制終止。
11 SIGSEGV 工作嘗試存取未經授權的記憶體。
15 SIGTERM 如果工作超出所設定的逾時時間，就會收到 SIGTERM 信號。應用程式伺服器會傳送 SIGTERM 信號，讓容器執行個體關閉。如果執行個體在收到 SIGTERM 後的幾秒內沒有自行關閉，Cloud Run 就會傳送 SIGKILL 信號，強制終止。如果執行個體使用 SIGTERM 正確結束，可能會回報不同的錯誤代碼；否則，則會傳回 SIGTERM。

強制終止

超出允許記憶體限制的 Cloud Run 容器執行個體會遭到終止。所有仍在容器執行個體上處理的要求，都會結束於 HTTP 500 錯誤。

如果任務超過任務逾時，Cloud Run 會傳送「SIGTERM」信號，表示開始 10 秒的倒數計時，然後才會實際關閉，此時 Cloud Run 會傳送 SIGKILL 信號，關閉容器執行個體。

在此期間，容器執行個體會在整個生命週期中分配 CPU，並且會產生費用。

請參閱SIGTERM 程式碼範例，瞭解如何擷取 SIGTERM 信號。

容器執行個體資源

以下各節說明容器執行個體的資源：

CPU

根據預設，執行個體中的每個 Cloud Run 容器都會分配已設定的 vCPU (預設為 1)。您可以為每個容器分別設定 CPU 限制。

vCPU 會以基礎硬體的抽象方式實作，在變數 CPU 平台上提供單一硬體超執行緒的近似等價 CPU 時間。Cloud Run 使用的所有 CPU 平台都支援 AVX2 指令集。請注意，容器合約不包含任何額外的 CPU 平台詳細資料。

容器可能會同時在多個核心上執行。

對於 Cloud Run 服務，CPU 分配方式取決於所選的計費方式。

如果您選取以執行個體為依據的計費模式，系統會在執行個體的生命週期內分配 CPU。如果您選取以要求為依據的計費模式 (預設)，系統會在執行個體處理要求時分配 CPU。詳情請參閱帳單設定。

如果您已設定最低執行個體數量，就必須使用以執行個體為依據的計費方式，才能在要求之外分配 CPU。

您可以啟用啟動時 CPU 效能強化功能，在執行個體啟動期間暫時增加 CPU 分配，以便縮短啟動延遲時間。

記憶體

根據預設，每個 Cloud Run 容器都會分配已設定的記憶體 (預設為 512 MiB)。您可以為每個容器分別設定記憶體限制。

常見的記憶體用途包括：

  • 載入至記憶體的程式碼，用於執行服務
  • 寫入檔案系統
  • 在容器中執行的其他程序，例如 nginx 伺服器
  • 記憶體內快取系統，例如 PHP OpCache
  • 每個要求的記憶體用量
  • 共用記憶體內磁碟區

GPU

您可以在 Cloud Run 執行個體中設定容器，以便存取 GPU。如果 Cloud Run 服務是搭配附屬容器部署，則部署中只有一個容器可以存取 GPU。如需相關規定和詳細資訊，請參閱「設定 GPU」一文。

NVIDIA 程式庫

根據預設，所有 NVIDIA L4 驅動程式程式庫都會掛載至 /usr/local/nvidia/lib64 底下。Cloud Run 會自動將這個路徑附加至含 GPU 容器的 LD_LIBRARY_PATH 環境變數 (即 ${LD_LIBRARY_PATH}:/usr/local/nvidia/lib64)。這樣一來，動態連結器就能找到 NVIDIA 驅動程式程式庫。連結器會依照您在 LD_LIBRARY_PATH 環境變數中列出的順序搜尋及解析路徑。您在此變數中指定的任何值，都會優先於預設 Cloud Run 驅動程式庫路徑 /usr/local/nvidia/lib64。

如果您想使用 12.2 以上的 CUDA 版本，最簡單的方法是使用較新的 NVIDIA 基本映像檔，並安裝已安裝的向前相容性套件。另一個方法是手動安裝 NVIDIA 向前相容性套件，然後將這些套件新增至 LD_LIBRARY_PATH。請參閱 NVIDIA 的相容性矩陣，判斷哪些 CUDA 版本與提供的 NVIDIA 驅動程式版本 (535.216.03) 相容。

並行 (服務)

對於 Cloud Run 服務，每個 Cloud Run 執行個體預設為多個並行，輸入容器可同時接收多個要求。如要變更這項設定，請設定並行運作功能。

容器沙箱

如果您使用第一代執行環境，Cloud Run 容器會使用 gVisor 容器執行階段沙箱進行沙箱處理。如gVisor 系統呼叫相容性參考資料所述，這個容器沙箱可能不支援某些系統呼叫。

如果您使用第二代執行環境，則可享有完整的 Linux 相容性。Cloud Run 工作一律會使用第二代執行環境。在第二代執行環境中，/sys/class/dmi/id/product_name 會設為 Google Compute Engine。

第二代執行環境會在個別的處理程序命名空間中執行服務程式碼，因此會以具有特殊處理程序語意的容器初始化程序開始。在第一代執行環境中，服務程式碼不會以容器初始化程序執行。

檔案描述元限制

Cloud Run 第一和第二代環境會將程序可開啟的檔案描述元數量限制為 25000。這項做法適用於容器和它建立的任何子程序 (分支)。這是硬性限制。如果超過上限，執行個體可能會耗盡檔案描述元/通訊端。

第二代環境中的限制

第二代環境的限制是標準的 Linux 限制。

舉例來說，可開啟的檔案描述元數量限制 (如 /proc/sys/fs/file-max 所擷取) 會使用約 10% 記憶體的預設值。詳情請參閱核心說明文件中的 file-max 和 file-nr。

同樣地，max_map_count (在 /proc/sys/vm/max_map_count 中擷取) 會設定程序可擁有的記憶體區域數量，使用預設值 65535。詳情請參閱核心說明文件中的 max-map-count。

特殊權限容器和 setuid 二進位檔

Cloud Run 不支援特權容器。因此，Cloud Run 不支援使用 setuid 標記的二進位檔，例如 gcsfuse 或 sudo，因為非 root 使用者可能會因權限不足而失敗。

另一種做法是，以超級使用者身分執行這些二進位檔，然後在執行階段使用 su 指令切換至其他使用者。

舉例來說，請在 Dockerfile 中移除 USER 指示，並在進入點指令碼中使用以下順序：

gcsfuse ...                 # Run gcsfuse as root
su myuser -c "/yourapp.sh"  # Switch to 'myuser' and run 'yourapp.sh'

執行者

如果使用者名稱不存在，Cloud Run 會以 Root 使用者身分 (uid=0) 執行容器。

執行個體中繼資料伺服器

Cloud Run 執行個體會公開中繼資料伺服器，您可以使用該伺服器擷取容器的詳細資料，例如專案 ID、區域、執行個體 ID 或服務帳戶。您也可以使用中繼資料伺服器為服務身分產生權杖。

如要存取中繼資料伺服器資料，請使用 HTTP 要求，並透過 Metadata-Flavor: Google 標頭傳送至 http://metadata.google.internal/ 端點：不需要用戶端程式庫。詳情請參閱「取得中繼資料」。

下表列出部分可用中繼資料伺服器資訊：

路徑 說明
/computeMetadata/v1/project/project-id Cloud Run 服務或工作所屬專案的專案 ID
/computeMetadata/v1/project/numeric-project-id Cloud Run 服務或工作所屬專案的專案編號
/computeMetadata/v1/instance/region 這個 Cloud Run 服務或工作的區域，會傳回 projects/PROJECT-NUMBER/regions/REGION
/computeMetadata/v1/instance/id 執行個體的專屬 ID (也可在記錄中找到)。
/computeMetadata/v1/instance/service-accounts/default/email 這個 Cloud Run 服務或工作所需的服務身分電子郵件地址。
/computeMetadata/v1/instance/service-accounts/default/token 為 此 Cloud Run 服務或工作的服務帳戶產生 OAuth2 存取權杖。Cloud Run 服務代理人用於擷取權杖。這個端點會傳回含有 access_token 屬性的 JSON 回應。如要進一步瞭解如何擷取及使用此存取權杖，請參閱本文。

請注意，Cloud Run 不會提供執行例項所在的 Google Cloud zone 詳細資料。因此，中繼資料屬性 /computeMetadata/v1/instance/zone 一律會傳回 projects/PROJECT-NUMBER/zones/REGION-1。

檔案名稱

在容器中使用的檔案名稱必須與 UTF-8 相容，也就是說，檔案名稱必須是 UTF-8 格式，或可安全地自動轉換為 UTF-8 的格式。如果檔案名稱使用不同的編碼，請在使用 UTF-8 相容檔案名稱的電腦上執行 Docker 建構作業，並避免將檔案複製至含有不相容 UTF-8 名稱的容器。

如果檔案名稱不相容於 UTF-8，容器部署作業就會失敗。請注意，檔案內使用的字元編碼沒有任何限制。

傳出要求逾時

對於 Cloud Run 服務和工作，如果容器的閒置時間超過 10 分鐘，從容器傳送至 VPC 的要求就會逾時。如果是從容器傳送至網際網路的要求，則會在閒置 20 分鐘後逾時。

傳出連線重設

當基礎架構重新啟動或更新時，從容器連往VPC和網際網路的連線串流可能會暫時終止並重新連線。如果應用程式會重複使用長效連線，建議您將應用程式設為重新建立連線，以免重複使用已中斷的連線。