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

コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

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

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

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

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

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

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

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

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

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

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 エラーが返されます。

環境変数

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

サービスの環境変数

次の環境変数が実行中のコンテナに自動的に追加されます。

名前 説明 例
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」までの一意の値が設定されます。 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 サービスの場合、受信リクエストに応じて、サービスは特定の数のコンテナ インスタンスに自動的にスケールアウトされ、インスタンスごとにデプロイされたコンテナ イメージを実行します。

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

起動

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

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

コンテナ インスタンスの起動を待つリクエストは最大 10 秒間キューに保持されます。

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

リクエストの処理

Cloud Run サービスの場合、CPU は、コンテナ インスタンスが 1 つ以上のリクエストを処理する際に必ず割り当てられます。

アイドル状態

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

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

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

シャットダウン

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

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

強制終了

メモリ制限の上限を超える 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 つ）。

vCPU は、基盤となる CPU を抽象化して実装し、利用可能な CPU プラットフォームに対して単一ハードウェアのハイパースレッドとほぼ同等の CPU 時間を提供します。 Cloud Run で使用されるすべての CPU プラットフォームは、AVX2 命令セットをサポートしています。コンテナ契約には追加の CPU プラットフォームの詳細が含まれていないことに注意してください。

コンテナ インスタンスは、複数のコアで同時に実行できます。

Cloud Run サービスの場合、CPU をインスタンスのライフサイクル期間中に常に割り当てることも、コンテナ インスタンスの起動時とリクエストを処理する際にのみ割り当てるように設定することもできます。詳しくは、CPU の割り当てをご覧ください。

最小インスタンス数を構成している場合、これらのインスタンスも CPU 割り当て構成の対象となります。

起動時の CPU ブーストを有効にすることで、コンテナ インスタンスの起動時に一時的に CPU 割り当てを増やして起動レイテンシを短縮できます。

メモリ

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

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

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

同時実行（サービス）

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

コンテナ インスタンスのサンドボックス

第 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、サービス アカウントなど、コンテナ インスタンスに関する詳細情報を取得するために使用できるメタデータ サーバーを公開します。これは、ランタイム サービス アカウントのトークンを生成するためにも使用できます。

メタデータ サーバーからこのデータにアクセスするには、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 サービスまたはジョブのランタイム サービス アカウントのメールアドレス。
/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 に変換してからデプロイする必要があります。

アウトバウンド接続

アウトバウンド リクエストのタイムアウト

Cloud Run のサービスとジョブでは、コンテナから VPC へのリクエストで 10 分間アイドル状態が継続するとタイムアウトが発生します。コンテナからインターネットへのリクエストの場合は、20 分間のアイドル時間の後にタイムアウトが発生します。

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

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