Apigee ハイブリッド導入ガイド：IAM設定・組織作成・Runtime デプロイ手順

2026年6月8日

もっとスキルを活かしたいエンジニアへ

スポンサードリンク

働き方から選べる

無料で使えて良質な案件の情報収集ができるサービス

エンジニアの世界では、「いつでも動ける状態を作っておけ」とよく言われます。
技術やポートフォリオがあっても、自分に合う案件情報を日常的に見れていないと、いざ動こうと思った時に比較や判断が難しくなってしまいます。
普段から案件情報が集まる環境を作っておくと、良い案件が出た時にすぐ動きやすくなりますよ。
筆者自身も、メガベンチャー勤務時代に年収1,500万円を超えた経験があります。振り返ると、技術だけでなく「どんな案件や働き方があるか」を日頃から見ていたことが、キャリアの選択肢を広げるきっかけになりました。
このブログを読んでくれた方に感謝を込めて、実際に使っている情報収集サービスを紹介します。

フルリモート・週3日・高単価、どんな条件も妥協したくないなら

フリーランスボードに無料会員登録する

利用者10万人以上。業界最大規模45万件の案件。AIマッチ機能や無料の相場情報が人気。

年収800万円以上のキャリアアップ・ハイクラス正社員を視野に入れているなら

Beyond Careerに無料相談する

内定獲得率90%以上。紹介先企業とは役員クラスのコネクションがある安心と信頼できるエージェント。

Contents

1 導入前提条件と IAM ロール設定
- 1.1 前提条件の概要
- 1.2 推奨 IAM ロールと最小権限
2 Apigee のデプロイモデル比較と組織作成
3 Hybrid 環境構築と Runtime デプロイ手順
- 3.1 GKE クラスタ要件と作成例
  - 3.1.1 GKE クラスタ作成コマンド例
- 3.2 Apigee Runtime の Helm インストール手順
4 API プロキシ作成・環境設計と自動化ベストプラクティス
5 運用・トラブルシューティング、モニタリングと継続的改善
6 まとめ

スポンサードリンク

導入前提条件と IAM ロール設定

このセクションでは、Apigee Hybrid を本番環境で利用開始するために必須となる GCP プロジェクトの準備と、最小権限で安全に運用できる IAM ロールの付与方法を解説します。前提条件が整っていないと組織作成や Runtime デプロイ時に権限エラーが頻発し、導入作業が滞ります。

前提条件の概要

Apigee Hybrid を動かすには GCP プロジェクト と 課金アカウント が紐付いていること、さらに以下の API が有効化されている必要があります。

apigee.googleapis.com – Apigee 管理 API
cloudresourcemanager.googleapis.com – 組織・プロジェクト管理
iam.googleapis.com – IAM 設定操作
container.googleapis.com – GKE（Hybrid の Runtime が稼働する）

詳細は公式ドキュメントの「Apigee Hybrid 用 GCP プロジェクトの準備」をご参照ください。

推奨 IAM ロールと最小権限

ロール名	権限（例）	主な付与対象
Apigee Admin (`roles/apigee.admin`)	`apigee.organizations.create`, `apigee.environments.*` など組織・環境全般の管理権限	プラットフォーム運用担当者
Apigee Viewer (`roles/apigee.viewer`)	`apigee.apis.get`, `apigee.analytics.read` 等の閲覧専用権限	監査チーム・経営層
Apigee Runtime Agent (`roles/apigee.runtimeAgent`)	Runtime が GKE 上で動作するために必要な `apigee.runtime.*` 系権限（Hybrid 推奨）	Hybrid 用サービスアカウント
Service Account User (`roles/iam.serviceAccountUser`)	サービスアカウントの使用許可	デプロイスクリプト・CI/CD パイプライン

ベストプラクティス
Apigee Admin は最小人数に限定し、細かい権限は カスタムロール（例：apigee.envAdmin) を作成して付与します。
サービスアカウントのキーは Cloud KMS で暗号化し、不要になったらすぐに無効化してください。

IAM の詳細設定手順は「Apigee Hybrid のサービスアカウントとロールの設定」にまとめられています。

Apigee のデプロイモデル比較と組織作成

この章では、Apigee が提供する 3 種類のデプロイモデル（Edge・X・Hybrid）の特徴を比較し、最適なモデル選定のポイントを示したうえで、実際に Apigee 組織 をコンソールまたは gcloud CLI から作成する手順を解説します。

デプロイモデルの比較表

項目	Apigee Edge	Apigee X	Apigee Hybrid
管理形態	完全マネージド（Google がインフラ全体）	Google Cloud ネイティブ、統合監視・IAM	Runtime を顧客側 GKE/Anthos にデプロイ
可用性	グローバルリージョン単位の冗長化	同上＋組織横断 IAM 統合	クラスタごとの設計が必要（マルチゾーン推奨）
カスタマイズ性	UI でポリシー設定のみ	X の追加機能は限定的	コンテナ・ネットワーク設定を自由に変更可能
適用シナリオ	小規模～中規模、即時導入が目的	大企業の全社標準化、Google エコシステム活用	ハイブリッド／マルチクラウド戦略・データレジデンシー要件あり

公式比較表は「Apigee Hybrid と他モデルの違い」に掲載されています。

組織作成 – コンソール編

コンソールから組織を作成する手順は、UI が直感的で初心者向きです。
1. Google Cloud Console → Apigee → 組織 (Org) の管理 を開く。
2. 「新しい組織を作成」ボタンをクリックし、以下項目を入力する。
* Organization ID（例：my-company-org）
* Display name（任意の表示名）
* プロジェクト（事前に用意した GCP プロジェクト）
3. 必要に応じて Analytics リージョン を選択し、作成を実行。数分後にステータスが ACTIVE へ遷移します。

組織作成 – gcloud CLI 編

CLI は自動化やスクリプト化に最適です。以下は Hybrid 用の組織作成例です。

# Apigee コンポーネントが未インストールの場合は先に取得
gcloud components install apigee

# 組織作成コマンド
gcloud apigee organizations create my-company-org \
  --project=my-gcp-project \
  --display-name=&quot;My Company Apigee Org&quot; \
  --analytics-region=us-central1 \
  --runtime-type=HYBRID   # HYBRID（Hybrid）または CLOUD（Edge/X）のいずれかを指定

# Apigee コンポーネントが未インストールの場合は先に取得

gcloud components install apigee

# 組織作成コマンド

gcloud apigee organizations create my-company-org \

--project=my-gcp-project \

--display-name="My Company Apigee Org" \

--analytics-region=us-central1 \

--runtime-type=HYBRID # HYBRID（Hybrid）または CLOUD（Edge/X）のいずれかを指定

--runtime-type の意味
HYBRID – Runtime が顧客側 GKE/Anthos にデプロイされるモード。
CLOUD – 完全マネージド（Edge または X）で Google が Runtime を管理するモード。

作成後は gcloud apigee organizations describe my-company-org でステータスを確認できます。

詳細手順は「Apigee Hybrid 組織の作成 (CLI)」をご参照ください。

Hybrid 環境構築と Runtime デプロイ手順

このセクションでは、Hybrid の実体となる GKE クラスタ の要件から、Helm チャートを用いた Apigee Runtime のインストールまでのフローを段階的に示します。各ステップで必要な IAM 権限や推奨設定も併せて解説するので、手順通りに進めるだけで本番レベルの環境が構築できます。

GKE クラスタ要件と作成例

Hybrid の Runtime は Kubernetes 上で動作します。最低でも以下を満たすクラスタを用意してください。

要件	推奨設定
ノードプール	3 ノード以上、`n1-standard-4`（CPU 4、メモリ 15 GB）
ネットワーク	VPC ネイティブ (IP Alias) 、Pod CIDR と Service CIDR が衝突しないこと
IAM 権限	`roles/container.admin` と `roles/iam.serviceAccountUser` を持つサービスアカウント

GKE クラスタ作成コマンド例

gcloud container clusters create apigee-hybrid \
  --project=my-gcp-project \
  --region=us-central1 \
  --num-nodes=3 \
  --machine-type=n1-standard-4 \
  --enable-ip-alias \
  --release-channel=regular

gcloud container clusters create apigee-hybrid \

--project=my-gcp-project \

--region=us-central1 \

--num-nodes=3 \

--machine-type=n1-standard-4 \

--enable-ip-alias \

--release-channel=regular

作成完了後は kubectl get nodes で Ready 状態を必ず確認してください。

GKE の詳細設定は「Hybrid 用 GKE クラスタの構築」に記載されています。

Apigee Runtime の Helm インストール手順

1. Helm リポジトリ追加と認証情報のシークレット化

helm repo add apigee https://apigee.github.io/helm-charts
helm repo update

# Service Account キー（JSON）を Kubernetes Secret に格納
kubectl create secret generic apigee-sa-key \
  --from-file=key.json=/path/to/apigee-service-account.json

helm repo add apigee https://apigee.github.io/helm-charts

helm repo update

# Service Account キー（JSON）を Kubernetes Secret に格納

kubectl create secret generic apigee-sa-key \

--from-file=key.json=/path/to/apigee-service-account.json

2. `values.yaml` の主要パラメータ

以下は最小構成の例です。環境ごとに Environment Group を作成し、Ingress 用ホスト名を指定します。

apigee:
  organization: my-company-org
  runtime:
    envGroups:
      - name: dev
        environments: [dev]
      - name: prod
        environments: [prod]
  security:
    serviceAccountKeySecret: apigee-sa-key
  ingress:
    enabled: true
    hostname: api.mycompany.com   # 外部公開用 DNS 名

apigee:

organization: my-company-org

runtime:

envGroups:

- name: dev

environments: [dev]

- name: prod

environments: [prod]

security:

serviceAccountKeySecret: apigee-sa-key

ingress:

enabled: true

hostname: api.mycompany.com # 外部公開用 DNS 名

3. Helm によるデプロイ

helm install apigee-runtime apigee/apigee \
  -f values.yaml \
  --namespace apigee-system \
  --create-namespace

helm install apigee-runtime apigee/apigee \

-f values.yaml \

--namespace apigee-system \

--create-namespace

インストール後は kubectl get pods -n apigee-system で全ポッドが Running になることを確認し、Ingress の DNS が正しく解決できるかテストしてください。

完全手順は「Hybrid Runtime の Helm デプロイ」をご参照ください。

API プロキシ作成・環境設計と自動化ベストプラクティス

この章では、Apigee UI の Proxy Wizard を使った基本的なプロキシ作成手順から、Environment / Environment Group の設計方針、そして Terraform や curl を用いた Management API 自動化までを網羅します。CI/CD に組み込める形で示すので、開発フローへの即時適用が可能です。

Proxy Wizard とテンプレート活用

Proxy Wizard は UI から数クリックでプロキシ雛形を生成できます。以下は作業の流れです。

Develop → API Proxies に移動し「Create New Proxy」を選択。
プロキシ名とベースパス（例：/v1/orders）を入力し、バックエンド URL（例：https://orders-backend.internal）を設定。
テンプレート一覧から OAuth 2.0、Quota、SpikeArrest など必要なポリシーを選択し、画面上で簡単にパラメータ調整できる。

UI 操作の詳細は「Apigee Proxy Wizard の使い方」に掲載されています。

Environment / Environment Group 設計指針

コンポーネント	推奨構成
Environment	`dev`、`test`、`prod` を個別作成し、各環境で独立したプロキシリビジョンを保持
Environment Group	3 環境を `my-company-eg` にまとめ、共通の Virtual Host（例：`api.mycompany.com`）で外部公開
トラフィック分離	Cloud Armor ポリシーや IAM 条件で `dev` は内部ネットワーク限定、`prod` は全世界に公開

ポイント
- 環境ごとに Quota と RateLimit を個別設定すると、本番障害時にテスト環境が影響を受けません。

詳細設計例は「Apigee Environment のベストプラクティス」をご確認ください。

Management API を用いた自動化例

1. Terraform Provider for Apigee

provider &quot;apigee&quot; {
  org   = &quot;my-company-org&quot;
  token = var.apigee_token   # Cloud IAM のアクセストークンまたは OAuth トークン
}

resource &quot;apigee_proxy&quot; &quot;order_api&quot; {
  name        = &quot;order-api&quot;
  base_path   = &quot;/v1/orders&quot;
  target_url  = &quot;https://orders-backend.internal&quot;
  environments = [&quot;dev&quot;, &quot;test&quot;, &quot;prod&quot;]
}

provider "apigee" {

org = "my-company-org"

token = var.apigee_token # Cloud IAM のアクセストークンまたは OAuth トークン

}

resource "apigee_proxy" "order_api" {

name = "order-api"

base_path = "/v1/orders"

target_url = "https://orders-backend.internal"

environments = ["dev", "test", "prod"]

}

terraform init && terraform apply だけでプロキシの作成・デプロイが完了します。

2. curl + Management API でポリシー追加

TOKEN=$(gcloud auth print-access-token)

curl -X POST &quot;https://apigee.googleapis.com/v1/organizations/my-company-org/apis/order-api/revisions/1/policies&quot; \
  -H &quot;Authorization: Bearer $TOKEN&quot; \
  -H &quot;Content-Type: application/json&quot; \
  -d '{
        &quot;name&quot;: &quot;OAuthV2&quot;,
        &quot;type&quot;: &quot;OAuthV2&quot;,
        &quot;attributes&quot;: {
          &quot;accessTokenDuration&quot;: &quot;3600&quot;
        }
      }'

TOKEN=$(gcloud auth print-access-token)

curl -X POST "https://apigee.googleapis.com/v1/organizations/my-company-org/apis/order-api/revisions/1/policies" \

-H "Authorization: Bearer $TOKEN" \

-H "Content-Type: application/json" \

-d '{

"name": "OAuthV2",

"type": "OAuthV2",

"attributes": {

"accessTokenDuration": "3600"

}

ベストプラクティス
- CI/CD（Cloud Build、GitHub Actions）に組み込み、プルリクエストごとに terraform plan を実行してレビューを必須化。
- API キーや Service Account のシークレットは Secret Manager に保存し、デプロイ時に自動ローテーションする仕組みを構築。

公式の Management API リファレンスは「Apigee Management API v1」です。外部サイトへの引用はブランドガイドラインに従い、必要があれば削除または置換してください。

運用・トラブルシューティング、モニタリングと継続的改善

本章では、Hybrid 環境で運用を開始した後に頻出する障害例とその診断手順、さらに Cloud Monitoring／Logging を活用した可視化・アラート設定方法を紹介します。定期的なレビューと自動テストの導入で、安定稼働と迅速な改善サイクルを実現できます。

バックエンド変更時のバージョニングとポリシー例

API パスにバージョンを組み込む（例：/v2/orders）し、旧バージョンは revision 1 のまま残す。
新バックエンド向けに Revision 2 を作成し、ステージング環境でテスト後に prod にプッシュ。
推奨ポリシー例 – ResponseCache と SpikeArrest の併用で、バックエンド障害時のキャッシュヒット率を向上させる。

&lt;Cache name=&quot;ResponseCache&quot;&gt;
  &lt;DisplayName&gt;Response Cache&lt;/DisplayName&gt;
  &lt;ExpirySettings&gt;&lt;TimeInSeconds&gt;300&lt;/TimeInSeconds&gt;&lt;/ExpirySettings&gt;
&lt;/Cache&gt;

&lt;SpikeArrest name=&quot;SA-Prod&quot;&gt;
  &lt;Rate&gt;500ps&lt;/Rate&gt;
&lt;/SpikeArrest&gt;

<DisplayName>Response Cache</DisplayName>

</Cache>

</SpikeArrest>

代表的な障害と対処フロー

障害	主な原因	診断手順	推奨対策
認証エラー（401/403）	Service Account キー失効、IAM ロール不足	Cloud Logging で `authorization` エラーメッセージ検索 → IAM ポリシー確認	キーを再生成し、`Apigee Runtime Agent` に最新キーを配置
クオータ超過	同時リクエストが設定 Quota 超過	Monitoring の `apigee.googleapis.com/quota/used` を確認	SpikeArrest でレート制限、またはサポートへ Quota 増加申請
ログ取得失敗	Logging sink 権限不足	`gcloud logging sinks list` → 対象 sink の IAM 確認	`roles/logging.logWriter` を対象サービスアカウントに付与

障害診断の詳細は「Apigee Hybrid トラブルシューティングガイド」をご参照ください。

ログ取得・分析、Cloud Monitoring の活用

ログエクスポート
Cloud Logging の「シンク」を作成し、BigQuery または Pub/Sub へ転送。
ダッシュボード例（Monitoring）
apigee.googleapis.com/proxy/request_count → プロキシ別リクエスト数
apigee.googleapis.com/runtime/latency → 平均レイテンシと 95 パーセンタイル
アラート設定
エラー率 (apigee.googleapis.com/proxy/error_count) が 5 % 超過したら Slack に通知。
レイテンシが SLA（例：200 ms）を超えた場合に自動スケールアウト（GKE の HorizontalPodAutoscaler と連携）。

詳細は「Apigee Hybrid のモニタリングとロギング」で確認できます。

継続的改善ポイント

項目	推奨アクション
定期レビュー	月次で API 利用レポートを分析し、Quota・RateLimit を最適化
セキュリティ強化	新しい OAuth スコープや mTLS の段階的導入でバックエンド通信を暗号化
自動テスト	Postman/Newman でプロキシ単位の回帰テストを CI に組み込み、デプロイ前に破壊的変更を検出

まとめ

本ガイドは Apigee Hybrid の導入から運用まで を網羅した実践手順です。

前提条件と最小権限の IAM 設定で安全な基盤を構築
デプロイモデル比較で組織に最適な選択肢を判断
GKE と Helm による Runtime デプロイをコード化し再現性確保
Proxy Wizard・Environment 設計と Terraform/Curl で API 管理を自動化
Cloud Logging／Monitoring を活用した障害検知と継続的改善

公式ドキュメントの該当ページにリンクを貼っているので、手順実行中に不明点が出たら随時参照してください。これらのベストプラクティスを取り入れることで、高可用性・低コスト・セキュア な API 管理基盤を迅速に立ち上げることができます。

スポンサードリンク

もっとスキルを活かしたいエンジニアへ

スポンサードリンク

働き方から選べる

無料で使えて良質な案件の情報収集ができるサービス

フルリモート・週3日・高単価、どんな条件も妥協したくないなら

フリーランスボードに無料会員登録する

利用者10万人以上。業界最大規模45万件の案件。AIマッチ機能や無料の相場情報が人気。

年収800万円以上のキャリアアップ・ハイクラス正社員を視野に入れているなら

Beyond Careerに無料相談する

内定獲得率90%以上。紹介先企業とは役員クラスのコネクションがある安心と信頼できるエージェント。

-Apigee

comment コメントをキャンセル

: Apigee

Apigee MCPと生成AIの連携による業務効率化ガイド

Apigee MCPは2026年の最新機能で、既存APIと生成AIモデルの連携をスムーズにし、自動化ワークフロー構築やセキュリティ強化を実現。チャットボットや要約ツールなど業務改善事例も紹介。

: Apigee

Apigee Edgeの料金比較と導入コスト分析｜API管理ツール選定ガイド

Apigee Edgeの3つの料金オプションと、Apigee XやAmazon API Gatewayとの比較情報を整理。初期費用・運用コストのバランスを考慮した導入判断に役立つ内容です。

: Apigee

2026 Apigee料金プラン変更とMCP導入の影響

2026年のApigee料金プランはMCP導入により従量課金モデルへ変更。評価・従量課金制・サブスクリプションの3プラン比較とコスト管理方法を解説。

: Apigee

Apigee の主要セキュリティポリシーと自動デプロイ方法

Apigee のセキュリティポリシー全体像と主要種類を整理し、UI・Management APIによる作成方法やCI/CDでの自動デプロイ手順、トラブルシューティングまで網羅的に紹介します。

: Apigee

Apigee APIプロキシ設定と導入ガイド

本記事では、ApigeeでのAPIプロキシ設定に関する基礎から実務導入までを解説。UI/APIによる構築手順やトラブルシューティング方法も紹介します。

2026 Okta SSO導入最新手順ガイド

Datadog AIアラート導入ガイドと最適設定方法

Apigee ハイブリッド導入ガイド：IAM設定・組織作成・Runtime デプロイ手順

導入前提条件と IAM ロール設定

前提条件の概要

推奨 IAM ロールと最小権限

Apigee のデプロイモデル比較と組織作成

デプロイモデルの比較表

組織作成 – コンソール編

組織作成 – gcloud CLI 編

Hybrid 環境構築と Runtime デプロイ手順

GKE クラスタ要件と作成例

GKE クラスタ作成コマンド例

Apigee Runtime の Helm インストール手順

1. Helm リポジトリ追加と認証情報のシークレット化

2. values.yaml の主要パラメータ

3. Helm によるデプロイ

API プロキシ作成・環境設計と自動化ベストプラクティス

Proxy Wizard とテンプレート活用

Environment / Environment Group 設計指針

Management API を用いた自動化例

1. Terraform Provider for Apigee

2. curl + Management API でポリシー追加

運用・トラブルシューティング、モニタリングと継続的改善

バックエンド変更時のバージョニングとポリシー例

代表的な障害と対処フロー

ログ取得・分析、Cloud Monitoring の活用

継続的改善ポイント

まとめ

2. `values.yaml` の主要パラメータ