Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

VPC Service Controls を使用してエージェントと Agent Gateway をデプロイする

1. はじめに

この Codelab では、VPC Service Controls の境界を使用してエージェントと Agent Gateway を設定するように Google Cloud 環境を構成する手順について説明します。VPC Service Controls の境界を確立し、ネットワーキングと DNS を構成し、Identity-Aware Proxy（IAP）リクエスト承認を使用して Agent Gateway をデプロイし、エージェントを安全にテストします。

作成するアプリの概要

この Codelab では、次の処理を行う Gemini Enterprise Agent Platform と Agent Gateway の安全な Google Cloud アーキテクチャを構築します。

VPC Service Controls を使用して、不正なデータ引き出しからプロジェクトリソースを保護します。
プライベート API ルーティング用に、限定公開の Google アクセス、Private Service Connect（PSC）、Cloud DNS プライベートゾーンを構成します。
一元化されたトラフィックプロキシ、下り（外向き）ルール、プロトコル構成を使用して Agent Gateway をプロビジョニングします。
Identity-Aware Proxy（IAP）リクエスト承認ポリシーを適用します。
プライベート接続を介して Agent Engine エージェントをデプロイし、安全にテストします。

学習内容

Agent Platform とセキュリティに必要な Google Cloud APIs を有効にする方法。
VPC Service Controls の境界と上り（内向き）アクセスルールを構成する方法。
プライベートネットワーク接続とプライベート DNS レコードを設定する方法。
Agent Gateway とエージェント接続テンプレートを作成する方法。
IAP リクエストの認証拡張機能とポリシーを構成する方法。
Agent Engine エージェントを安全にデプロイしてテストする方法。

必要なもの

Google Cloud CLI がインストールされ、最新バージョンに更新されている。
ワークステーションに Python 3 がインストールされている。
ワークステーションに Git がインストールされていること。
有効な Google Cloud 組織と請求先アカウントの権限。

2. 前提条件

このセクションでは、セットアップスクリプトを実行する前に必要な基本的なコマンドラインツールの要件と環境構成について説明します。

Google Cloud CLI がインストールされ、最新バージョンに更新されていることを確認してから、Google アカウントで認証します。Google Cloud CLI コンポーネントを更新して、Network Services と VPC Service Controls の最新の機能がサポートされていることを確認します。

gcloud components update
gcloud auth login
gcloud config set account USER_EMAIL

カスタムエージェントフレームワークを構成してデプロイするために、Python 3 がインストールされていることを確認します。手順については、Python モジュールのインストールをご覧ください。

python3 --version

セットアップコードと構成テンプレートを含むサンプルリポジトリのクローンを作成するために、Git がインストールされていることを確認します。手順については、Git のインストールをご覧ください。

3. Google Cloud プロジェクトを構成する

組織内に分離されたプロジェクトを作成すると、この Codelab で使用されるすべてのリソース、ネットワーク、権限がカプセル化され、管理可能になります。詳しくは、プロジェクトの作成と管理をご覧ください。

この設定のリソースをホストするために、組織の下に新しい Google Cloud プロジェクトを初期化します。独自のプロジェクトを使用することもできます。

export PROJ_ID="YOUR_PROJECT_ID"
gcloud projects create ${PROJ_ID} --organization=YOUR_ORG_ID

gcloud config set project $PROJ_ID

gcloud auth application-default set-quota-project $PROJ_ID

ログインしてアプリケーションのデフォルト認証情報を取得します。

gcloud auth application-default login

構成を確認します

gcloud config list

課金を有効にする

有効な請求先アカウントを新しく作成したプロジェクトにリンクして、サービスの使用を有効にします。

課金を有効にすることは、API 割り当てを使用し、エージェントゲートウェイ、Virtual Private Cloud、コンピューティングノードなどの Google Cloud インフラストラクチャをプロビジョニングするための前提条件です。課金構成の詳細については、Google Cloud Billing のドキュメントをご覧ください。

gcloud billing accounts list
# Copy the billing account to assign to your GCP project
gcloud billing projects link $PROJ_ID --billing-account=BILLING_ACCOUNT_ID

4. サービスを有効にする

エージェント、Agent Gateway、ネットワーキング、セキュリティ、オブザーバビリティ機能に必要なすべての Google Cloud API を有効にします。

API を有効にすると、安全なエージェント接続に必要なリソース管理、オブザーバビリティ、ネットワーキング機能のバックエンドクラウドサービスが公開されます。詳細については、Service Usage API のドキュメントをご覧ください。

gcloud services enable \
  agentregistry.googleapis.com \
  aiplatform.googleapis.com \
  apphub.googleapis.com \
  apptopology.googleapis.com \
  cloudapiregistry.googleapis.com \
  cloudtrace.googleapis.com \
  compute.googleapis.com \
  dataform.googleapis.com \
  iam.googleapis.com \
  iap.googleapis.com \
  logging.googleapis.com \
  modelarmor.googleapis.com \
  monitoring.googleapis.com \
  networksecurity.googleapis.com \
  networkservices.googleapis.com \
  notebooks.googleapis.com \
  observability.googleapis.com \
  securitycenter.googleapis.com

gcloud services enable \
  saasservicemgmt.googleapis.com \
  storage.googleapis.com \
  telemetry.googleapis.com \
  texttospeech.googleapis.com \
  run.googleapis.com \
  artifactregistry.googleapis.com \
  cloudbuild.googleapis.com \
  dns.googleapis.com \
  accesscontextmanager.googleapis.com \
  discoveryengine.googleapis.com \
  agentidentity.googleapis.com \
  agentidentitycredentials.googleapis.com

5. 環境変数をエクスポートする

リージョン、プロジェクト ID、プロジェクト番号、組織 ID、ユーザー ID の再利用可能な環境変数を定義します。シェル変数を設定すると、ステップ間でリソース構成コマンドが標準化され、スクリプト実行中の手動置換エラーが最小限に抑えられます。

export REGION="us-central1"
export PROJ_ID=$(gcloud config list --format="value(core.project)")
export PROJ_NO=$(gcloud projects describe ${PROJ_ID} --format="value(projectNumber)")
export ORG_ID=$(gcloud projects get-ancestors ${PROJ_ID} --format="value(id)" | tail -n 1)
export USER_IDENTITY=$(gcloud config get-value account)

6. VPC Service Controls の境界を作成する

VPC Service Controls 境界を作成して、プロジェクトリソースを分離し、データ漏洩を防ぎます。詳細については、VPC Service Controls の概要をご覧ください。

アクセスポリシーを取得する

組織に関連付けられている Access Context Manager ポリシー ID を取得します。Access Context Manager ポリシーは、VPC Service Controls の境界が接続され、適用される組織境界を定義します。

gcloud access-context-manager policies list --organization=$ORG_ID

アクセスポリシーをエクスポートする

gcloud CLI 構成でアクセスポリシーを設定し、サポートされている制限付きサービスのリストを収集します。サポートされているすべてのサービスを収集すると、Google Cloud API エンドポイント全体で不正アクセスを防止する制限付き境界ルールセットを構築できます。

export ACCESS_POLICY=ACCESS_POLICY_ID

gcloud config set access_context_manager/policy $ACCESS_POLICY
SUPPORTED_SERVICES=$(gcloud access-context-manager supported-services list --format="value(name)" | paste -sd, -)

境界を作成する

サービス境界名を定義し、プロジェクト内のサポートされている Google Cloud サービス全体に制限を適用します。境界はプロジェクトリソースを囲む境界として機能し、上り（内向き）ルールと下り（外向き）ルールで明示的に許可されていない限り、直接の送受信トラフィックを制限します。

export PERIMETER_NAME="perimeter_${PROJ_NO}"

gcloud access-context-manager perimeters create accessPolicies/${ACCESS_POLICY}/servicePerimeters/${PERIMETER_NAME} \
--title="${PERIMETER_NAME}" \
--perimeter-type=regular \
--resources=projects/${PROJ_NO} \
--restricted-services=${SUPPORTED_SERVICES}

上り（内向き）ポリシーを作成する

上り（内向き）ポリシーは、境界外から発信され、境界内の制限付きリソースに到達できるトラフィックの明示的な条件（特定のユーザー ID やアクセスレベルなど）を定義します。

すべてのサービスでユーザー ID の明示的なアクセスを許可する YAML ファイルを作成します。

cat > ingress-policy.yaml << EOF
- ingressFrom:
    identities:
      - user:${USER_IDENTITY}
    sources:
      - accessLevel: '*'
  ingressTo:
    operations:
      - serviceName: '*'
    resources:
      - '*'
EOF

gcloud access-context-manager perimeters update $PERIMETER_NAME --set-ingress-policies="ingress-policy.yaml"

この Codelab では、デフォルトで VPC Service Controls のアクセス拒否を回避するように環境を構成します。ただし、テスト中のトラブルシューティングに役立つように、VPC Service Controls には詳細な拒否ログとポリシーインテリジェンスツールが用意されています。

VPC Service Controls の拒否のトラブルシューティング

テスト中は、以下のトラブルシューティングのヒントを参照してください。

違反ダッシュボードを有効にすると、環境内の最新の違反を追跡できます。
Cloud Audit Logs で VPC Service Controls のアクセス拒否（403）ログをモニタリングします。
違反分析ツールで、違反の一意の ID またはトークンを使用して違反を診断します。
詳細な手順については、VPC Service Controls のトラブルシューティングの動画をご覧ください。

7. ネットワークを設定する

Google API とサービスとのプライベート通信をサポートするように VPC ネットワーク設定を構成します。適切なネットワーク構成により、エージェント、ゲートウェイ、Google Cloud API 間のネットワークトラフィックがプライベート内部ネットワークに留まることが保証されます。ネットワーキングパターンの詳細については、Google Cloud VPC のドキュメントをご覧ください。

限定公開の Google アクセスの有効化

デフォルトサブネットでプライベート Google アクセスを有効にして、VM インスタンスと内部ワークロードがパブリック IP アドレスではなく内部 IP アドレスを使用して Google API にアクセスできるようにします。

export NETWORK_NAME="default"
export SUBNET_NAME="default"

gcloud compute networks subnets update $SUBNET_NAME --region=$REGION --enable-private-ip-google-access

PSC ネットワークアタッチメントを作成する

Agent Gateway 接続用に Private Service Connect（PSC）ネットワークアタッチメントを作成します。ネットワークアタッチメントは Private Service Connect（PSC）インターフェースを提供し、Agent Gateway サービスと内部サブネット間の安全なクロス VPC 通信を容易にします。

gcloud compute network-attachments create psc-agw-${REGION} \
  --region=${REGION} \
  --subnets=${SUBNET_NAME} \
  --connection-preference=ACCEPT_AUTOMATIC

確認

新しく作成したネットワークアタッチメントのセルフリンクリソース URI を取得して確認します。リソース URI を検証することで、ネットワークアタッチメントが正常にインスタンス化され、接続テンプレートで参照できることを確認します。

export PSC_NA_URI=$(gcloud compute network-attachments describe psc-agw-${REGION} \
  --region=${REGION} \
  --format="value(selfLink.scope(v1))")
echo ${PSC_NA_URI}

Cloud DNS プライベートゾーンを作成する

プライベート IP 範囲を介して googleapis.com トラフィックをルーティングするように Cloud DNS 限定公開ゾーンを構成します。限定公開 DNS ゾーンは、googleapis.com のパブリックドメインルックアップをオーバーライドし、すべての送信トラフィックを VPC ネットワーク内のプライベート内部仮想 IP（VIP）に転送します。詳細については、Cloud DNS 限定公開ゾーンをご覧ください。

export ZONE_NAME="gapis"

gcloud dns managed-zones create ${ZONE_NAME} \
--visibility=private \
--networks=https://www.googleapis.com/compute/v1/projects/${PROJ_ID}/global/networks/${NETWORK_NAME} \
  --description="Privately reach Google APIs" \
  --dns-name=googleapis.com

gcloud dns record-sets transaction start --zone=${ZONE_NAME}

プライベートルーティング用に次のドメインオプションのいずれかを選択します（トランザクションを実行する前に、オプション 1 またはオプション 2 のコマンドのみを実行します）。詳細については、限定公開の Google アクセスの構成オプションをご覧ください。

オプション 1: プライベート VIP [推奨]

gcloud dns record-sets transaction add --name="*.googleapis.com." \
    --type=CNAME private.googleapis.com. \
    --zone=${ZONE_NAME} \
    --ttl=300

gcloud dns record-sets transaction add --name=private.googleapis.com. \
    --type=A 199.36.153.8 199.36.153.9 199.36.153.10 199.36.153.11 \
    --zone=${ZONE_NAME} \
    --ttl=300

オプション 2: 制限付き VIP

gcloud dns record-sets transaction add --name="*.googleapis.com." \
    --type=CNAME restricted.googleapis.com. \
    --zone=${ZONE_NAME} \
    --ttl=300

gcloud dns record-sets transaction add --name=restricted.googleapis.com. \
    --type=A 199.36.153.4 199.36.153.5 199.36.153.6 199.36.153.7 \
    --zone=${ZONE_NAME} \
    --ttl=300

DNS トランザクションを commit します。

gcloud dns record-sets transaction execute --zone=${ZONE_NAME}

8. Agent Gateway を作成する

Agent Gateway をプロビジョニングし、接続テンプレートとルーティングルールを定義します。Agent Gateway は、エージェントトラフィック、下り（外向き）ポリシー、プロトコル処理、安全なサービスディスカバリを管理するための一元化されたプロキシとして機能します。アーキテクチャの参照については、Agent Gateway の概要をご覧ください。

VPC Service Controls 境界内の Agent Gateway、IAP リクエスト認証、PSC ネットワークアタッチメントを介してリクエストをルーティングするエージェントを示すアーキテクチャ図。

export AGW_NAME="gateway-${USER_IDENTITY}"
export AGW_CONNECTIVITY_TEMPLATE="agw-connectivity-template-${USER_IDENTITY}"

エージェント接続テンプレートを作成する

接続テンプレートは、ゲートウェイが送信リクエストを処理するために必要なネットワーク構成、下り（外向き）ルーティングポリシー、DNS ピアリング設定、ネットワークアタッチメント URI を指定します。

cat > ${AGW_CONNECTIVITY_TEMPLATE}.yaml << EOF
name: projects/${PROJ_NO}/locations/${REGION}/agentConnectivityTemplates/${AGW_CONNECTIVITY_TEMPLATE}
accessPath: AGENT_TO_ANYWHERE
deploymentModel: CENTRALIZED
egressNetworkConfig:
  networkAttachment: ${PSC_NA_URI}
  dnsPeeringConfig:
    domain: googleapis.com.
    targetNetwork: projects/${PROJ_ID}/global/networks/${NETWORK_NAME}
  vpcEgress: ALL_TRAFFIC
EOF

gcloud network-services agent-connectivity-templates import ${AGW_CONNECTIVITY_TEMPLATE} \
    --source="${AGW_CONNECTIVITY_TEMPLATE}.yaml" \
    --location=${REGION}

Agent Gateway を作成する

cat > ${AGW_NAME}-config.yaml << EOF
name: ${AGW_NAME}
protocols:
  - MCP
googleManaged:
  governedAccessPath: AGENT_TO_ANYWHERE
agentConnectivityTemplate: projects/${PROJ_NO}/locations/${REGION}/agentConnectivityTemplates/${AGW_CONNECTIVITY_TEMPLATE}
registries:
  - //agentregistry.googleapis.com/projects/${PROJ_NO}/locations/global
EOF

gcloud network-services agent-gateways import ${AGW_NAME} \
    --source="${AGW_NAME}-config.yaml" \
    --location=${REGION}

作成を確認する

Agent Gateway リソースが正常にデプロイされ、構成されていることを確認します。デプロイされたエージェントゲートウェイを記述すると、その運用状態がアクティブであることが確認され、関連付けられた接続テンプレートとレジストリが正しくアタッチされていることが検証されます。

gcloud network-services agent-gateways describe ${AGW_NAME} \
  --location=${REGION}

9. IAP を介して承認を作成する

Identity-Aware Proxy（IAP）リクエスト承認ポリシーとサービス拡張機能を構成して、Agent Gateway へのアクセスを許可する前にリクエスト認証情報を検証します。詳細については、IAP のドキュメントをご覧ください。

Agent Gateway がネットワークセキュリティの Authz ポリシーと Authz サービス拡張機能を使用して、リクエストの認可を Identity-Aware Proxy（IAP）に委任するフロー図。

export AUTHZ_EXT="iap-authz-extension-${USER_IDENTITY}"
export AUTHZ_POLICY="iap-authz-policy-${USER_IDENTITY}"

AuthZ 拡張機能を作成する

cat > ${AUTHZ_EXT}.yaml << EOF
name: ${AUTHZ_EXT}
service: iap.googleapis.com
failOpen: false
timeout: 1s
metadata:
  iapPolicyVersion: "V2"
EOF

gcloud service-extensions authz-extensions import ${AUTHZ_EXT} \
    --source=${AUTHZ_EXT}.yaml \
    --location=${REGION}

AuthZ ポリシーを作成して Agent Gateway にバインドする

cat > ${AUTHZ_POLICY}.yaml << EOF
name: ${AUTHZ_POLICY}
target:
  resources:
    - "projects/${PROJ_ID}/locations/${REGION}/agentGateways/${AGW_NAME}"
policyProfile: REQUEST_AUTHZ
action: CUSTOM
customProvider:
  authzExtension:
    resources:
      - "projects/${PROJ_ID}/locations/${REGION}/authzExtensions/${AUTHZ_EXT}"
EOF

gcloud network-security authz-policies import ${AUTHZ_POLICY} \
    --source=${AUTHZ_POLICY}.yaml \
    --location=${REGION}

この Codelab では、デフォルトで IAP アクセスが拒否されないようにします。ただし、テストを支援するために、Agent Gateway はアクセス拒否の詳細なオブザーバビリティを提供します。

IAP 認可拒否のトラブルシューティングとモニタリング

_Default ロギングバケットでログ分析を有効にします。

gcloud logging buckets update _Default --location=global --enable-analytics --async

Agent Gateway のオブザーバビリティダッシュボードを開きます。
Google Cloud コンソールで、[Agent Gateway] ページに移動します。
ゲートウェイの名前（gateway-xyz など）をクリックします。
[オブザーバビリティ] タブをクリックします。
[Authorization Failure] ダッシュボードと [403 Denials] ダッシュボードを確認します。

10. Agent Engine エージェントを作成する

ステージングバケットを作成する

実行時の初期化中に一時的なステージングアーティファクト、依存関係、デプロイ構成を保存する Cloud Storage バケットをターゲットリージョンに作成します。

#Staging bucket name needs to be globally unique
export STAGING_BUCKET="agent-temp-bucket-${PROJ_NO}-${USER_IDENTITY}"
gcloud storage buckets create gs://${STAGING_BUCKET} --location=${REGION}

Python 仮想環境を有効にする

python3 -m venv .venv
source .venv/bin/activate

エージェントコードをダウンロードする

git clone https://github.com/gpratikab/gcp-vpcsc-agent.git
cd gcp-vpcsc-agent

依存関係のインストール

python3 -m pip install --upgrade -r requirements.txt

Agent Platform サービスエージェントに IAM ロールを付与する

gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="serviceAccount:service-${PROJ_NO}@gcp-sa-aiplatform.iam.gserviceaccount.com" \
  --role="roles/agentgateway.serviceAgent"
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="serviceAccount:service-${PROJ_NO}@gcp-sa-aiplatform.iam.gserviceaccount.com" \
  --role="roles/ml.serviceAgent"
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="serviceAccount:service-${PROJ_NO}@gcp-sa-aiplatform.iam.gserviceaccount.com" \
  --role="roles/networkservices.viewer"

エージェントをデプロイする

python3 deploy_gcp_agent.py create

前のコマンドの出力に表示されたエージェント ID を環境変数としてエクスポートします。

#Paste identity of your Agent, it will be printed as the output of the previous command
export AGENT_IDENTITY="principal://PRINCIPAL_ID"
echo $AGENT_IDENTITY

11. ゲートウェイ経由のエージェントの下り（外向き）を許可する

新しく作成されたエージェントが googleapis.com に下り（外向き）トラフィックを送信できるようにします。

注: エージェントゲートウェイのオブザーバビリティを使用して、エンドポイントを選択的に許可リストに登録できます。この Codelab では、わかりやすくするために、すべての API へのアクセスを許可しています。

明示的な IAM 下り（外向き）ポリシールールを構成すると、エージェントは Agent Gateway と IAP プロキシを介して API 呼び出しをルーティングし、外部の Google Cloud サービスにアクセスする権限が付与されます。

IAM ポリシーの作成

cat > agent-access-rules.json << EOF
{
  "conditions": {
    "iap.googleapis.com": {
      "description": "Allow access to agent",
      "expression": "(destination.agent_registry.location == 'global') || (destination.unregistered.host.endsWith('googleapis.com'))",
      "title": "agenttogapis"
    }
  },
  "description": "agenttogapis",
  "effect": "ALLOW",
  "excludedPrincipals": [],
  "operation": {
    "excludedPermissions": [],
    "permissions": [
      "iap.googleapis.com/resources.egressViaIAP"
    ]
  },
  "principals": [
    "${AGENT_IDENTITY}"
  ]
}
EOF

アクセスポリシーを更新する

既存のアクセスポリシーがあるかどうかを確認します。

gcloud iam access-policies list --project=${PROJ_ID} --location=global

アクセスポリシー名を設定します。

export IAM_ACCESS_POLICY="agent-access-policy"

新しいポリシーを作成する方法は次のとおりです:

gcloud iam access-policies create ${IAM_ACCESS_POLICY} \
  --details-rules=agent-access-rules.json \
  --project=${PROJ_ID} \
  --location=global

または、既存のポリシーを更新します。

gcloud iam access-policies update ${IAM_ACCESS_POLICY} \
  --add-details-rules=agent-access-rules.json \
  --project=${PROJ_ID} \
  --location=global

12. エージェントをテストする

Google Cloud コンソールでエージェントの動作を検証すると、エンドツーエンドの通信、IAM ポリシー、VPC Service Controls の境界が適切に機能していることを確認できます。これで、エージェントをテストする準備が整いました。

Google Cloud コンソールで、[エージェントのデプロイ] ページに移動します。
デプロイしたエージェント（gcp_agent_...）を選択します。
[プレイグラウンド] タブを開きます。
プロンプトフィールドに「List storage buckets in the current project.」と入力します。
エージェントがプライベート Agent Gateway を介してバケットのリストを正常に返すことを確認します。
アクセス拒否により、エージェントが別のプロジェクトからバケットを取得できないことを確認します。拒否は、Cloud Audit Logs または VPC Service Controls 違反ダッシュボードで確認できます。

13. クリーンアップ

この Codelab で使用したリソースに対して Google Cloud アカウントで課金されないようにするには、作成したプロジェクトを削除します。

gcloud projects delete ${PROJ_ID}

14. 完了

おめでとうございます！Google Cloud の安全な VPC Service Controls 境界内にエージェントと Agent Gateway を構成できました。

次のステップ

VPC Service Controls のきめ細かい上り（内向き）ルールと下り（外向き）ルールについて説明します。
Agent Gateway を使用してアクセスポリシーとセマンティックポリシーを構成します。
高度な安全性とセキュリティのフィルタリングのために Model Armor を統合する。