URL マップを使用する

このガイドでは、 Google CloudURL マップの構成方法について説明します。URL マップは、受信 HTTP(S) リクエストを特定のバックエンド サービス またはバックエンド バケットに転送するための一連のルールです。最小限の URL マップは、受信したすべてのリクエストパス（/*）と一致します。

このガイドに記載された手順を行う前に、URL マップのコンセプトを十分に理解してください。

注: このページでは、ロードバランサの作成前または作成後に、ロードバランサの特定のコンポーネントまたは機能を構成する方法について説明します。特定のコンポーネントを操作することは、高度な構成に役立ちます。また、一部の構成オプションでは、そうする必要があります。このページの情報を使用する前に、必要な Google Cloud ロードバランサの種類を確認してください。

URL マップは、次の Google Cloud プロダクトで使用されます。

• 外部アプリケーション ロードバランサ（グローバル、従来、 リージョン モード）
• 内部アプリケーション ロードバランサ

• Cloud Service Mesh

グローバル外部アプリケーション ロードバランサ、リージョン外部アプリケーション ロードバランサ、内部アプリケーション ロードバランサ、Cloud Service Mesh で使用される URL マップは、いくつかの高度なトラフィック管理機能もサポートしています。詳細については、URL マップのコンセプト: 高度なトラフィック管理をご覧ください。

URL マップのデフォルト

次の表に示すように、URL マップには 2 つのデフォルトがあります。

デフォルトの種類	設定	意味
URL マップのデフォルト	gcloud compute url-maps create --default-service | --default-backend-bucket	受信 URL に一致するパスマッチャーやホストルールがない場合、指定したデフォルトのバックエンド サービス またはバックエンド バケット が使用されます。
パスマッチャーのデフォルト	gcloud compute url-maps add-path-matcher --default-service | --default-backend-bucket	URL のパスがパスマッチャーと一致しても、指定された --path-rules が一致しない場合、指定したデフォルトのバックエンド サービス またはバックエンド バケット が使用されます。

ホストルール

ホストルールでは、リクエストと照合する一連のホストを定義します。

ホストルールでは、ホスト名は完全修飾ドメイン名（FQDN）にする必要があります。ホスト名には IPv4 または IPv6 アドレスを使用できません。例:

• 正常に機能する: example.com
• 正常に機能する: web.example.com
• 正常に機能する: *.example.com
• 正常に機能しない: 35.244.221.250

URL マップを構成する

URL マップにより、トラフィックをバックエンド サービスに送信できます。また、バックエンド バケットにも送信できます。バックエンド バケットは、リージョン外部アプリケーション ロードバランサと内部アプリケーション ロードバランサではサポートされていません。

重要: 最初にGoogle Cloud コンソールでロードバランサを設定した場合、URL マップ名はロードバランサの名前と同じになります。

コンソール

Google Cloud コンソールを使用して URL マップを追加するには、次の操作を行います。

1. [ロード バランシング] ページに移動します。

   [ロード バランシング] に移動

2. ロードバランサの名前をクリックします。
3. [ロードバランサの詳細] ページで、選択したロードバランサの [編集] をクリックします。
4. [ホストとパスのルール] を選択します。
5. [ホストとパスのルールを追加] をクリックします。

6. [ホスト] フィールド、[パス] フィールド、またはその両方を入力して、[バックエンド サービス] または [バックエンド バケット]を選択します。

   1. 完全修飾のホスト名を入力します（例: web.example.com）。
   2. パスを入力します（例: /video）。
   3. [ホストとパスのルール] ページの [バックエンド] メニューで、使用可能なバックエンド サービス またはバックエンド バケットを選択します。
   注: バックエンド サービスまたはバックエンド バケット が URL マップのホストとパスのルールに追加されない場合、バックエンド サービスまたはバックエンド バケット はロードバランサによって使用されないままになるため、ロードバランサの [詳細] ページと [編集] ページには表示されません。

7. [ホストとパスのルール] の左側の青色のチェックマークを確認して、[更新] ボタンをクリックします。

gcloud

Google Cloud CLI を使用して URL マップを追加するには、url-maps create コマンドを使用します。

gcloud compute url-maps create URL_MAP_NAME \
   (--default-backend-bucket=DEFAULT_BACKEND_BUCKET | --default-service=DEFAULT_SERVICE) \
   [--description DESCRIPTION] \
   [--global | --region=REGION]

リージョン外部アプリケーション ロードバランサと内部アプリケーション ロードバランサの場合、URL マップの作成時に必ず --region フラグを指定します。

パスマッチャーを作成するには、gcloud compute url-maps add-path-matcher コマンドを使用します。

gcloud compute url-maps add-path-matcher URL_MAP_NAME \
   (--default-backend-bucket=DEFAULT_BACKEND_BUCKET | --default-service=DEFAULT_SERVICE) \
   --path-matcher-name PATH_MATCHER \
   [--path-rules="PATH=SERVICE or BUCKET"]

このコマンドには、一致しないリクエストを送信できるデフォルトのバックエンド サービス またはバックエンド バケット が必要です。--path-rules フラグでは、リクエストパスとバックエンド サービス （バックエンド バケット）の間のマッピングを定義します。次の例では、リクエストパス /video/ および /video/* が video-service バックエンド サービスに転送されます。

--path-rules="/video=video-service,/video/*=video-service"

ホストルールを作成するには、gcloud compute url-maps add-host-rule コマンドを使用します。

gcloud compute url-maps add-host-rule URL_MAP_NAME \
    --hosts=[HOSTS] --path-matcher-name=PATH_MATCHER

たとえば、次の --hosts 値は、リクエストを www.example.com および altostrat.com のすべてのサブドメインと照合します。

--hosts=[*.altostrat.com,www.example.com]

URL マップのデフォルトのサービス またはデフォルトのバケット を変更するには、url-maps set-default-service コマンドを使用します。

gcloud compute url-maps set-default-service URL_MAP_NAME
  (--default-backend-bucket=DEFAULT_BACKEND_BUCKET
  | --default-service=DEFAULT_SERVICE)[GCLOUD_WIDE_FLAG ...]

Terraform

グローバル URL マップを作成するには、google_compute_url_map リソースを使用します。

# url map
resource "google_compute_url_map" "default" {
  name            = "http-lb"
  default_service = google_compute_backend_bucket.default.id
}

リージョン URL マップを作成するには、google_compute_region_url_map リソースを使用します。

resource "google_compute_region_url_map" "default" {
  name            = "regional-l7-xlb-map"
  region          = "us-west1"
  default_service = google_compute_region_backend_service.default.id
}

URL マップの構成を検証する

注: gcloud compute url-maps validate コマンドは、リージョン外部アプリケーション ロードバランサと内部アプリケーション ロードバランサではサポートされていません。

URL マップをデプロイする前に、URL マップ構成を検証して、マップが意図したとおりに適切なバックエンドにリクエストをルーティングしていることを確認してください。これを行うには、URL マップの構成にテストを追加します。さまざまな URL マップルールをテストし、必要な回数のテストを実行して、デプロイ時にマップがトラフィックを適切にルーティングすることを確認できます。また、今後、ルールの変更が必要になった場合は、新しい構成を実際に使用する前に変更内容をテストできます。

URL マップの構成を検証するには、gcloud compute url-maps validate コマンドを使用します。このコマンドは、指定された構成のみをテストします。テストに合格したかどうかにかかわらず、デプロイされた URL マップに変更は保存されません。この動作は、同じ URL テストを実行する他の URL マップコマンド（edit、import）とは異なり、テストに合格すると新しい構成を保存します。デプロイされている URL マップを変更せずに新しいルーティング構成をテストするには、validate コマンドを使用します。

validate コマンドを使用すると、ヘッダーとクエリ パラメータに基づくルーティング、HTTP から HTTPS へのリダイレクト、URL の書き換えなどの高度なルート構成をテストできます。

コンソール

Google Cloud コンソールを使用して URL マップの構成を検証することはできません。gcloud または REST API を使用してください。

gcloud

URL マップの構成を検証するには、gcloud compute url-maps validate コマンドを使用します。

グローバル外部アプリケーション ロードバランサの場合:

gcloud compute url-maps validate --source PATH_TO_URL_MAP_CONFIG_FILE \
    --load-balancing-scheme=EXTERNAL_MANAGED \
    --global

従来のアプリケーション ロードバランサの場合:

gcloud compute url-maps validate --source PATH_TO_URL_MAP_CONFIG_FILE \
    --load-balancing-scheme=EXTERNAL \
    --global

• PATH_TO_URL_MAP_CONFIG_FILE: 検証用の URL マップ構成を含むファイルのパスに置き換えます。

既存ロードバランサの URL マップに対する変更を検証する

URL マップの変更が必要な既存のロードバランサがある場合は、公開する前にこれらの構成の変更をテストできます。

1. ロードバランサの既存の URL マップを YAML ファイルにエクスポートします。

   gcloud compute url-maps export URL_MAP_NAME \
      --destination PATH_TO_URL_MAP_CONFIG_FILE \
      --global
   

2. 新しい構成で YAML ファイルを編集します。たとえば、外部アプリケーション ロードバランサを編集して、パス /video を含むすべてのリクエストを video-backend-service という新しいバックエンド サービスに送信する場合は、次のように URL マップ構成にテストを追加できます。

   1 つのデフォルト web-backend-service が設定された既存の URL マップ構成。

    kind: compute#urlMap
    name: URL_MAP_NAME
    defaultService: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendService/web-backend-service
    

   追加のパスマッチャーを使用した編集された URL マップ構成。デフォルト web-backend-service と新しい video-backend-service バックエンド サービス両方のテストを実行します。

    kind: compute#urlMap
    name: URL_MAP_NAME
    defaultService: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendService/web-backend-service
    hostRules:
    - hosts:
      - '*'
      pathMatcher: pathmap
    pathMatchers:
    - defaultService: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendService/web-backend-service
      name: pathmap
      pathRules:
      - paths:
        - /video
        - /video/*
        service: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendService/video-backend-service
    tests:
    - description: Test routing to existing web service
      host: foobar
      path: /
      service: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendService/web-backend-service
    - description: Test routing to new video service
      host: foobar
      path: /video
      service: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendService/video-backend-service
   

3. 新しい構成を検証します。

   gcloud compute url-maps validate --source PATH_TO_URL_MAP_CONFIG_FILE
   

   すべてのテストに合格すると、成功を示す次のようなメッセージが表示されます。

   Successfully validated [https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/urlMaps/URL_MAP_CONFIG_FILE_NAME]
   

   テストに失敗すると、エラー メッセージが表示されます。URL マップ構成ファイルに必要な修正を加え、検証を再試行してください。

   Error: Invalid value for field 'urlMap.tests': ''.
   Test failure: Expect URL 'HOST/PATH' to map to service 'EXPECTED_BACKEND_SERVICE', but actually mapped to 'ACTUAL_BACKEND_SERVICE'.
   

4. 新しい構成が機能し、既存の設定に影響を与えないことを確認できたら、URL マップにインポートできます。この手順では、新しい構成で URL マップもデプロイされます。

   gcloud compute url-maps import URL_MAP_NAME \
      --source PATH_TO_URL_MAP_CONFIG_FILE \
      --global
   

URL マップにテストを追加する

注: URL マップへのテストの追加は、リージョン外部アプリケーション ロードバランサと内部アプリケーション ロードバランサではサポートされていません。

URL マップに構成テストを追加すると、URL マップがバックエンド サービスまたはバックエンド バケットにリクエストを正しくルーティングしているかどうかを確認できます。

このセクションでは、デプロイ済みの URL マップにテストを追加する方法について説明します。マップを実際にデプロイせずに URL マップの新しい変更をテストする場合は、URL マップ構成を検証するをご覧ください。

URL マップを編集するとテストが実行されます。テストに失敗すると、エラー メッセージが表示されます。

Error: Invalid value for field 'urlMap.tests': ''.
Test failure: Expect URL 'HOST/PATH' to map to service 'EXPECTED_BACKEND_SERVICE', but actually mapped to 'ACTUAL_BACKEND_SERVICE'.

URL マップへのテストの追加は任意です。

コンソール

Google Cloud コンソールからテストを実行するには:

1. [ロード バランシング] ページに移動します。

   [ロード バランシング] に移動

2. ロードバランサの名前をクリックします。
3. [ロードバランサの詳細] ページで、選択したロードバランサの [編集] をクリックします。
4. [ルーティング ルール] をクリックします。従来のアプリケーション ロードバランサの場合、これはホストとパスのルールです。
5. [構成テストを表示する] をクリックします。
6. [構成テストの追加] をクリックします。次のテスト URL とバックエンドを追加します。
   • テストホストとパス 1 example.com とバックエンド www-service.
   • テストホストとパス 2 example.net とバックエンド www-service.
   • ホストとパスのテスト 3 example.net/web とバックエンド www-service.
   • テストホストとパス 4 example.com/videos とバックエンド video-service.
   • テストホストとパス 5 example.com/videos/browse とバックエンド video-service.
   • テストホストとパス 6 example.net/static とバックエンド static-service.
   • テストホストとパス 7 example.net/static/images とバックエンド static-service.
7. [ルーティング ルール] の左側にある青色のチェックマークを確認して、[更新] ボタンをクリックします。従来のアプリケーション ロードバランサの場合、[ホストとパスのルール] の横にある青色のチェックマークを探します。

gcloud

Google Cloud CLI を使用して URL マップにテストを追加するには、gcloud compute url-maps edit コマンドを使用します。

gcloud compute url-maps edit URL_MAP_NAME

これによってテキスト エディタが起動します。外部アプリケーション ロードバランサの場合、テストで次の形式を使用する必要があります。

  tests:
    - host: example.com
    service: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/www-service
    - host: example.net
    service: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/www-service
    - host: example.com
      path: /videos
      service: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/video-service
    - host: example.com
      path: /videos/browse
      service: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/video-service
    - host: example.net
      path: /web
      service: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/www-service
    - host: example.net
      path: /static
      service: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/static-service
    - host: example.net
      path: /static/images
      service: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/static-service

ホストルールでホストを指定しない場合、すべてのホストの URL（example.com と example.net の両方）が一致する場合があります。ホストルールがある場合は、example.com と example.net の両方に一致するルールを作成する必要があります。

URL マップの一覧表示

コンソール

Google Cloud コンソールですべての URL マップを一覧表示することはできません。

gcloud

Google Cloud CLI を使用して URL マップのリストを表示するには、url-maps list コマンドを使用します。

gcloud compute url-maps list

URL マップに関する情報の取得

コンソール

URL マップに関する情報を取得するには、次の手順を実行します。

1. [ロード バランシング] ページに移動します。

   [ロード バランシング] に移動

2. ロードバランサの名前をクリックします。
3. [ロードバランサの詳細] ページで、選択したロードバランサの [編集] をクリックします。
4. ホストとパスのルールを表示します。

gcloud

Google Cloud CLI を使用して単一の URL マップに関する情報を取得するには、url-maps describe コマンドを使用します。

gcloud compute url-maps describe URL_MAP_NAME

URL マップの削除

URL マップを削除する前に、参照先のすべてのターゲット プロキシを削除する必要があります。詳細については、ターゲット プロキシの削除をご覧ください。

コンソール

URL マップを削除するには、次の手順を実行します。

1. [ロード バランシング] ページに移動します。

   [ロード バランシング] に移動

2. ロードバランサの名前をクリックします。
3. [ロードバランサの詳細] ページで、選択したロードバランサの [編集] をクリックします。
4. [ロードバランサの詳細] ページで、[ホストとパスのルール] を表示します。
5. URL マップの右側にある「X」をクリックして削除します。URL マップが表示から消えます。
6. [ホストとパスのルール] の左側の青色のチェックマークを確認して、[更新] ボタンをクリックします。

gcloud

Google Cloud CLI を使用して URL マップを削除するには、url-maps delete コマンドを使用します。URL マップを削除する際は、事前にその URL マップを参照するターゲット HTTP プロキシを削除しておく必要があります。

gcloud compute url-maps delete URL_MAP_NAME [--quiet]

パスマッチャーの削除

コンソール

パスマッチャーを削除するには、次の手順を実行します。

1. [ロード バランシング] ページに移動します。

   [ロード バランシング] に移動

2. ロードバランサの名前をクリックします。
3. [ロードバランサの詳細] ページで、選択したロードバランサの [編集] をクリックします。
4. [ホストとパスのルール] を選択します。
5. 既存の URL マップの [パス] フィールドで、パスマッチャーの名前の「x」をクリックします。
6. [ホストとパスのルール] の左側の青色のチェックマークを確認して、[更新] ボタンをクリックします。

gcloud

パスマッチャーを削除するには、gcloud compute url-maps remove-path-matcher コマンドを使用します。

gcloud compute url-maps remove-path-matcher URL_MAP_NAME \
   [--path-matcher-name PATH_MATCHER]

ホストルールの削除

コンソール

ホストルールを削除するには、次の操作を行います。

1. [ホストとパスのルール] ページが表示されていない場合は、[ロード バランシング] ページに移動します。

   [ロード バランシング] に移動

2. ロードバランサの名前をクリックします。
3. [ロードバランサの詳細] ページで、選択したロードバランサの [編集] をクリックします。
4. [ホストとパスのルール] を選択します。
5. 既存の URL マップの [ホスト] フィールドで、ホストの名前の「x」をクリックします。
6. [ホストとパスのルール] の左側の青色のチェックマークを確認して、[更新] ボタンをクリックします。

gcloud

URL マップからホストルールを削除するには、gcloud compute url-maps remove-host-rule コマンドを使用します。

gcloud compute url-maps remove-host-rule URL_MAP_NAME --host=HOST

たとえば、ホスト altostrat.com を含むホストルールを my-map という名前の URL マップから削除するには、次のコマンドを実行します。

gcloud compute url-maps remove-host-rule my-map --host altostrat.com

トラフィック管理ガイド

すべてのプロダクトで、すべての URL マップ機能が利用できるわけではありません。URL マップは、いくつかの高度なトラフィック管理機能をサポートするためにロードバランサで使用されますが、これらの機能が一部は従来のアプリケーション ロードバランサでサポートされていません。

次の表に、管理作業に使用する URL マップ機能を示します。

プロダクト	URL マップの機能とトラフィック管理ガイド
グローバル外部アプリケーション ロードバランサ	ロードバランサの機能: ルーティングとトラフィック管理 トラフィック管理の概要 トラフィック管理の設定 URL リダイレクトの設定 HTTP から HTTPS へのリダイレクトの設定 ホスト名とパス リクエストのルーティング Cookie
従来のアプリケーション ロードバランサ	ロードバランサの機能: ルーティングとトラフィック管理 トラフィック管理の概要 URL リダイレクトの設定 HTTP から HTTPS へのリダイレクトの設定 ホスト名とパス ヘッダーとクエリ パラメータ ベースのルーティング
リージョン外部アプリケーション ロードバランサ	ロードバランサの機能: ルーティングとトラフィック管理 トラフィック管理の概要 トラフィック管理の設定 URL リダイレクトの設定 HTTP から HTTPS へのリダイレクトの設定 ホスト名とパス リクエストのルーティング Cookie
内部アプリケーション ロードバランサ	ロードバランサの機能: ルーティングとトラフィック管理 トラフィック管理の概要 トラフィック管理の設定 URL リダイレクトの設定 HTTP から HTTPS へのリダイレクトの設定 Cookie ホスト名とパス
Cloud Service Mesh	Cloud Service Mesh の機能: ルーティングとトラフィック管理 高度なトラフィック管理の概要 高度なトラフィック管理の構成

API と gcloud CLI のリファレンス

Google Cloud コンソールに加えて、API と gcloud CLI を使用して URL マップを作成できます。

API

REST API で URL マップを操作するときに使用できるプロパティとメソッドについては、以下をご覧ください。

プロダクト	API ドキュメント
外部アプリケーション ロードバランサ	urlMaps
内部アプリケーション ロードバランサ	regionUrlMaps
Cloud Service Mesh	urlMaps

注: URL マップ API では、HttpRouteRuleMatch は pathMatchers[].routeRules[].matchRules[] のインスタンスを意味します。

gcloud CLI

Google Cloud CLI については、以下をご覧ください。

• gcloud compute url-maps

• グローバル: --global

• リージョン: --region=[REGION]

高度なトラフィック管理を行うには、YAML ファイルを使用し、gcloud compute url-maps import コマンドを使用してインポートします。

次のステップ

• URL マップの仕組みを確認する。URL マップの概要をご覧ください。
• 外部アプリケーション ロードバランサでの URL マップの動作を確認する。外部アプリケーション ロードバランサの概要をご覧ください。
• 内部アプリケーション ロードバランサ内の URL マップの動作を確認する。内部アプリケーション ロードバランサの概要をご覧ください。