Cloud Run の基礎

Cloud Run は、Google の高度にスケーラブルなインフラストラクチャ上でコード、関数、またはコンテナを実行するための完全マネージド アプリケーション プラットフォームです。インフラストラクチャ管理を抽象化し、3 つの主要なリソースタイプを提供します。

1. Services: 一意で安定したエンドポイントに送信される HTTP リクエストに応答し、ステートレス インスタンスを使用してさまざまなキー メトリクスに基づいて自動スケーリングを行います。イベントと関数にも応答します。
2. Jobs: 手動で実行されるか、スケジュールに基づいて実行される並列化可能なタスクを実行し、完了まで実行します。
3. Worker pools: Kafka コンシューマー、Pub/Sub プル キュー、RabbitMQ コンシューマーなど、常時稼働するプルベースのバックグラウンド ワークロードを処理します。

前提条件

1. Cloud Run Admin API と Cloud Build API を有効にします。

   gcloud services enable run.googleapis.com cloudbuild.googleapis.com --quiet
   

2. ドメイン制限組織ポリシーが認証されていない呼び出しを制限している場合は、プライベート サービスのテストに説明されているようにデプロイされたサービスにアクセスする必要があります。

必要なロール

Cloud Run リソースをデプロイするには、以下のロールが必要です。

• プロジェクトの Cloud Run Admin (roles/run.admin)
• プロジェクトの Cloud Run Source Developer (roles/run.sourceDeveloper)
• サービス アイデンティティの Service Account User (roles/iam.serviceAccountUser)
• プロジェクトの Logs Viewer (roles/logging.viewer)

Cloud Build は、ソース コードおよび Cloud Run リソースを構築するため、この動作をオーバーライドしない限り、Compute Engine のデフォルト サービス アカウントをデフォルトの Cloud Build サービス アカウントとして自動的に使用します。

Cloud Build がソースを構築するには、Cloud Build サービス アカウントにプロジェクトの Cloud Run Builder (roles/run.builder) ロールを付与します。

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:SERVICE_ACCOUNT_EMAIL_ADDRESS \
    --role=roles/run.builder \
    --quiet

PROJECT_ID を Google Cloud プロジェクト ID に、SERVICE_ACCOUNT_EMAIL_ADDRESS を Cloud Build サービス アカウントのメール アドレスに置き換えます。

Cloud Run サービスをデプロイする

コンテナ イメージを使用するか、単一の Google Cloud CLI コマンドでソース コードから直接デプロイすることで、サービスを Cloud Run にデプロイできます。

重要ルール: デプロイされたコードは必ず 0.0.0.0 (127.0.0.1 ではなく) でリッスンし、注入された $PORT 環境変数 (デフォルトは 8080) を使用する必要があります。そうしないと、起動時にクラッシュします。

コンテナ イメージを Cloud Run にデプロイする

Cloud Run はデプロイ時にコンテナ イメージをインポートします。Cloud Run は、このコンテナ イメージのコピーをサービング リビジョンで使用されている限り保持します。新しい Cloud Run インスタンスが起動されると、コンテナ イメージはコンテナ リポジトリから取得されません。

サポートされているコンテナ イメージ

Artifact Registry または Docker Hub に保存されているコンテナ イメージを直接使用できます。Google は Artifact Registry の使用を推奨しています。Docker Hub イメージは最大 1 時間キャッシュされるためです。

Artifact Registry リモート リポジトリを設定することで、他のパブリックまたはプライベート レジストリ (JFrog Artifactory、Nexus、GitHub Container Registry など) からコンテナ イメージを使用できます。

Docker Hub は、Docker Official Images や Docker Sponsored OSS images などの一般的なコンテナ イメージのデプロイのみを検討してください。可用性を高めるために、Google はこれらの Docker Hub イメージを Artifact Registry リモート リポジトリを使用してデプロイすることを推奨しています。

コンテナ イメージをデプロイするには、以下のコマンドを実行します。

    gcloud run deploy SERVICE_NAME \
        --image IMAGE_URL \
        --region us-central1 \
        --allow-unauthenticated \
        --quiet

以下を置き換えます。

• SERVICE_NAME: デプロイするサービスの名前。サービス名は 49 文字以下である必要があり、リージョンとプロジェクトごとに一意である必要があります。サービスがまだ存在しない場合、このコマンドはデプロイ中にサービスを作成します。このパラメーターは完全に省略できますが、省略した場合はサービス名の入力が求められます。
• IMAGE_URL: コンテナ イメージへの参照。例: us-docker.pkg.dev/cloudrun/container/hello:latest。Artifact Registry を使用する場合、リポジトリ REPO_NAME は既に作成されている必要があります。URL は LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG の形式に従います。--image フラグを指定しない場合、deploy コマンドはソース コードからのデプロイを試みることに注意してください。

ソース コードからデプロイする

ソースからサービスをデプロイするには、2 つの異なる方法があります。

• ビルドを使用したソースからのデプロイ (デフォルト): このオプションは、Google Cloud の buildpacks と Cloud Build を使用して、マシンに Docker をインストールしたり、buildpacks や Cloud Build を設定したりすることなく、ソース コードからコンテナ イメージを自動的に構築します。デフォルトでは、Cloud Run は Cloud Build によって提供されるデフォルト マシンタイプを使用します。

  • 自動基本イメージ更新を有効にしてソースからデプロイするには、以下のコマンドを実行します。

    gcloud run deploy SERVICE_NAME --source . \
    --base-image BASE_IMAGE \
    --automatic-updates \
    --quiet
    

    Cloud Run は Google Cloud の buildpacks 基本イメージを使用する自動基本イメージのみをサポートしています。

    • Dockerfile を使用してソースからデプロイするには、以下のコマンドを実行します。

     gcloud run deploy SERVICE_NAME --source . --quiet
    

    Dockerfile を提供すると、Cloud Build はそれをクラウドで実行し、サービスをデプロイします。
    

• ビルドなしでソースからデプロイ (プレビュー): このオプションは、Cloud Build ステップをバイパスして、アーティファクトを直接 Cloud Run にデプロイします。これにより、デプロイ時間が短縮されます。ビルドなしでソースからデプロイするには、以下のコマンドを実行します。

  gcloud beta run deploy SERVICE_NAME \
   --source APPLICATION_PATH \
   --no-build \
   --base-image=BASE_IMAGE \
   --command=COMMAND \
   --args=ARG \
   --quiet
  

  以下を置き換えます。

  • SERVICE_NAME: Cloud Run サービスの名前。
  • APPLICATION_PATH: ローカル ファイルシステム上のアプリケーションの場所。
  • BASE_IMAGE: アプリケーション用に使用するランタイム基本イメージ。例: us-central1-docker.pkg.dev/serverless-runtimes/google-24-full/runtimes/nodejs24。また、osonly24 などの OS のみの基本イメージを使用して、追加の言語固有のランタイム コンポーネントを設定することなく、事前コンパイル済みバイナリをデプロイすることもできます。
  • COMMAND: コンテナの起動時に実行するコマンド。
  • ARG: コンテナ コマンドに送信する引数。複数の引数を使用する場合は、それぞれを別の行に指定します。

  ビルドなしでソースからデプロイする例については、ビルドなしでソースからデプロイする例を参照してください。

Cloud Run ジョブの作成と実行

新しいジョブを作成するには、以下のコマンドを実行します。

gcloud run jobs create JOB_NAME --image IMAGE_URL OPTIONS --quiet

または、deploy コマンドを使用します。

gcloud run jobs deploy JOB_NAME --image IMAGE_URL OPTIONS --quiet

以下を置き換えます。

• JOB_NAME: 作成するジョブの名前。このパラメーターを省略した場合、コマンド実行時にジョブ名の入力が求められます。

• IMAGE_URL: コンテナ イメージへの参照。例: us-docker.pkg.dev/cloudrun/container/job:latest。

• オプションで、OPTIONS を以下のフラグのいずれかで置き換えます。

  • --tasks: 1 以上の整数を指定します。デフォルトは 1。最大は 10,000。各タスクには、0 からタスク数マイナス 1 までの値を持つ CLOUD_RUN_TASK_INDEX 環境変数と、タスク数を示す CLOUD_RUN_TASK_COUNT が提供されます。
  • --max-retries: 失敗したタスクが再試行される回数。任意のタスクがこの限度を超えて失敗すると、ジョブ全体が失敗とマークされます。例えば、1 に設定された場合、失敗したタスクは 1 回再試行され、合計 2 回の試行になります。デフォルトは 3 です。0 から 10 までの整数を受け入れます。
  • --task-timeout: 「2s」などの期間を指定します。デフォルトは 10 分。最大は 168 時間 (7 日)。GPU を使用するタスクの場合、利用可能な最大タイムアウトは 1 時間です。
  • --parallelism: 並列で実行できるタスクの最大数。デフォルトでは、タスクは可能な限り並列に開始されます。
  • --execute-now: 設定された場合、ジョブの作成直後に、ジョブ実行が開始されます。gcloud run jobs create の後に gcloud run jobs execute を呼び出すことと同じです。

  これらのオプションに加えて、環境変数やメモリ制限など、より多くの構成を指定することもできます。

ジョブを作成するときに利用可能なオプションの完全なリストについては、gcloud run jobs create コマンド ラインドキュメントを参照してください。

ジョブ作成が完了するのを待ちます。成功時に成功メッセージが表示されます。

既存のジョブを実行するには、以下のコマンドを実行します。

gcloud run jobs execute JOB_NAME --quiet

実行が完了するまでコマンドが待機するようにする場合は、以下のコマンドを実行します。

gcloud run jobs execute JOB_NAME --wait --region=REGION --quiet

以下を置き換えます。

• JOB_NAME: ジョブの名前。
• REGION: リソースが存在するリージョン。例: europe-west1。または、run/region プロパティを設定します。

ワーカー プールをデプロイする

コンテナ イメージを使用するか、ソースから直接デプロイすることで、Cloud Run ワーカー プールをデプロイできます。

コンテナ イメージをデプロイする

タグ付きコンテナ イメージ (例: us-docker.pkg.dev/my-project/container/my-image:latest) または正確なダイジェスト (例: us-docker.pkg.dev/my-project/container/my-image@sha256:41f34ab970ee...) を指定できます。

サポートされているコンテナ イメージ

Artifact Registry または Docker Hub に保存されているコンテナ イメージを直接使用できます。Google は Artifact Registry の使用を推奨しています。Docker Hub イメージは最大 1 時間キャッシュされるためです。

Artifact Registry リモート リポジトリを設定することで、他のパブリックまたはプライベート レジストリ (JFrog Artifactory、Nexus、GitHub Container Registry など) からコンテナ イメージを使用できます。

Docker Hub は、Docker Official Images や Docker Sponsored OSS images などの一般的なコンテナ イメージのデプロイのみを検討してください。可用性を高めるために、Google はこれらの Docker Hub イメージを Artifact Registry リモート リポジトリを使用してデプロイすることを推奨しています。

コンテナ イメージをデプロイするには、以下のコマンドを実行します。

gcloud run worker-pools deploy WORKER_POOL_NAME --image IMAGE_URL --quiet

以下を置き換えます。

• WORKER_POOL_NAME: デプロイするワーカー プールの名前。ワーカー プールがまだ存在しない場合、このコマンドはデプロイ中にワーカー プールを作成します。このパラメーターは完全に省略できますが、省略した場合はワーカー プール名の入力が求められます。

• IMAGE_URL: ワーカー プールを含むコンテナ イメージへの参照。例: us-docker.pkg.dev/cloudrun/container/worker-pool:latest。--image フラグを指定しない場合、deploy コマンドはソース コードからのデプロイを試みることに注意してください。

デプロイが完了するのを待ちます。デプロイが正常に完了すると、Cloud Run はデプロイされたワーカー プールに関するリビジョン情報とともに成功メッセージを表示します。

ソースからワーカー プールをデプロイする

単一の gcloud CLI コマンド gcloud run worker-pools deploy（--source フラグ付き）を使用して、ソース コードから新しいワーカー プールまたはワーカー プール リビジョンを Cloud Run に直接デプロイできます。

--image または --source フラグを指定しない場合、deploy コマンドはデフォルトでソース デプロイメントになります。

内部的には、このコマンドは Google Cloud の buildpacks と Cloud Build を使用して、マシンに Docker をインストールしたり、buildpacks や Cloud Build を設定したりすることなく、ソース コードからコンテナ イメージを自動的に構築します。デフォルトでは、Cloud Run は Cloud Build によって提供されるデフォルト マシンタイプを使用します。

ソースからワーカー プールをデプロイするには、以下のコマンドを実行します。

gcloud run worker-pools deploy WORKER_POOL_NAME --source . --quiet

WORKER_POOL_NAME をワーカー プールに使用する名前に置き換えます。

デプロイが失敗した場合の対処方法

1. IAM/Permission エラー: iam-security.md を参照してください。
2. 起動時にクラッシュ / ヘルスチェック失敗: gcloud logging read "resource.labels.service_name=SERVICE_NAME" --limit=20 を使用してすぐにログを取得し、正確なランタイム エラーを確認してください。
3. ネイティブ依存関係エラー (Node/Python): --no-build を使用している場合は、ネイティブ拡張機能が Linux 用に適切にコンパイルされるよう --source . (Buildpacks) に切り替えてください。

リファレンス ディレクトリ

• Core Concepts: Services と Jobs と Worker pools、リソース モデル、サービスの自動スケーリング動作。

• CLI Usage: デプロイと管理のための必須 gcloud run コマンド。

• Client Libraries: Google Cloud クライアント ライブラリを使用した Cloud Run との対話。

• MCP Usage: Cloud Run リモート MCP サーバーの使用。

• Infrastructure as Code: Services、Jobs、ワーカー プール、IAM バインディングの Terraform の例。

• IAM & Security: ロール、サービス アイデンティティ、およびイングレス/エグレス制御。

これらのリファレンスに見つからない製品情報が必要な場合は、Developer Knowledge MCP サーバーの search_documents ツールを使用してください。