Contents
スポンサードリンク
統合前提条件と必須 API の有効化
Apigee Edge と Cloud Run をシームレスに連携させるには、まず Google Cloud の基盤サービスをすべて有効化 し、適切な IAM ロールを付与しておくことが不可欠です。これにより、デプロイ時の権限エラーやネットワーク接続不良といった障害を未然に防げます。本セクションでは、必要な API と推奨される有効化手順を具体的に示します。
必要な Google Cloud サービス
以下の API は Apigee Edge と Cloud Run の統合で必ず有効化しておくべきサービスです。表は各 API の主な役割と、無効化した場合に起こり得る影響を併記しています。
| API | 主な役割 | 無効化時の影響 |
|---|---|---|
apigee.googleapis.com |
Apigee Edge 管理機能（組織・環境作成、プロキシ管理） | 組織や環境が作れず、API プロキシをデプロイできない |
run.googleapis.com |
Cloud Run（フルマネージド） | コンテナ化したバックエンドが起動しない |
serviceusage.googleapis.com |
API の有効化・利用状況管理 | 他サービスの有効化操作が失敗する |
cloudlogging.googleapis.com |
ログ収集と可視化 | Cloud Run と Apigee の実行ログが取得できず、トラブルシューティングが困難になる |
iam.googleapis.com |
IAM ポリシー管理 | 権限付与・ロール設定ができない |
有効化手順（gcloud CLI）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
PROJECT_ID=YOUR_PROJECT_ID # プロジェクトを選択 gcloud config set project "$PROJECT_ID" # 必要 API を一括有効化 gcloud services enable \ apigee.googleapis.com \ run.googleapis.com \ serviceusage.googleapis.com \ cloudlogging.googleapis.com \ iam.googleapis.com |
コンソールからも 「API とサービス」→「ライブラリ」 で同様に有効化できます。
詳細は公式ドキュメントの [統合の前提条件]（https://cloud.google.com/apigee/docs/api-platform/integrations/prerequisites）をご参照ください。
IAM ロールと権限設定
適切なロール付与は 最小特権の原則 に沿って行う必要があります。本節では、Apigee‑Cloud Run 連携に最低限必要なロールと、その中身（個別権限）を明示します。
必要ロール一覧
| ロール | 用途・対象 |
|---|---|
roles/apigee.admin |
Apigee 組織・環境の作成・削除、プロキシの管理全般 |
roles/run.developer |
Cloud Run サービスの作成・更新・削除 |
roles/iam.serviceAccountUser |
任意のサービスアカウントを代行実行（Adapter や Cloud Run の SA で必要） |
roles/apigee.runtimeAgent |
Apigee Adapter が Runtime API を呼び出す際に最低限必要な権限 |
roles/apigee.runtimeAgent の最小権限
| 権限 | 説明 |
|---|---|
apigee.environments.invoke |
指定環境のプロキシへリクエストを転送できる |
apigee.developers.get |
開発者情報取得（トラフィック認証に利用） |
apigee.apis.get |
API プロキシ設定の参照 |
apigee.deployments.get |
デプロイ状態の確認 |
serviceusage.services.use |
Apigee Runtime API の呼び出しを許可 |
これら以外の権限は不要です。過剰なロール（例:
roles/editor）は付与しないようにしてください。
ロール付与コマンド例
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
# ユーザーへ管理者ロール付与 gcloud projects add-iam-policy-binding "$PROJECT_ID" \ --member="user:user@example.com" \ --role="roles/apigee.admin" # Cloud Run デベロッパーロール付与 gcloud projects add-iam-policy-binding "$PROJECT_ID" \ --member="user:user@example.com" \ --role="roles/run.developer" # Adapter 用サービスアカウントに最小権限付与 gcloud iam service-accounts create apigee-adapter-sa \ --display-name="Apigee Adapter Service Account" gcloud projects add-iam-policy-binding "$PROJECT_ID" \ --member="serviceAccount:apigee-adapter-sa@$PROJECT_ID.iam.gserviceaccount.com" \ --role="roles/apigee.runtimeAgent" |
Google Cloud プロジェクトと Apigee Edge 環境のセットアップ
このセクションでは、Apigee の組織・環境を 同一 GCP プロジェクト に作成し、Cloud Run と相互に参照できるようにする手順を解説します。正しい構成であれば、API 管理画面から Cloud Run エンドポイントへ直接リンクできます。
Apigee Edge 組織・環境の作成手順
- Apigee コンソール（https://cloud.google.com/apigee）にログイン
- 左側メニューの 「組織」 → 「新規組織」 をクリックし、対象プロジェクトを選択
- 組織 ID は自動生成されますが、変更不可です。覚えやすい文字列（例:
myorg）でメモしておきましょう - デフォルト環境
testとprodが自動作成されます。エンドポイントは次の形式になります
|
1 2 |
https://{org-id}-{env}.apigee.net |
例:
https://myorg-test.apigee.net
VPC 設定と Hybrid との違い
| 項目 | Apigee Edge（パブリック） | Apigee Hybrid |
|---|---|---|
| エンドポイントの公開範囲 | インターネット上に公開された URL が利用可能 | プライベート VPC 内でのみアクセスできる |
| 必要なネットワーク構成 | 基本的に不要。内部サービスへは VPC Connector 経由で呼び出す | 完全にプライベートネットワーク上にデプロイし、GKE クラスタが VPC に所属 |
| セキュリティ管理 | IAM と Apigee のポリシーで制御 | 追加で VPC Service Controls 等の GCP ネットワークセキュリティを適用 |
Edge 環境で内部 Cloud Run 呼び出しが必要な場合
- VPC ネットワーク作成（サブネットは Cloud Run と同一リージョン）
bash
gcloud compute networks create apigee-vpc --subnet-mode=custom - サブネット作成（例:
asia-northeast1）
bash
gcloud compute networks subnets create apigee-subnet \
--network=apigee-vpc \
--region=asia-northeast1 \
--range=10.0.0.0/24 - VPC Access Connector の作成（Cloud Run 側）
bash
gcloud compute networks vpc-access connectors create apigee-connector \
--network=apigee-vpc \
--region=asia-northeast1 \
--range=10.8.0.0/28 - Cloud Run デプロイ時に
--vpc-connector=apigee-connectorを付与
Hybrid では 上記 VPC が必須であり、Apigee のコントロールプレーンが GKE にデプロイされる点が大きく異なります。Edge 環境の場合は「オプション」扱いです。
Cloud Run サービスの作成・デプロイ
本節では、シンプルな Python Flask アプリを例に Cloud Build → Artifact Registry → Cloud Run のフローを実装します。コードと設定ファイルはすべてローカルで管理し、CI/CD パイプラインから自動デプロイできる構成です。
1. ソースコード（main.py）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
from flask import Flask, jsonify import logging, os logging.basicConfig(level=logging.INFO) logger = logging.getLogger(__name__) app = Flask(__name__) @app.route("/hello") def hello(): logger.info("Hello endpoint called", extra={"trace": os.getenv("TRACE_ID")}) return jsonify(message="Hello from Cloud Run!") |
2. requirements.txt
|
1 2 3 |
Flask==3.0.0 gunicorn==22.0.0 |
3. Dockerfile
|
1 2 3 4 5 6 7 8 9 10 |
# Python 公式イメージをベースに使用 FROM python:3.11-slim WORKDIR /app COPY requirements.txt ./ RUN pip install --no-cache-dir -r requirements.txt COPY . . CMD ["gunicorn", "-b", "0.0.0.0:8080", "main:app"] |
4. Cloud Build 設定（cloudbuild.yaml）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
steps: # コンテナイメージのビルド - name: 'gcr.io/cloud-builders/docker' args: - build - '-t' - 'asia-northeast1-docker.pkg.dev/$PROJECT_ID/my-repo/flask-app:$SHORT_SHA' - '.' # Artifact Registry にプッシュ images: - 'asia-northeast1-docker.pkg.dev/$PROJECT_ID/my-repo/flask-app:$SHORT_SHA' |
Artifact Registry リポジトリ作成
|
1 2 3 4 5 |
gcloud artifacts repositories create my-repo \ --repository-format=docker \ --location=asia-northeast1 \ --description="Container images for Cloud Run" |
ビルド実行
|
1 2 |
gcloud builds submit --config cloudbuild.yaml . |
5. Cloud Run デプロイ（認証必須）
|
1 2 3 4 5 6 7 8 |
gcloud run deploy flask-app \ --image=asia-northeast1-docker.pkg.dev/$PROJECT_ID/my-repo/flask-app:$SHORT_SHA \ --region=asia-northeast1 \ --no-allow-unauthenticated \ --platform=managed \ --service-account=my-run-sa@$PROJECT_ID.iam.gserviceaccount.com \ --vpc-connector=apigee-connector # VPC 経由で内部 API 呼び出しが必要な場合 |
ベストプラクティス
- リージョンは
asia-northeast1（東京）または同一アジアリージョンに統一し、レイテンシとデータ所在地要件を満たす - メモリは 512 MiB、CPU は自動スケーリングで十分。トラフィックが増える場合は手動で
--cpuオプションを調整
Apigee Adapter for Envoy のインストールと構成（最新安定版）
Apigee Adapter は Envoy と連携し、Apigee が発行したポリシーを Cloud Run のサイドカーとして適用できるコンポーネントです。2024 年 10 月時点での 最新版 (v2.0.1) を使用する例を示します（将来的なバージョンは公式リリースページをご確認ください）。
⚠️ 本稿では「2026/02/17 更新版」という情報が未確認だったため、公式に公開されている最新安定版 に置き換えました。実装時は必ずリリースノートを参照し、バージョン番号を合わせてください。
バイナリ取得手順
|
1 2 3 4 5 6 7 |
# 例: v2.0.1 のタグ名 ADAPTER_VERSION=v2.0.1 gsutil cp gs://apigee-adapter-releases/${ADAPTER_VERSION}/apigee_adapter_linux_amd64 \ ./apigee_adapter chmod +x ./apigee_adapter |
Envoy 設定（envoy.yaml）
以下は Cloud Run のサイドカーとして動作させる最小構成です。Apigee 組織・環境情報 と サービスアカウントファイル を必ず設定してください。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 |
static_resources: listeners: - name: listener_0 address: socket_address: address: 0.0.0.0 port_value: 8081 # Envoy が受け付けるポート filter_chains: - filters: - name: envoy.filters.network.http_connection_manager typed_config: "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager stat_prefix: ingress_http route_config: name: local_route virtual_hosts: - name: backend domains: ["*"] routes: - match: { prefix: "/" } route: { cluster: service_backend } http_filters: - name: envoy.filters.http.router clusters: - name: service_backend connect_timeout: 0.25s type: LOGICAL_DNS lb_policy: ROUND_ROBIN load_assignment: cluster_name: service_backend endpoints: - lb_endpoints: - endpoint: address: socket_address: address: localhost # Cloud Run 本体のローカルアドレス port_value: 8080 admin: organization: myorg environment: test runtime_uri: https://myorg-test.apigee.net auth: service_account_file: /var/run/secrets/google/service-account.json |
Service Account の作成と最小権限付与
|
1 2 3 4 5 6 7 8 9 |
# サービスアカウント作成 gcloud iam service-accounts create apigee-adapter-sa \ --display-name="Apigee Adapter Service Account" # 最小権限（runtimeAgent）を付与 gcloud projects add-iam-policy-binding "$PROJECT_ID" \ --member="serviceAccount:apigee-adapter-sa@$PROJECT_ID.iam.gserviceaccount.com" \ --role="roles/apigee.runtimeAgent" |
作成したキーは Secret Manager に格納し、コンテナ起動時に /var/run/secrets/google/service-account.json としてマウントしてください。
API プロキシ作成・認証設定
この章では Apigee Edge の UI（または Management API）を使って API プロキシ を作成し、先ほどデプロイした Cloud Run エンドポイントへリクエストを転送する手順と、Google ID Token を用いた認証フローを紹介します。
1. ターゲットエンドポイントに Cloud Run URL を設定
導入文：Apigee のプロキシはバックエンド URL（Target Endpoint）を正確に指定しないと、リクエストが届かず 404 エラーになることがあります。以下の手順で間違いなく設定しましょう。
- Apigee コンソール → 「API プロキシ」 → 「作成」
- プロキシ名（例:
run-proxy）とベースパス（例:/api/v1/）を入力 - Target Endpoint に Cloud Run の URL を貼り付け（例：
https://flask-app-abcdefg-uc.a.run.app） - 保存後、「Deploy」 ボタンで
test環境へデプロイ
2. Google ID Token の検証ポリシー（Verify JWT）
Apigee が受け取った Authorization ヘッダーに含まれる ID Token を検証し、正当な呼び出し元かどうかを判断します。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
<OAuthV2 async="false" continueOnError="false" enabled="true" name="Verify-ID-Token"> <DisplayName>Verify Google ID Token</DisplayName> <Operation>VerifyAccessToken</Operation> <Scope>openid email</Scope> <Tokens> <AccessToken> <Source>request.header.Authorization</Source> </AccessToken> </Tokens> <Issuer>https://accounts.google.com</Issuer> <PublicKeyReference> <JWKSUri>https://www.googleapis.com/oauth2/v3/certs</JWKSUri> </PublicKeyReference> </OAuthV2> |
3. ヘッダー付与ポリシー（AssignMessage）
Apigee が検証したトークンを Cloud Run に転送する際は、正しい変数名 を使用します。Apigee の JWT フィールドは jwt.id_token ではなく jwt.idToken です（実装例は ${jwt.idToken}）。以下のように設定してください。
|
1 2 3 4 5 6 7 8 9 10 11 12 |
<AssignMessage async="false" continueOnError="false" enabled="true" name="Add-ID-Token"> <DisplayName>Add Google ID Token Header</DisplayName> <Set> <Headers> <!-- Authorization ヘッダーに Bearer トークンを付与 --> <Header name="Authorization">Bearer ${jwt.idToken}</Header> </Headers> </Set> <AssignTo createNew="false" transport="http" type="request"/> </AssignMessage> |
ポイント：
Verify-ID-Tokenポリシーで検証したトークンはjwt.idTokenに格納されます。変数名が合っていないと空ヘッダーが送られ、Cloud Run 側で 401 エラーになるので注意してください。
プロキシのデプロイ・テストとトラブルシューティング
本節では、作成した API プロキスを prod 環境へデプロイし、実際にリクエストを送って動作確認する手順と、代表的なエラーへの対処法をまとめます。
1. デプロイ手順
- Apigee コンソールで対象プロキシ（例:
run-proxy）を選択 - 「Deploy Revision」 → 環境
prodを選んでデプロイ - デプロイ完了後、「Revision」 タブで最新リビジョン番号をメモ
2. テスト実行（curl）
|
1 2 3 4 5 6 7 |
# Google ID Token を取得（gcloud CLI） TOKEN=$(gcloud auth print-identity-token) # API 呼び出し例 curl -H "Authorization: Bearer $TOKEN" \ https://myorg-prod.apigee.net/api/v1/hello |
期待されるレスポンス：
|
1 2 3 4 |
{ "message": "Hello from Cloud Run!" } |
3. 代表的エラーと対処法
| ステータス | 主な原因 | 確認ポイント |
|---|---|---|
| 401 Unauthorized | トークンが無効、または Verify-ID-Token が失敗 |
- トークンの有効期限 - Issuer が https://accounts.google.com か確認- JWKS URL にアクセスできるか |
| 404 Not Found | Cloud Run のサービス URL が間違っている | - gcloud run services describe ... --format='value(status.url)' で最新 URL を取得- リージョンが一致しているか |
| 502 Bad Gateway | Adapter/Envoy と Cloud Run 間の接続失敗 | - サイドカーコンテナのログ (docker logs <container-id>) に connection refused が出ていないか- VPC Connector が必要かどうか（内部 API 呼び出しの場合） |
| 503 Service Unavailable | Cloud Run のインスタンスがスケールアウト中 | - Cloud Run の 「リクエスト数」 メトリクスを確認し、CPU/メモリの上限に達していないか |
URL 変更時の手順
- 新しい Cloud Run URL を取得
bash
gcloud run services describe flask-app \
--region=asia-northeast1 \
--format='value(status.url)' - Apigee コンソール → 該当プロキシ → Target Endpoint を編集し、URL を貼り付けて保存
Deploy Revisionでprodに再デプロイ
監視・ロギング設定と CI/CD パイプライン例
本章では、運用フェーズに必須となる ログの一元管理 と 自動デプロイフロー を具体的に示します。Cloud Logging と Apigee Analytics の連携はすでにデフォルトで有効化されていますが、カスタムロギングや GitHub Actions との組み合わせで更なる可観測性を実現できます。
1. Cloud Logging と Apigee Analytics の連携
| 項目 | 設定方法 | 主な活用シーン |
|---|---|---|
| Cloud Run ログ | 自動的に projects/<PROJECT_ID>/logs/run.googleapis.com%2Frequest_log に送信 |
リクエストトレース、エラーレートの可視化 |
| Apigee Analytics | Edge コンソール > Analytics タブで閲覧 | トラフィック、レイテンシ、ステータスコード別集計 |
| カスタムログ（Python） | logging.info("msg", extra={"trace": os.getenv('TRACE_ID')}) で構造化データを出力 |
Cloud Logging の Log Explorer で検索・フィルタリングが容易 |
Python アプリ側のサンプルコード
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
import logging, os logging.basicConfig(level=logging.INFO) logger = logging.getLogger(__name__) @app.route("/hello") def hello(): logger.info( "Hello endpoint called", extra={"trace_id": os.getenv("TRACE_ID", "-")} ) return jsonify(message="Hello from Cloud Run!") |
2. CI/CD パイプライン（GitHub Actions + Cloud Build）
以下は コードのプッシュ → Cloud Build ビルド → Cloud Run デプロイ → Apigee プロキシ更新 を自動化する最小構成です。
cloudbuild.yaml（ビルド・デプロイ・Apigee 更新）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 |
steps: # 1. コンテナイメージをビルドして Artifact Registry にプッシュ - name: 'gcr.io/cloud-builders/docker' args: - build - '-t' - 'asia-northeast1-docker.pkg.dev/$PROJECT_ID/my-repo/flask-app:$SHORT_SHA' - '.' # 2. Cloud Run へデプロイ（認証必須） - name: 'gcr.io/google.com/cloudsdktool/cloud-sdk' entrypoint: bash args: - '-c' - | gcloud run deploy flask-app \ --image=asia-northeast1-docker.pkg.dev/$PROJECT_ID/my-repo/flask-app:$SHORT_SHA \ --region=asia-northeast1 \ --no-allow-unauthenticated \ --platform=managed \ --service-account=my-run-sa@$PROJECT_ID.iam.gserviceaccount.com # 3. Apigee プロキシのリビジョンを最新イメージに更新（Management API 呼び出し） - name: 'curlimages/curl' args: - '-X' - 'POST' - '-H' - "Authorization: Bearer $$(gcloud auth print-access-token)" - "-H" - "Content-Type: application/json" - "--data-binary" - '{"revision":"'$SHORT_SHA'"}' - "https://api.enterprise.apigee.com/v1/organizations/myorg/apis/run-proxy/revisions" |
GitHub Actions ワークフロー（.github/workflows/deploy.yml）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 |
name: CI/CD to Cloud Run & Apigee on: push: branches: [ main ] jobs: build-deploy: runs-on: ubuntu-latest permissions: contents: read id-token: write # Workload Identity Federation 用 steps: - uses: actions/checkout@v3 - name: Set up Cloud SDK uses: google-github-actions/setup-gcloud@v2 with: project_id: ${{ secrets.GCP_PROJECT }} service_account_key: ${{ secrets.GCP_SA_KEY }} - name: Submit Cloud Build run: | gcloud builds submit --config cloudbuild.yaml . |
ポイント
id-token権限を付与すれば Workload Identity Federation が利用でき、長期的な SA キーをリポジトリに保存する必要がなく安全です。- ビルドが成功すると自動で Cloud Run と Apigee の両方が最新イメージへ切り替わります。
次のステップ：本番環境への拡張と無料トライアル活用
ここまでで サンプルアプリを Cloud Run にデプロイし、Apigee Edge で API プロキシを作成・テスト できました。次は本格的な本番運用へ向けた拡張手順と、Google Cloud 無料トライアル（$300 クレジット）を活かす方法をご紹介します。
本番環境へのスケールアップ
- クォータ確認 –
gcloud compute regions describe asia-northeast1で CPU・メモリ上限をチェックし、必要に応じて増枠申請 - リージョン分散 – トラフィックが増える場合は
asia-northeast2（大阪）も併用し、Cloud Load Balancer でフェイルオーバー構成を検討 - バックエンド冗長化 – 同一サービスの複数 Cloud Run インスタンスをデプロイし、Apigee の
TargetEndpointに複数 URL（カンマ区切り）を設定してラウンドロビンさせる - 予算アラート設定 – Cloud Billing の予算機能で
$300超過前に Slack やメールで通知を受け取るようにする
無料トライアル活用のベストプラクティス
| 項目 | 推奨アクション |
|---|---|
| クレジット期間 | 90 日間有効。期限前に課金プランへ移行し、設定した予算・アラートをそのまま引き継ぐ |
| リソース最適化 | Cloud Run の自動スケーリングと 最低インスタンス数 0 をデフォルトにして、アイドル時の課金を抑制 |
| モニタリング | Cloud Monitoring の ダッシュボード に CPU・メモリ・ネットワーク使用率を可視化し、無駄なリソース消費を即座に検知 |
実践への第一歩：本稿の手順をローカルで試したら、同じ構成を GitHub リポジトリへプッシュし、GitHub Actions が自動的にデプロイする流れを体感してください。その後、無料クレジットを使い切る前に 本番規模のリージョン分散 と 予算アラート を設定すれば、スムーズに本格運用へ移行できます。
まとめ
- 必要な API を有効化し、最小権限（
roles/apigee.runtimeAgent等）を正しく付与することで、権限エラーを防止 - VPC 設定は Edge と Hybrid の違い を意識し、内部 API 呼び出しが必要な場合のみ構成すれば OK
- Apigee Adapter は公式の最新バージョン（執筆時点 v2.0.1）を使用し、
jwt.idToken変数名でヘッダー付与を行うことがポイント - Cloud Run と Apigee の CI/CD パイプラインは GitHub Actions + Cloud Build がシンプルかつ安全（Workload Identity Federation 推奨）
- 本番環境への拡張はリージョン分散・冗長化・予算管理を徹底し、無料トライアルのクレジットを有効活用
以上が Apigee Edge と Cloud Run の統合 に関する最新ベストプラクティスです。ぜひ本稿を手引きに、実際のプロジェクトで試してみてください。
スポンサードリンク