カスタム エラー レスポンスを構成する

このドキュメントでは、カスタム エラー レスポンスの構成例について説明します。カスタム エラー レスポンスを構成する前に、カスタム エラー レスポンスの概要をご覧ください。

このページで説明する構成例では、URL マップリソースの 3 つのレベル（ロードバランサ レベル、URL ドメインレベル、URL パスレベル）でカスタム エラー レスポンス ポリシーを構成します。

この構成例は、次のドキュメントで説明しているコンセプトと設定に基づいて構成されています。

例 1: すべてのホストに共通するすべての 4xx エラーのエラーページを構成する

この例では、VM インスタンス グループのバックエンドを使用してグローバル外部アプリケーション ロードバランサを設定するの説明に従ってロードバランサを設定していることを前提としています。

この例では、ロードバランサへのリクエストが web-backend-service という名前のバックエンド サービスに転送されます。リクエストに 4xx レスポンスが返されると、カスタム エラー レスポンス ポリシーによりエラーサービスにリクエストが送信され、エラー オブジェクト（not-found.html）がクライアントに返されます。

カスタム エラー レスポンス ポリシーを作成する手順は次のとおりです。

  1. HTML エラーページ（not-found.html）を Cloud Storage バケットにアップロードします。

    gcloud storage cp Desktop/not-found.html gs://GCS_BUCKET_NAME/

  2. URL マップ（web-map-http）を web-map-http.yaml という名前のファイルにエクスポートします。

    gcloud compute url-maps export web-map-http --destination web-map-http.yaml

    カスタム エラー レスポンス ポリシーを追加する前の URL マップ（web-map-http）は、次のような構成になっています。

    creationTimestamp: '2020-01-14T19:12:44.680-08:00'
defaultService: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/web-backend-service
fingerprint: d0eJJpCBpHg=
kind: compute#urlMap
name: web-map-http
selfLink: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/urlMaps/web-map-http

  3. 次の YAML 構成の defaultCustomErrorResponsePolicy セクションでハイライト表示されているように、web-map-http.yaml を編集してカスタム エラー レスポンス ポリシーを追加します。この例では、エラー レスポンス ポリシーはロードバランサ レベル（urlMaps.defaultCustomErrorResponsePolicy）で構成されています。

    creationTimestamp: '2020-01-14T19:12:44.680-08:00'
defaultService: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/web-backend-service
defaultCustomErrorResponsePolicy:
  errorResponseRules:
    - matchResponseCodes:
      - 4xx
      path: '/not-found.html'
  errorService: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendBuckets/CUSTOM_ERRORS_BUCKET
fingerprint: d0eJJpCBpHg=
kind: compute#urlMap
name: web-map-http
selfLink: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/urlMaps/web-map-http

    すべてのエラー オブジェクトを Cloud Storage バケットに保存し、ロードバランサに接続されたバックエンド バケットから参照することをおすすめします。Cloud Storage バケットを使用すると、エラー オブジェクトを簡単に保存し、ロードバランサを介してクライアントに返すことができます。ただし、バックエンド バケットを使用せずにエラーページと関連アセットを提供することもできます。たとえば、VM インスタンス グループ バックエンドを参照し、カスタム エラー レスポンス ページを提供するように Apache サーバーが構成されているバックエンド サービスを使用することもできます。

  4. web-map-http.yaml から最新の構成をインポートして、URL マップを更新します。

    gcloud compute url-maps import web-map-http --source web-map-http.yaml

  5. URL マップを更新したら、ロードバランサの IP アドレスへのトラフィックの送信が始まるまでしばらく待つ必要があります。

    存在しないページのリクエストを送信します。

    curl -I http://IP_ADDRESS/a-page-that-does-not-exist

    not-found.html からのエラー コンテンツが提供され、HTTP 404 ステータス コードが返されます。

例 2: 特定のホストの特定のエラーコードのエラーページを構成する

前の例ではすべてのホストに共通するすべての 4xx エラーのエラーページを構成しましたが、この例はその構成に基づいています。この例では、ホスト video.example.com へのリクエストが video-backend-service という名前のバックエンド サービスに転送されるようにロードバランサが構成されていることを前提としています。リクエストがバックエンド サービスによる認証に失敗した場合、サービスは 401 (Unauthorized) レスポンスを返します。カスタム エラー レスポンス ポリシーにより、リクエストがエラーサービスに送信され、エラー オブジェクト（video-obtain-authorization.html）がクライアントに返されます。

ほとんどの場合、エラー コンテンツにはアセット（ロゴ画像など）へのリンクが含まれています。クライアントがエラーページで参照されているアセットをリクエストし、そのアセットを取得するために追加のリクエストがロードバランサに送信されます。その後、ロードバランサはリクエストに応答し、リンクされたアセットを返します。この処理を行うため、これらのアセットを defaultCustomErrorResponsePolicy で指定された同じバックエンド バケットに保存し、アセット URL（/assets/logo.svg など）からバックエンド バケットにリクエストを転送するルールを追加します。次の構成に示すように、リンクされたアセットのリクエストに対するロードバランサのレスポンスはエラー レスポンスではなく、通常のレスポンスになります。

pathMatchers:
...
  pathRules:
  - service: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendBuckets/CUSTOM_ERRORS_BUCKET
    paths:
    - /assets

このポリシーでは、リクエストの最終的なレスポンス コードを定義することもできます。この例では、overrideResponseCode の値を 200 にすることで、レスポンス コードを 401 から 200 に変更しています。他のすべての 4xx エラーの場合、not-found.html のエラー コンテンツがクライアントに返され、バックエンド サービスからの元の HTTP レスポンス コードが保持されます。

次の表に示すように、この例では 2 つのカスタム エラー レスポンス ポリシーが構成されています。これらのポリシーは、ロードバランサ レベルと URL ドメインレベルで作成されます。

ポリシーレベル API フィールド 一致する HTTP レスポンス コード エラーサービス 返されるエラー オブジェクト
URL ドメイン pathMatchers[].defaultCustomErrorResponsePolicy 401 CUSTOM_ERRORS_BUCKET video-obtain-authorization.html
ロードバランサ urlMaps.defaultCustomErrorResponsePolicy 4xx すべて CUSTOM_ERRORS_BUCKET not-found.html

ホスト video.example.com の 401 エラーコードのカスタム エラー レスポンス ポリシーを作成するには、次の操作を行います。

  1. HTML エラーページ（video-obtain-authorization.html）と関連アセット（logo.svg）を Cloud Storage バケットにアップロードします。

    gcloud storage cp Desktop/video-obtain-authorization.html gs://GCS_BUCKET_NAME/
gcloud storage cp Desktop/logo.svg gs://GCS_BUCKET_NAME/assets/

  2. URL マップ（web-map-http）を web-map-http.yaml という名前のファイルにエクスポートします。

    gcloud compute url-maps export web-map-http --destination web-map-http.yaml

  3. 次の YAML 構成の defaultCustomErrorResponsePolicy セクションでハイライト表示されているように、web-map-http.yaml を編集してカスタム エラー レスポンス ポリシーを追加します。この例では、カスタム エラー レスポンス ポリシーはロードバランサ レベル（urlMaps.defaultCustomErrorResponsePolicy）と URL ドメインレベル（pathMatchers[].defaultCustomErrorResponsePolicy）で構成されています。

    エラーサービスは URL ドメインレベルで定義されていないため、URL ドメインレベルのエラーサービスは、デフォルトで上位レベル（つまりロードバランサ レベル）で定義されたエラーサービスになります。

    creationTimestamp: '2020-01-14T19:12:44.680-08:00'
defaultService: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/web-backend-service
defaultCustomErrorResponsePolicy:
  errorResponseRules:
    - matchResponseCodes:
      - 4xx
      path: '/not-found.html'
  errorService: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendBuckets/CUSTOM_ERRORS_BUCKET
fingerprint: d0eJJpCBpHg=
hostRules:
- hosts:
  - video.example.com
  pathMatcher: path-matcher-1
kind: compute#urlMap
name: web-map-http
selfLink: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/urlMaps/web-map-http
pathMatchers:
- defaultService: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/video-backend-service
  name: path-matcher-1
  defaultCustomErrorResponsePolicy:
    errorResponseRules:
      - matchResponseCodes:
        - 401
        path: "/video-obtain-authorization.html
        overrideResponseCode: 200
    // The `errorService` in `pathMatchers[].defaultCustomErrorResponsePolicy` references the
    // error service configured in `urlMaps.defaultCustomErrorResponsePolicy`.

  // A URL map path rule to route requests from asset URLs (for example, "/assets/logo.svg") to the backend bucket.
  pathRules:
  - service: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendBuckets/CUSTOM_ERRORS_BUCKET
    paths:
    - /assets

  4. web-map-http.yaml から最新の構成をインポートして、URL マップを更新します。

    gcloud compute url-maps import web-map-http --source web-map-http.yaml

  5. URL マップを更新したら、ロードバランサの IP アドレスへのトラフィックの送信が始まるまでしばらく待つ必要があります。

    認証が必要な URL のリクエストをホストに送信します。

    curl -I http://video.example.com/a-page-that-needs-authorization

    video-obtain-authorization.html からのエラー コンテンツが提供され、HTTP 200 ステータス コードが返されます。

例 3: ドメイン、パス、エラー レスポンス コードごとにきめ細かいカスタム エラー レスポンス ポリシーを構成する

この例では、URL ドメイン、URL パス、HTTP エラー レスポンス コードごとにエラー レスポンスをカスタマイズする方法を示します。

この例で説明するカスタム エラー レスポンス構成は次のことを前提としています。

  • 次の図のように、ホストとパスベースのルーティングを使用して、外部アプリケーション ロードバランサの URL マップを構成している。

    バックエンド サービスの設定例
    バックエンド サービスの設定例（クリックして拡大）

  • カスタム エラーページを返すように、BUCKET_1 と BUCKET_2 という名前の 2 つのバックエンド バケットを構成している。

次の表に示すように、この例では 4 つのカスタム エラー レスポンス ポリシーが構成されています。これらのポリシーは、次の優先順位で 3 つのレベルに作成されます。

  1. URL パス（pathMatchers[].pathRules[].customErrorResponsePolicy）
  2. URL ドメイン（pathMatchers[].defaultCustomErrorResponsePolicy）
  3. ロードバランサ（urlMaps.defaultCustomErrorResponsePolicy）
ポリシーレベル リクエスト URL 一致する HTTP レスポンス コード エラーサービス 返されるエラー オブジェクト
URL パス example.net/video/hd/* 404 BUCKET-2 not-found-hd-videos-404.html
URL パス example.net/video/sd/* 404 BUCKET-2 not-found-sd-videos-404.html
URL ドメイン example.net/* 4xx すべて BUCKET-1 example-net-4xx.html
ロードバランサ Any 4xx または 5xx すべて BUCKET-1 error-page-generic.html

ロードバランサ レベルのカスタム エラー レスポンス ポリシーは、ポリシーがエラー条件に一致し、下位レベル（つまり、URL ドメインまたは URL パス）のエラーコードに一致するポリシーが定義されていない場合にのみ適用されます。同様に、URL ドメインレベルのカスタム エラー レスポンス ポリシーは、ポリシーがエラー条件に一致し、下位レベルのエラーコードに一致するポリシーが定義されていない場合にのみ適用されます。この例では、URL www.example.net/video/hd へのリクエストに対して 404 レスポンスが返されると、ファイル not-found-hd-videos-404.html が返されます。ただし、URL www.example.net/video/ に対するリクエストで 404 レスポンスが返された場合は、ファイル example-net-4xx.html が返されます。

URL マップの 3 つのレベルにわたるカスタム エラー レスポンス ポリシーを作成する手順は次のとおりです。

  1. エラー オブジェクトを Cloud Storage バケットにアップロードします。

    gcloud storage cp Desktop/error-page-generic.html gs://GCS_BUCKET_1_NAME/
gcloud storage cp Desktop/example-net-4xx.html gs://GCS_BUCKET_1_NAME/
gcloud storage cp Desktop/not-found-sd-videos-404.html gs://GCS_BUCKET_2_NAME/
gcloud storage cp Desktop/not-found-hd-videos-404.html gs://GCS_BUCKET_2_NAME/

  2. URL マップ（video-org-url-map）を video-org-url-map.yaml. という名前のファイルにエクスポートします。

    gcloud compute url-maps export video-org-url-map --destination video-org-url-map.yaml

    カスタム エラー レスポンス ポリシーを追加する前の URL マップ（video-org-url-map）は、次のような構成になっています。

    creationTimestamp: '2021-03-05T13:34:15.833-08:00'
defaultService: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/org-site
fingerprint: mfyJIT7Zurs=
hostRules:
- hosts:
  - '*'
  pathMatcher: video-matcher
- hosts:
  - example.net
  pathMatcher: video-matcher
id: '8886405179645041976'
kind: compute#urlMap
name: video-org-url-map
pathMatchers:
- defaultService: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/video-site
  name: video-matcher
  pathRules:
  - paths:
    - /video/hd
    - /video/hd/*
    service: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/video-hd
  - paths:
    - /video/sd
    - /video/sd/*
    service: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/video-sd
selfLink: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/urlMaps/video-org-url-map

  3. 次の YAML 構成の defaultCustomErrorResponsePolicy セクションでハイライト表示されているように、video-org-url-map.yaml を編集してカスタムエラー レスポンス ポリシーを追加します。

    エラーサービスは URL ドメインレベルで定義されていないため、URL ドメインレベルのエラーサービスは、デフォルトで上位レベル（つまりロードバランサ レベル）で定義されたエラーサービスになります。

    creationTimestamp: '2021-03-05T13:34:15.833-08:00'
defaultService: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/org-site
fingerprint: mfyJIT7Zurs=
hostRules:
- hosts:
  - '*'
  pathMatcher: video-matcher
- hosts:
  - example.net
  pathMatcher: video-matcher
id: '8886405179645041976'
kind: compute#urlMap
name: video-org-url-map
defaultCustomErrorResponsePolicy:
  errorResponseRules:
    - matchResponseCodes:
      - 4xx
      - 5xx
      path: '/error-page-generic.html'
  errorService: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendBuckets/BUCKET-1
pathMatchers:
- defaultService: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/video-site
  name: video-matcher
  defaultCustomErrorResponsePolicy:
      errorResponseRules:
        - matchResponseCodes:
          - 4xx
          path: '/example-net-4xx.html'
      // The `errorService` in `pathMatchers[].defaultCustomErrorResponsePolicy` references the
      // error service configured in `urlMaps.defaultCustomErrorResponsePolicy`.
  pathRules:
  - paths:
    - /video/hd
    - /video/hd/*
    service: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/video-hd
    customErrorResponsePolicy:
          errorResponseRules:
            - matchResponseCodes:
              - 404
              path: '/not-found-hd-videos-404.html'
          errorService: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendBuckets/BUCKET-2
  - paths:
    - /video/sd
    - /video/sd/*
    service: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/video-sd
    customErrorResponsePolicy:
          errorResponseRules:
            - matchResponseCodes:
              - 404
              path: '/not-found-sd-videos-404.html'
          errorService: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendBuckets/BUCKET-2
selfLink: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/urlMaps/video-org-url-map

  4. video-org-url-map.yaml から最新の構成をインポートして、URL マップを更新します。

    gcloud compute url-maps import video-org-url-map --source video-org-url-map.yaml

  5. URL マップを更新したら、ロードバランサの IP アドレスへのトラフィックの送信が始まるまでしばらく待つ必要があります。

    存在しないページのリクエストを送信します。

    curl -I http://example.net/a-page-that-does-not-exist

    example-net-4xx.html のエラー コンテンツが配信されます。

    同様に、URL ドメインと URL パスが異なる他の URL もテストします。