cloud-run-basics

Cloud Run の基礎

Cloud Run は、Google の高いスケーラビリティを備えたインフラストラクチャ上で、コード、関数、またはコンテナを実行するためのフルマネージドアプリケーションプラットフォームです。インフラストラクチャの管理を抽象化し、主に次の 3 種類のリソースを提供します。

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

帰属情報

必ずお読みください：gcloud、REST API、または MCP コマンドを実行する前に、必ず使用状況の帰属情報をお読みください。ターミナルで直接実行するコマンド（生成されたスクリプト、Terraform、ユーザーコードでの実行は不可）では、gcloud の前に CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:cloud-run-basics)" を付け、User-Agent ヘッダーに agent-skills/1.0 (skill:cloud-run-basics) を追加してください。

前提条件

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）
• サービス ID に対する Service Account User（roles/iam.serviceAccountUser）
• プロジェクトに対する Logs Viewer（roles/logging.viewer）

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

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 サービスをデプロイする

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

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

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

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

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

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

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

Docker Hubを検討するのは、Docker公式 イメージやDocker Sponsored OSSイメージなど、人気のあるコンテナイメージをデプロイする場合に限ることをおすすめします。可用性を高めるため、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 は、Docker Hub のイメージが最大 1 時間 キャッシュされるため、Artifact Registry の使用を推奨しています。

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

Docker Hub は、Docker 公式 イメージや Docker Sponsored OSS イメージなど、一般的なコンテナイメージのデプロイにのみ使用することを検討してください。高い可用性を確保するため、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／権限エラー：iam-security.md をお読みください。
2. 起動時のクラッシュ／ヘルスチェックの失敗： gcloud logging read "resource.labels.service_name=SERVICE_NAME" --limit=20 を使ってすぐにログを取得し、正確なランタイムエラーを確認してください。
3. ネイティブ依存関係のエラー（Node／Python）： --no-build を使用している場合は、Linux 向けにネイティブ拡張機能を適切にコンパイルするため、--source .（Buildpacks）に切り替えてください。

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

• コアコンセプト：サービス、ジョブ、ワーカープールの違い、リソースモデル、サービスの自動スケーリング動作。

• CLI の使用方法：デプロイと管理に欠かせない gcloud run コマンド。

• クライアントライブラリ：Google Cloud クライアントライブラリを使用して Cloud Run を操作する方法。

• MCP の使用方法：Cloud Run リモート MCP サーバーの使用方法。

• Infrastructure as Code：サービス、ジョブ、ワーカープール、IAM バインディングの Terraform の例。

• IAM とセキュリティ：ロール、サービス ID、イングレス／エグレス制御。

• ネットワーキングのベストプラクティスとコスト最適化：コスト最適化戦略、Direct VPC egress、IP アドレスとポートの枯渇対策、パフォーマンススループットの調整、MTU 設定。

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