1. はじめに
このドキュメントでは、WIF を使用して AgentSpace にアクセスするようにカスタム ドメインを構成するためのリファレンス アーキテクチャについて説明します。Agentspace アプリの作成時に割り当てられた Google 管理の URL の代わりに、カスタム ドメインを使用できます。この Codelab では、nip.io ドメインを使用して Agentspace のカレンダー アプリケーションとドライブ アプリケーションにアクセスする方法を説明します。nip.io は、任意の IP アドレスにワイルドカード DNS を提供する無料のオープンソース サービスです。基本的には、独自の DNS サーバーを設定したり、/etc/hosts ファイルを変更したりすることなく、特定の IP アドレスに解決されるホスト名を作成できます。
独自のドメインを使用することをおすすめしますが、このチュートリアルではデモンストレーション用に nip.io を使用します。
下の図 1 に示すデプロイ シナリオでは、AgentSpace が、一般公開されている Google マネージド URL を介してアクセスされるカレンダー アプリケーションを含むデータストアを公開しています。
図 1
データストアと後続のアプリケーションの継続的な増加により、次のデプロイ シナリオ（図 2）に示すように、パブリック Google マネージド URL の管理がさらに行われ、Agentspace アプリケーションと URL の 1 対 1 のマッピングが行われます。
図 2.
カスタム ドメインを使用すると、さまざまな AgentSpace アプリケーションをユーザーが指定した単一の顧客ドメインにマッピングできます。この機能により、特定の URL パスを各 Agentspace アプリケーションに関連付けることができ、次のデプロイ シナリオ（図 3）に示すように、柔軟性が向上します。たとえば、お客様が管理するドメイン agentspace.cosmopup.com はパスルールに分割され、それぞれが特定の Agentspace アプリケーションにマッピングされます。例:
- agentspace.cosmopup.com/drive-app。Workspace ドライブの Agentspace アプリケーションにマッピングされます。
- agentspace.cosmopup.com/sharepoint-app（Sharepoint 用 Agentspace アプリケーションにマッピング）
URL マップで構成された外部アプリケーション ロードバランサの ホストルールとパルールは、カスタム ドメインを Google マネージド URL にマッピングするロジックを制御します。この関数は、例として agentpace.cosmopup.com/drive-app を使用して次の処理を行います。
- カスタム ドメインホスト パス agentspace.cosmopup.com/drive-app がロードバランサによって受信される
- URL マップが高度なホストとパスルールの照合用に構成されている
- ホスト agentspace.cosmopup.com はパスのマッチングとリダイレクトの対象です
- カスタム ドメインのホストパス agentspace.cosmopup.com/drive-app は UrlRedirect の対象です
- pathRedirect は Agentspace のパスです: /us/home/cid/5970a1b4-080a-4b44-8acd-fa89460cf0cd
- hostRedirect は Agentspace ホスト（vertexaisearch.cloud.google.com）です。
- カスタム ドメインのホストパス agentspace.cosmopup.com/sharepoint-app は UrlRedirect の対象です
- pathRedirect は Agentspace パスです。/signin/locations/global/workforcePools/your-pool-name/providers/your-provider-name?continueUrl=https://vertexaisearch.cloud.google/home/cid/f190000-0000-4d0a-0000-d08df6e3bef6
- hostRedirect は Agentspace ホスト（auth.cloud.google）です。
- バックエンド サービスへのルーティングの前にリダイレクト オペレーションが実行される
図 3
学習内容
- グローバル外部アプリケーション ロードバランサを作成する
- カスタム ドメインを Agentspace アプリケーションにリダイレクトするルーティングを作成する
- nip.io と Cloud DNS を統合してカスタム ドメインを作成する方法
- Agentspace カスタム ドメインへのアクセスを検証する方法
必要なもの
- オーナー権限を持つ Google Cloud プロジェクト
- 既存の Agentspace アプリケーションの URL
- 自己所有のカスタム ドメイン（省略可）
- 証明書 - 自己署名または Google マネージド
2. 作成するアプリの概要
高度なトラフィック管理機能を備えたグローバル外部アプリケーション ロードバランサを確立し、ホストとパスのリダイレクトを使用して Agentspace アプリケーションのカスタム ドメインパス一致を有効にします。デプロイが完了したら、次の操作を行って Agentspace アプリケーションへのアクセスを検証します。
- ウェブブラウザを開いてカスタム ドメインと指定されたパスに移動し、Agentspace アプリケーションにアクセスします。
3. ネットワークの要件
ネットワーク要件の内訳は次のとおりです。
コンポーネント | 説明 |
VPC（agentspace-vpc） | カスタムモード VPC |
インターネット NEG | エージェントスペースの Google マネージド FQDN（vertexaisearch.cloud.google.com）を示す FQDN として構成された、ロードバランサの外部バックエンドを定義するために使用されるリソース。インターネット FQDN は、解決のために VPC 内で DNS ルックアップを実行します。 |
バックエンド サービス | バックエンド サービスは、ロードバランサとバックエンド リソース間のブリッジとして機能します。このチュートリアルでは、バックエンド サービスがインターネット NEG に関連付けられています。 |
証明書 | Google Cloud でアプリケーション ロードバランサの証明書を構成するには、Certificate Manager サービスと、Google マネージド またはセルフマネージド SSL 証明書を使用します。 |
Cloud DNS | Cloud DNS パブリック ゾーンは、外部アプリケーション ロードバランサの外部 IP を nip.io（agentspace.externalip.nip.io）に解決するために使用されます。または、カスタム ドメインとロードバランサの IP アドレスで構成される A レコードを使用します。 |
4. Codelab のトポロジ
5. 設定と要件
セルフペース型の環境設定
- Google Cloud Console にログインして、プロジェクトを新規作成するか、既存のプロジェクトを再利用します。Gmail アカウントも Google Workspace アカウントもまだお持ちでない場合は、アカウントを作成してください。
- プロジェクト名は、このプロジェクトの参加者に表示される名称です。Google API では使用されない文字列です。いつでも更新できます。
- プロジェクト ID は、すべての Google Cloud プロジェクトにおいて一意でなければならず、不変です（設定後は変更できません）。Cloud コンソールでは一意の文字列が自動生成されます。通常は、この内容を意識する必要はありません。ほとんどの Codelab では、プロジェクト ID（通常は
PROJECT_IDと識別されます）を参照する必要があります。生成された ID が好みではない場合は、ランダムに別の ID を生成できます。または、ご自身で試して、利用可能かどうかを確認することもできます。このステップ以降は変更できず、プロジェクトを通して同じ ID になります。 - なお、3 つ目の値として、一部の API が使用するプロジェクト番号があります。これら 3 つの値について詳しくは、こちらのドキュメントをご覧ください。
- 次に、Cloud のリソースや API を使用するために、Cloud コンソールで課金を有効にする必要があります。この Codelab の操作をすべて行って、費用が生じたとしても、少額です。このチュートリアルの終了後に請求が発生しないようにリソースをシャットダウンするには、作成したリソースを削除するか、プロジェクトを削除します。Google Cloud の新規ユーザーは、300 米ドル分の無料トライアル プログラムをご利用いただけます。
Cloud Shell を起動する
Google Cloud はノートパソコンからリモートで操作できますが、この Codelab では、Google Cloud Shell（Cloud 上で動作するコマンドライン環境）を使用します。
Google Cloud Console で、右上のツールバーにある Cloud Shell アイコンをクリックします。
プロビジョニングと環境への接続にはそれほど時間はかかりません。完了すると、次のように表示されます。
この仮想マシンには、必要な開発ツールがすべて用意されています。永続的なホーム ディレクトリが 5 GB 用意されており、Google Cloud で稼働します。そのため、ネットワークのパフォーマンスと認証機能が大幅に向上しています。この Codelab での作業はすべて、ブラウザ内から実行できます。インストールは不要です。
6. 始める前に
API を有効にする
Cloud Shell で、プロジェクト ID が設定されていることを確認します。
gcloud config list project
gcloud config set project [YOUR-PROJECT-ID]
project=[YOUR-PROJECT-ID]
region=[YOUR-REGION]
echo $project
echo $region
必要なサービスをすべて有効にします。
gcloud services enable compute.googleapis.com
gcloud services enable dns.googleapis.com
7. ロードバランサ コンポーネントを設定する
ロードバランサの外部 IP アドレスを予約する
Cloud Shell 内で、ロードバランサに外部 IP アドレスを予約します。
gcloud compute addresses create external-ip \
--network-tier=PREMIUM \
--ip-version=IPV4 \
--global
Cloud Shell で、予約済みの IP アドレスを表示します。
gcloud compute addresses describe external-ip \
--global | grep -i address:
出力例:
user@cloudshell$ gcloud compute addresses describe external-ip \
--global | grep -i address:
address: 34.54.158.206
インターネット NEG を設定する
インターネット NEG を作成し、–network-endpoint-type を internet-fqdn-port（外部バックエンドに到達可能なホスト名とポート）に設定します。Agentspace を解決するために、FQDN vertexaisearch.cloud.google.com とポート 443 が使用されます。
gcloud compute network-endpoint-groups create agentspace-ineg \
--network-endpoint-type="internet-fqdn-port" \
--global
gcloud compute network-endpoint-groups update agentspace-ineg \
--add-endpoint="fqdn=vertexaisearch.cloud.google.com,port=443" \
--global
ロードバランサを作成する
Cloud Shell で、次の操作を行います。
gcloud compute backend-services create agentspace-ineg-bes \
--load-balancing-scheme=EXTERNAL_MANAGED \
--protocol=HTTPS \
--global
gcloud compute backend-services add-backend agentspace-ineg-bes \
--network-endpoint-group=agentspace-ineg \
--global-network-endpoint-group \
--global
証明書を作成する
この時点で、インターネット NEG とバックエンド サービスが作成されています。次のセクションでは、HTTPS ターゲット プロキシで使用する証明書リソースを作成する必要があります。SSL 証明書リソースは、Google マネージド SSL 証明書またはセルフマネージド SSL 証明書を使用して作成できます。Google Cloud が自動的に取得、管理、更新するため、Google マネージド証明書の使用をおすすめします。
このチュートリアルで使用されているグローバル外部アプリケーション ロードバランサでサポートされている証明書の詳細については、以下をご覧ください。
SSL 証明書の概要 | ロード バランシング | Google Cloud
次のセクションでは、自己署名証明書を作成します（代わりに Google マネージド証明書を使用することもできます）。これには、共通名と完全修飾ドメイン名（agentspace.YOUR-EXTERNAL-IP.nip.io）のマッピングが必要です。これは、前に生成されたロードバランサの外部 IP アドレスに対応します。例を次に示します。
共通名: agentspace.34.54.158.206.nip.io
Cloud Shell 内で秘密鍵を作成する
openssl genrsa -out private-key-file.pem 2048
Cloud Shell 内で、pem ファイルの生成に使用する config.txt ファイルを作成します。次の構成の DNS 1 エントリ agentspace.YOUR-EXTERNAL-IP.nip.io（例: agentspace.34.54.158.206.nip.io）に完全修飾ドメイン名を指定します。
cat <<'EOF' >config.txt
[req]
default_bits = 2048
req_extensions = extension_requirements
distinguished_name = dn_requirements
[extension_requirements]
basicConstraints = CA:FALSE
keyUsage = nonRepudiation, digitalSignature, keyEncipherment
subjectAltName = @sans_list
[dn_requirements]
countryName = Country Name (2 letter code)
stateOrProvinceName = State or Province Name (full name)
localityName = Locality Name (eg, city)
organizationName = Organization Name (eg, company)
organizationalUnitName = Organizational Unit Name (eg, section)
commonName = Common Name (e.g. server FQDN or YOUR name)
emailAddress = Email Address
[sans_list]
DNS.1 = agentspace.YOUR-EXTERNAL-IP.nip.io
EOF
Cloud Shell で、config.txt と private-key-file.pem が生成されていることを確認します。
user@cloudshell:$ ls
config.txt private-key-file.pem
Cloud Shell で次の操作を行います。
sudo openssl req -new -key private-key-file.pem \
-out csr.pem \
-config config.txt
例:
user@cloudshell:$ sudo openssl req -new -key private-key-file.pem \
-out csr.pem \
-config config.txt
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) []:
State or Province Name (full name) []:
Locality Name (eg, city) []:
Organization Name (eg, company) []:
Organizational Unit Name (eg, section) []:
Common Name (e.g. server FQDN or YOUR name)[]:agentspace.34.54.158.206.nip.io
Email Address []:
Cloud Shell で、必要な証明書署名 pem の作成を検証します。
user@cloudshell:$ ls
config.txt csr.pem private-key-file.pem
Cloud Shell 内で証明書を生成します。
sudo openssl x509 -req \
-signkey private-key-file.pem \
-in csr.pem \
-out cert.cert \
-extfile config.txt \
-extensions extension_requirements \
-days 365
出力例:
user@cloudshell:$ sudo openssl x509 -req \
-signkey private-key-file.pem \
-in csr.pem \
-out cert.cert \
-extfile config.txt \
-extensions extension_requirements \
-days 365
Certificate request self-signature ok
subject=CN = agentspace.34.54.158.206.nip.io
Cloud Shell で、ファイル cert.cert の作成を検証します。
user@cloudshell:$ ls
cert.cert config.txt csr.pem private-key-file.pem
外部ロードバランサに関連付ける証明書リソースを作成します。証明書と秘密鍵のパラメータは、実際のファイル名に置き換えてください。
Cloud Shell で、次の操作を行います。
gcloud compute ssl-certificates create agentspace-self-signed-cert \
--certificate=cert.cert \
--private-key=private-key-file.pem \
--global
Cloud Shell で、次の操作を行います。
gcloud compute url-maps create agentspace-lb \
--default-service=agentspace-ineg-bes \
--global
Cloud Shell で、次の操作を行います。
gcloud compute target-https-proxies create https-proxy \
--ssl-certificates=agentspace-self-signed-cert \
--url-map=agentspace-lb \
--global
Cloud Shell で、次の操作を行います。
gcloud compute forwarding-rules create agentspace-fr \
--load-balancing-scheme=EXTERNAL_MANAGED \
--network-tier=PREMIUM \
--address=external-ip \
--target-https-proxy=https-proxy \
--global \
--ports=443
8. 一般公開 DNS ゾーンを作成する
次のセクションでは、nip.io が外部ロードバランサの IP アドレスに対して解決するために使用するパブリック DNS ゾーンを作成します。
Cloud Shell で、次の操作を行って外部ロードバランサの IP アドレスの変数を作成します。
externalip=<YOUR-EXTERNAL-IP>
echo $externalip
Cloud Shell で、次の操作を行います。
gcloud dns --project=$project managed-zones create agentspace-dns --description="Agentspace public dns" --dns-name="$externalip.nip.io." --visibility="public"
Cloud Shell で、次の操作を行います。
gcloud dns --project=$project record-sets create agentspace.$externalip.nip.io. --zone="agentspace-dns" --type="A" --ttl="300" --rrdatas="$externalip"
9. Agentspace アプリケーションの URL を特定する
次の手順では、Google が生成し、各アプリケーションの Agentspace にマッピングされた Google マネージド Agentspace の公開 URL を特定します。URL の出力はリファレンス アーキテクチャに基づく例であるため、URL が正確であることを確認する必要があります。
ウェブアプリへのリンクは、アプリケーションごとに保存してください。
ドライブ アプリケーション
Agentspace のウェブ URL:
https://vertexaisearch.cloud.google.com/us/home/cid/5970a1b4-080a-4b44-8acd-fa89460cf0cd
SharePoint アプリケーション
Agentspace ウェブ URL: https://auth.cloud.google/signin/locations/global/workforcePools/your-pool-name/providers/your-provider-name?continueUrl=https://vertexaisearch.cloud.google/home/cid/f190000-0000-4d0a-0000-d08df6e3bef6
10. 詳細なホストとパスのルールを作成する
次のセクションでは、ロードバランサのルーティング ルールを更新して、Cloud コンソールを使用してホストルールとパスルールを定義するオプションを有効にします。次の表に、カスタム値（上から順）の概要を示します。環境に合わせて更新してください。
カスタム値 | チュートリアルに基づく例 | |
ホスト | agentspace.YOUR-EXTERNAL-IP.nip.io | agentspace.34.54.158.206.nip.io |
defaultService | projects/<projectid>/global/backendServices/agentspace-ineg-bes | projects/your-project-id/global/backendServices/agentspace-ineg-bes |
prefixMatch | /<Agentspace アプリ#1 の名前> | /drive-app |
pathRedirect | /<アプリ 1 の Agentspace URL パス> | /us/home/cid/5970a1b4-080a-4b44-8acd-fa89460cf0cd |
hostRedirect | vertexaisearch.cloud.google.com | vertexaisearch.cloud.google.com |
prefixMatch | /<Agentspace アプリ#2 の名前> | /sharepoint-app |
pathRedirect | /<アプリ 2 のエージェント スペース URL パス> | //signin/locations/global/workforcePools/your-pool-name/providers/your-provider-name?continueUrl=https://vertexaisearch.cloud.google/home/cid/f190000-0000-4d0a-0000-d08df6e3bef6 |
hostRedirect | auth.cloud.google | vertexaisearch.cloud.google.com |
ホストとパスのルールにアクセスするには、次の場所に移動します。
[Load balancing]（ロード バランシング）→ [agentspace-lb] → [Select edit]（編集を選択）
[ルーティング ルール] → [詳細なホストとパスのルール] を選択します。
[ホストとパスのルールを追加] を選択します
新しいホストとパスのルールを作成する画面が表示されます。ホスト セクションに agentspace.YOUR-EXTERNAL-IP.nip.io またはカスタム ドメインを挿入します。
[パスマッチャー] フィールド（一致、アクション、サービス）で、環境構成に合わせて以下のコンテンツを更新し、[更新] を選択します。
defaultService: projects/<projectid>/global/backendServices/agentspace-ineg-bes
name: matcher1
routeRules:
- matchRules:
- prefixMatch: /<name of Agentspace app#1>
priority: 1
urlRedirect:
pathRedirect: /<Agentspace URL path of app#1>
hostRedirect: vertexaisearch.cloud.google.com
redirectResponseCode: FOUND
- matchRules:
- prefixMatch: /<name of Agentspace app#2>
priority: 2
urlRedirect:
pathRedirect: /<Agentspace URL path of app#2>
hostRedirect: auth.cloud.google
redirectResponseCode: FOUND
スクリーンショットの例:
11. 検証
デプロイが完了しました。カスタム ドメインを使用して Agentspace アプリケーションにアクセスするには、ウェブブラウザまたはターミナルで agentspace.YOUR-EXTERNAL-IP.nip.io/path（agentspace.34.54.158.206.nip.io など）を指定します。次の例をご覧ください。
Agentspace アプリケーション: drive-app
パス: agentspace.34.54.158.206.nip.io/drive-app
Agentspace アプリケーション: sharepoint-app
パス: agentspace.34.54.158.206.nip.io/sharepoint-app
12. クリーンアップ
OAuth 認証情報を削除するには、次の操作を行います。
[API とサービス] → [認証情報] に移動します。
[OAuth 2.0 クライアント ID] で、認証情報を選択して削除します。
単一の Cloud Shell ターミナルからラボ コンポーネントを削除します。
gcloud compute forwarding-rules delete agentspace-fr --global -q
gcloud compute target-https-proxies delete https-proxy --global -q
gcloud compute url-maps delete agentspace-lb --global -q
cloud compute ssl-certificates delete agentspace-self-signed-cert --global -q
gcloud compute backend-services delete agentspace-ineg-bes --global -q
gcloud compute network-endpoint-groups delete agentspace-ineg --global -q
gcloud dns --project=$projectid record-sets delete agentspace.$externalip.nip.io --zone="agentspace-dns" --type="A"
gcloud dns --project=$projectid managed-zones delete agentspace-dns
gcloud compute addresses delete external-ip --global -q
gcloud compute networks delete agentspace-vpc -q
13. 完了
お疲れさまでした。ここでは、高度なトラフィック管理を備えた外部アプリケーション ロードバランサを使用して、カスタム ドメインで Agentspace への接続を構成して検証しました。
ロードバランサ インフラストラクチャを作成し、カスタム ドメインを使用して Agentspace への接続を可能にするホストとパスのリダイレクトを有効にするインターネット NEG、Cloud DNS、高度なトラフィック管理を作成する方法を学習しました。
Cosmopup はコードラボが大好きです。
