コンテナ ランタイムの契約

このページでは、Cloud Run のコンテナの主な要件と動作について説明します。Cloud Run サービスと Cloud Run ジョブにはいくつかの違いがあります。これらは必要に応じて説明します。

サポートされる言語とイメージ

このページに記載されている制約を遵守すると、コンテナ イメージでは任意のプログラミング言語で書かれたコードを実行でき、任意のベースイメージを使用できます。

コンテナ イメージ内の実行可能ファイルは、Linux 64 ビット用にコンパイルする必要があります。Cloud Run は特に Linux x86_64 ABI 形式をサポートしています。

Cloud Run は、Docker イメージ マニフェスト V2、スキーマ 1、スキーマ 2、OCI のイメージ形式のコンテナ イメージを受け入れます。Cloud Run は、Zstd 圧縮されたコンテナ イメージも受け入れます。

マルチ アーキテクチャ イメージをデプロイする場合は、マニフェスト リストに linux/amd64 を含める必要があります。

Cloud Run でデプロイされる関数の場合、Google Cloud の Buildpack によって公開されている Cloud Run ランタイム ベースイメージのいずれかを使用して、セキュリティとメンテナンスの更新を自動的に受け取ることができます。サポートされているランタイムについては、ランタイム サポートのスケジュールをご覧ください。

正しいポートでのリクエストのリッスン（サービス）

Cloud Run サービスが、受信リクエストを処理するために Cloud Run インスタンスを起動します。Cloud Run インスタンスには、リクエストをリッスンする Ingress コンテナが常に 1 つあり、必要に応じて 1 つ以上のサイドカー コンテナがあります。次のポート構成の詳細は、Ingress コンテナにのみ適用され、サイドカーには適用されません。

インスタンス内の Ingress コンテナは、リクエストの送信先ポートで 0.0.0.0 のリクエストをリッスンする必要があります。デフォルトでリクエストは 8080 に送信されますが、選択したポートにリクエストを送信するように Cloud Run を構成することもできます。Cloud Run は、PORT 環境変数を ingress コンテナに追加します。

ジョブの実行中に動作するコンテナは、完了時に終了しなければならない

Cloud Run ジョブの場合、ジョブが正常に完了したときに、コンテナは終了コード 0 で終了する必要があります。ジョブが失敗した場合は、ゼロ以外の終了コードで終了する必要があります。

ジョブはリクエストを処理しないため、コンテナでポートのリッスンや、ウェブサーバーの起動は行わないでください。

Transport Layer Encryption（TLS）

コンテナに Transport Layer Security を直接実装しないでください。TLS は HTTPS および gRPC 対応の Cloud Run によって終了し、リクエストは TLS なしで HTTP/1 または gRPC としてコンテナにプロキシされます。

Cloud Run サービスを構成して、HTTP/2 エンドツーエンドを使用する場合、コンテナは HTTP/2 クリアテキスト（h2c）形式でリクエストを処理する必要があります。これは、TLS が Cloud Run によって引き続き自動的に終了するためです。

レスポンス（サービス）

Cloud Run サービスの場合、コンテナは、リクエストを受信してからリクエスト タイムアウト設定で指定された時間内に、コンテナの起動時間を含むレスポンスを送信する必要があります。その時間を過ぎると、リクエストが終了し、504 エラーが返されます。

レスポンスのキャッシュ保存と Cookie

Cloud Run サービスのレスポンスに Set-Cookie ヘッダーが含まれている場合、Cloud Run は Cache-Control ヘッダーを private に設定して、レスポンスがキャッシュに保存されないようにします。これにより、他のユーザーが Cookie を取得できなくなります。

環境変数

Cloud Run サービスとジョブでは、異なる環境変数のセットを使用できます。

サービスの環境変数

次の環境変数は、PORT を除くすべての実行中のコンテナに自動的に追加されます。PORT 変数は Ingress コンテナにのみ追加されます。

名前	説明	例
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 に限定されます。また、コロンを含めることはできません。ヘッダーの値は、IETF RFC 7230 に従って、表示される ASCII 文字とスペースと水平タブに制限されます。

ファイル システムへのアクセス

各コンテナ内のファイル システムは書き込み可能で、次の動作の影響を受けます。

• これはインメモリ ファイル システムであるため、書き込みにはインスタンスのメモリが使用されます。
• インスタンスが停止すると、ファイル システムに書き込まれたデータは保持されません。

このファイル システムにはサイズの上限を指定できないため、インメモリ ファイル システムに書き込むことでインスタンスに割り当てられたすべてのメモリを使い果たし、その結果、インスタンスがクラッシュする可能性があります。サイズの上限が設定された専用のインメモリ ボリュームを使用すると、この問題を回避できます。

インスタンスのライフサイクル

ライフサイクルの特性は、Cloud Run ジョブとサービスで異なるため、以降のサブセクションで分けて説明します。

サービスの場合

以下の説明は、サービスにのみ適用されます。

サービスのスケーリング

Cloud Run サービスは、すべての受信リクエスト、イベント、CPU 使用率を処理するために必要なインスタンス数に自動的にスケーリングされます。

すべてのインスタンスは、所定の数のコンテナ（1 つ Ingress コンテナと、オプションで 1 つ以上のサイドカー コンテナ）を実行します。

リビジョンがトラフィックを受信しない場合、構成されたインスタンスの最小数にスケールインされます（デフォルトはゼロ）。

スタートアップ

Cloud Run サービスの場合、インスタンスは起動後 4 分以内にリクエストをリッスンする必要があります。また、インスタンス内のすべてのコンテナが良好な状態である必要があります。この起動時間でインスタンスに CPU が割り当てられます。起動時の CPU ブーストを有効にすることで、インスタンスの起動時に一時的に CPU 割り当てを増やして起動レイテンシを短縮できます。

構成されたポートでリッスンしているので、リクエストはすぐに Ingress コンテナに送信されます。

インスタンスを待機しているリクエストは、次のようにキュー内で保留状態になります。

• スケールアウト中など、新しいインスタンスが起動されると、少なくともこのサービスのコンテナ インスタンスの平均起動時間の間はリクエストが保留されます。これには、ゼロからのスケーリングなど、リクエストでスケールアウトが開始されるタイミングも含まれます。
• 起動時間が 10 秒未満の場合、リクエストは最大で 10 秒間保留されます。
• 起動プロセスにインスタンスがなく、リクエストがスケールアウトを開始しない場合、リクエストは最大で 10 秒間保留されます。

起動プローブを構成して、コンテナが起動してリクエストに対応する準備ができているかどうかを判断できます。

マルチコンテナ インスタンスで構成される Cloud Run サービスの場合、コンテナの起動順序を構成することで、インスタンス内でコンテナを起動する順序を指定できます。

リクエストの処理

Cloud Run サービスの場合、Cloud Run リビジョンが少なくとも 1 つのリクエストを処理している限り、CPU はインスタンス内のサイドカーを含むすべてのコンテナに必ず割り当てられます。

アイドル状態

Cloud Run サービスの場合、アイドル状態のインスタンスは、リクエストを処理していないインスタンスです。

アイドル状態のインスタンス内のすべてのコンテナに割り当てられる CPU は、構成された CPU の割り当てによって異なります。

インスタンスの最小数の構成でインスタンスをアイドル状態にする必要がある場合を除き、15 分以上アイドル状態になることはありません。

シャットダウン

Cloud Run サービスの場合、アイドル状態のインスタンスは、最小数のインスタンスを介してウォーム状態を維持するインスタンスを含め、いつでもシャットダウンできます。リクエストを処理しているインスタンスをシャットダウンする必要がある場合、新しい受信リクエストは他のインスタンスに転送され、現在処理されているリクエストに完了までの時間が与えられます。例外として、Cloud Run がシャットダウンを開始し、まだリクエストを処理しているコンテナに SIGTERM シグナルを送信する場合があります。

インスタンスをシャットダウンする前に、Cloud Run から SIGTERM シグナルがインスタンス内のすべてのコンテナに送信されます。これは、Cloud Run が SIGKILL シグナルを送信してから 10 秒後に実際のシャットダウンが開始することを表しています。この期間中、インスタンスに CPU が割り当てられ、課金されます。第 1 世代の実行環境を使用するサービスでは、インスタンスが SIGTERM シグナルをトラップしない場合、直ちにシャットダウンされます（SIGTERM シグナルをトラップする方法については、コードサンプルをご覧ください）。

強制終了

1 つ以上の Cloud Run コンテナがコンテナのメモリ上限を超えると、インスタンスは終了します。インスタンスで処理中のすべてのリクエストは、HTTP 500 エラーで終了します。

ジョブの場合

Cloud Run ジョブの場合、コンテナ インスタンスは、コンテナ インスタンスが終了するか、タスク タイムアウトに達するか、コンテナがクラッシュするまで実行されます。

強制終了

メモリ制限の上限を超える Cloud Run コンテナ インスタンスは終了します。コンテナ インスタンスで処理中のすべてのリクエストは、HTTP 500 エラーで終了します。

タスクがタスク タイムアウトを超えると、Cloud Run は実際のシャットダウンが発生する 10 秒前の開始を示す「SIGTERM」シグナルを送信します。シャットダウンの際は、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 割り当てを増やして起動レイテンシを短縮できます。

メモリ

デフォルトでは、各 Cloud Run コンテナに構成されたメモリが割り当てられます（デフォルトでは 512 MiB）。各コンテナに個別にメモリ上限を構成できます。

メモリの一般的な用途は次のとおりです。

• サービスを実行するためのコードの読み込み
• ファイルシステムへの書き込み
• nginx サーバーなどのコンテナ内で実行する別のプロセス
• PHP の OpCache などのメモリ内キャッシュ システム
• リクエストごとのメモリ使用量
• 共有インメモリ ボリューム

GPU

GPU にアクセスするように Cloud Run インスタンスのコンテナを構成できます。Cloud Run サービスがサイドカー コンテナとともにデプロイされている場合、デプロイ内の 1 つのコンテナのみが GPU にアクセスできます。要件と詳細については、GPU を構成するをご覧ください。

NVIDIA ライブラリ

デフォルトでは、すべての NVIDIA L4 ドライバ ライブラリが /usr/local/nvidia/lib64 にマウントされます。

提供されたライブラリをサービスが見つけられない場合は、Dockerfile に ENV LD_LIBRARY_PATH /usr/local/nvidia/lib64:${LD_LIBRARY_PATH} 行を追加して、ダイナミック リンカーの検索パスを更新します。

既存のイメージがあり、更新された Dockerfile でイメージを再ビルドしない場合は、Cloud Run サービスの環境変数として LD_LIBRARY_PATH を設定することもできます。

12.2 より大きい CUDA バージョンを使用する場合は、上位互換性パッケージがすでにインストールされている新しい NVIDIA ベースイメージを利用するのが最も簡単な方法です。別の方法として、NVIDIA の上位互換性パッケージを手動でインストールし、LD_LIBRARY_PATH に追加することもできます。NVIDIA の互換性マトリックスを参照して、提供されている NVIDIA ドライバ バージョン（535.129.03）と上位互換性がある CUDA バージョンを確認します。

同時実行（サービス）

Cloud Run サービスの場合、各 Cloud Run インスタンスにはデフォルトで複数の同時実行が設定されます。ここで、Ingress コンテナは複数のリクエストを同時に受信できます。これを変更するには、同時実行の設定を行います。

コンテナ サンドボックス

第 1 世代の実行環境を使用する場合、Cloud Run コンテナは、gVisor コンテナ ランタイム サンドボックスを使用してサンドボックス化されます。gVisor syscall 互換性リファレンスに記載されているように、このコンテナ サンドボックスでは一部のシステムコールがサポートされていない場合があります。

第 2 世代の実行環境を使用している場合は、Linux との完全な互換性があります。Cloud Run ジョブは、常に第 2 世代の実行環境を使用します。第 2 世代の実行環境では、/sys/class/dmi/id/product_name は Google Compute Engine に設定されます。

第 2 世代の実行環境では、サービスコードが別のプロセス名前空間で実行されるため、特別なプロセス セマンティクスを持つコンテナ init プロセスとして開始されます。第 1 世代の実行環境では、サービスコードはコンテナ init プロセスとして実行されません。

インスタンス メタデータ サーバー

Cloud Run インスタンスは、プロジェクト ID、リージョン、インスタンス ID、サービス アカウントなど、コンテナに関する詳細情報を取得するために使用できるメタデータ サーバーを公開します。メタデータ サーバーを使用して、サービス ID のトークンを生成することもできます。

メタデータ サーバーのデータにアクセスするには、Metadata-Flavor: Google ヘッダーを使用して http://metadata.google.internal/ エンドポイントに HTTP リクエストを送信します。クライアント ライブラリは必要ありません。詳細については、メタデータの取得をご覧ください。

次の表に、利用可能なメタデータ サーバー情報の一部を示します。

パス	説明
/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	インスタンスの一意の識別子（ログでも使用可能）
/computeMetadata/v1/instance/service-accounts/default/email	この Cloud Run サービスまたはジョブのサービス ID のメールアドレス。
/computeMetadata/v1/instance/service-accounts/default/token	この Cloud Run サービスまたはジョブのサービス アカウントの OAuth2 アクセス トークンを生成します。Cloud Run サービス エージェントはトークンの取得に使用されます。このエンドポイントは、access_token 属性を含む JSON レスポンスを返します。このアクセス トークンを抽出して使用する方法について詳しくは、こちらをご覧ください。

Cloud Run では、インスタンスが実行されている Google Cloud ゾーンに関する詳細情報は提供されません。そのため、メタデータ属性 /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 のサービスとジョブでは、コンテナから VPC へのリクエストで 10 分間アイドル状態が継続するとタイムアウトが発生します。コンテナからインターネットへのリクエストの場合は、20 分間のアイドル時間の後にタイムアウトが発生します。

アウトバウンド接続のリセット

コンテナから VPC とインターネットの両方への接続ストリームは、基盤となるインフラストラクチャの再起動や更新時に終了したり、置き換える場合があります。アプリケーションで長期間の接続を再利用する場合は、切断された接続の再利用を避けるため、接続を再確立してアプリケーションを構成することをおすすめします。