Cloud Run functionsのデプロイの裏側で起きていることを理解する

はじめに

この記事はフューチャー Advent Calendar 2025の19日目の記事です。

こんにちは。
フューチャーアーキテクト 製造・エネルギーサービス事業部の片岡です。
業務の中でCloud Run functionsを利用していて、デプロイプロセスまわりの理解に苦戦したため、まとめ記事を書いてみました。
Cloud Run functionsは、マネージドサービスでコードを書くだけでアプリをデプロイできる便利なサービスですが、裏側でどのようなプロセスが動いているのかが、一見わかりづらいので、トラブルシューティングの際に役立てば幸いです。

Cloud Run functionsとは

Cloud Run functionsは、Google Cloudが提供するサーバーレスコンピューティングサービスであり、Cloud Functionsの第2世代にあたります。
Cloud Run functionsは、Cloud Runのインフラストラクチャ上で動作し、コンテナの作成や管理を自動化することで、開発者がコードの実装に集中できるように設計されています。

Cloud Run関連のサービスはいくつかあり、関連するドキュメントを読んでも、どのサービスのことを言っているのかわかりづらい場合があります。
全体像の整理として、下記の@AoTo0330さんの記事が非常にわかりやすいですので、躓いた際は、こちらを参照してみてください。

Cloud Run functionsのデプロイプロセス

早速ですが、Cloud Run functionsがデプロイされる際の大まかなプロセスは以下の通りです。

https://docs.cloud.google.com/run/docs/functions/overview?hl=ja

1. ローカル環境からソースコードがCloud Storageにアップロードされる
2. Cloud Buildがトリガーされ、Cloud Storageからソースコードを取得し、ソースコードをビルドしコンテナイメージを作成する
3. 作成したコンテナイメージをArtifact Registryにプッシュする
4. Cloud Run functionsがArtifact Registryからコンテナイメージを取得し、デプロイされる

Cloud Run functionsのデプロイプロセスに関する詳細は、下記の公式ドキュメントに記載されています。

Cloud Run functionsのデプロイにあたって必要な権限

Cloud Run functions（第2世代）のデプロイプロセスは、ユーザーによるデプロイ操作（gcloud functions deploy コマンドの実行など）を起点として、以下の2段階で進みます。

1. ユーザーがソースコードを Cloud Storage にアップロードする
2. Cloud Buildがそのソースコードを取得してコンテナをビルドし、デプロイする
   そのため、権限エラーが出たときは「自分（ユーザー）」と「Cloud Build」、どちらの権限が不足しているかを確認することが重要です。

デプロイを実行するユーザー（自分）に必要な権限

開発者が CLI (gcloud functions deploy) でローカルのソースコードをデプロイする場合、以下の権限が必要です。

• Cloud functions 開発者 (roles/cloudfunctions.developer)
  • 関数の作成や更新を行うための基本的な権限です。
• サービス アカウント ユーザー (roles/iam.serviceAccountUser)
  • 関数が実行時に使用するサービスアカウント（ランタイム サービスアカウント）になり代わるために必要な権限です。
• Cloud Run 開発者 (roles/run.developer)
  • 第2世代の関数は実体が Cloud Run サービスであるため、Cloud Run へのデプロイ権限も必要です。
• Cloud Storage へのアクセス権限
  • デプロイ時のソースコードアップロードのため、以下の2つのロールが必要です。
    • Storage オブジェクト管理者 (roles/storage.objectAdmin)
    • Storage レガシー バケット 読み取り (roles/storage.legacyBucketReader)
      • ※ Storage オブジェクト管理者だけでは、デプロイコマンド実行時に必要な storage.buckets.get（バケットの存在確認）の権限が不足するため、Storage レガシー バケット 読み取り も併せて付与する必要があります。

Cloud Buildサービスアカウントに必要な権限

ソースコードをコンテナイメージにビルドし、Artifact Registry にプッシュするのは、ユーザーではなく Cloud Buildサービスアカウントです。

• Artifact Registry 書き込み (roles/artifactregistry.writer)
  • ビルドしたコンテナイメージを保存するために必要です。
• ログ書き込み (roles/logging.logWriter)
  • ビルドログを出力するために必要です。
• Storage オブジェクト閲覧者 (roles/storage.objectViewer)
  • ユーザーがアップロードしたソースコードを、Cloud Buildが取得（ダウンロード）するために必要です。

さいごに

本記事では、Cloud Run functionsのデプロイプロセスと、そこで求められる権限周りについて整理しました。

Cloud Run functionsのようなマネージドサービスは、裏側の複雑な処理をクラウド側が「よしなに」やってくれる便利さがある一方で、そのプロセスがブラックボックスになりがちです。そのため、いざエラーが発生すると原因特定に時間がかかってしまうことも少なくありません。

今回の記事が、デプロイ周りの「見えないプロセス」を理解する手助けとなり、同じような問題で躓いている方の参考になれば幸いです。