使用网址映射

本指南介绍如何配置 Google Cloud 网址映射。网址映射是一组规则，用于将传入 HTTP(S) 请求路由到特定的后端服务 或后端存储桶。最简单的网址映射与所有传入请求路径 (/*) 都匹配。

在阅读本指南之前，请先熟悉一下网址映射概念。

注意：本页面介绍如何在创建负载均衡器之前或之后配置特定负载均衡器组件或功能。使用特定组件对高级配置很有用，并且对于某些配置选项来说是必要的。在使用本页面中的信息之前，请先了解您需要的 Google Cloud 负载均衡器类型。

网址映射与以下 Google Cloud 产品结合使用：

• 外部应用负载均衡器（全球、传统和 区域级模式）
• 内部应用负载均衡器

• Cloud Service Mesh

与全球外部应用负载均衡器、区域级外部应用负载均衡器、内部应用负载均衡器和 Cloud Service Mesh 搭配使用的网址映射还支持多种高级流量管理功能。如需了解详情，请参阅网址映射概念：高级流量管理。

网址映射默认值

网址映射有两个默认值，如下表所述。

默认类型	设置	含义
网址映射默认值	gcloud compute url-maps create --default-service | --default-backend-bucket	如果路径匹配器或主机规则与传入的网址均不匹配，则使用指定的默认后端服务 或后端存储桶 。
路径匹配器默认值	gcloud compute url-maps add-path-matcher --default-service | --default-backend-bucket	如果网址的路径与路径匹配器匹配，但没有任何指定的 --path-rules 匹配，则使用指定的默认后端服务 或后端存储桶 。

主机规则

主机规则定义了一组要匹配请求的主机。

在主机规则中，主机名必须是完全限定域名 (FQDN)。主机名不能是 IPv4 或 IPv6 地址。例如：

• 运行：example.com
• 运行：web.example.com
• 运行：*.example.com
• 不能运行：35.244.221.250

配置网址映射

网址映射可以将流量发送到后端服务或后端存储桶。区域级外部应用负载均衡器和内部应用负载均衡器不支持后端存储桶。

重要提示：如果您最初在 Google Cloud 控制台中设置负载均衡器，那么网址映射的名称与负载均衡器的名称相同。

控制台

如需使用 Google Cloud 控制台添加网址映射，请执行以下步骤：

1. 打开负载均衡页面。

   转到“负载均衡”

2. 点击负载均衡器的名称。
3. 在负载均衡器详情页面上，点击所选负载均衡器对应的 修改。
4. 选择主机和路径规则。
5. 点击添加主机和路径规则。

6. 填写主机字段和/或路径字段，然后选择一个后端服务 或后端存储桶。

   1. 输入完全限定的主机名，例如 web.example.com。
   2. 输入路径，例如 /video。
   3. 在主机和路径规则页面的后端菜单中，选择可用的后端服务 或后端存储桶。
   注意：如果未将后端服务或后端存储桶 添加到网址映射的主机和路径规则，负载均衡器将不会使用该后端服务或后端存储桶 ，它们亦不会显示在负载均衡器的详细信息和修改页面中。

7. 在主机和路径规则左侧看到蓝色对勾标记后，点击更新按钮。

gcloud

如需使用 Google Cloud CLI 添加网址映射，请使用 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]

对于区域级外部应用负载均衡器和内部应用负载均衡器，请务必在创建网址映射时添加 --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-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

如需创建全局网址映射，请使用 google_compute_url_map 资源。

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

如需创建区域性网址映射，请使用 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
}

验证网址映射配置

注意：区域级外部应用负载均衡器和内部应用负载均衡器不支持 gcloud compute url-maps validate 命令。

部署网址映射之前，请确保您验证网址映射配置，以确保该映射将请求按预期路由到适当的后端。您可以通过将测试添加到网址映射配置来执行此操作。您可以尝试使用不同的网址映射规则，并根据需要运行任意数量的测试，以确保该映射在部署后能够正确路由流量。此外，如果将来需要更改任何规则，则可以在实际使用新配置之前测试这些更改。

使用 gcloud compute url-maps validate 命令验证网址映射配置。此命令仅测试提供的配置。无论测试通过还是失败，任何更改都不会保存到已部署的网址映射中。此行为与其他网址映射命令（edit、import）不同，后者也会运行相同的测试，但如果测试通过，则实际上会保存新配置。如果您想在不更改已部署的网址映射的情况下测试新的路由配置，请使用 validate 命令。

借助 validate 命令，您可以测试高级路由配置，例如基于标头和查询参数的路由、HTTP 到 HTTPS 的重定向以及网址重写。

控制台

您无法使用 Google Cloud 控制台来验证网址映射配置。请改用 gcloud 或 REST API。

gcloud

如需验证您的网址映射配置，请使用 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：替换为包含用于验证的网址映射配置的文件的路径。

验证对现有负载均衡器的网址映射的更改

如果您有一个需要更改网址映射的现有负载均衡器，则可以在使这些配置更改生效之前对其进行测试。

1. 将负载均衡器的现有网址映射导出到 YAML 文件。

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

2. 使用新配置修改 YAML 文件。例如，如果要修改外部应用负载均衡器，并将路径为 /video 的所有请求发送到名为 video-backend-service 的新后端服务，则可以添加对网址映射配置进行的测试，如下所示：

   具有单一默认 web-backend-service 的现有网址映射配置：

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

   修改了网址映射配置，添加了默认路径匹配器并测试了默认 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]
   

   如果测试失败，系统会显示一条错误消息。请对网址映射配置文件进行必要的修复，然后尝试重新验证。

   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. 确定新配置有效且不会影响现有设置后，您可将其导入到网址映射中。请注意，此步骤还会使用新配置部署网址映射。

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

将测试添加到网址映射

注意：区域级外部应用负载均衡器和内部应用负载均衡器不支持向网址映射添加测试。

您可以将配置测试添加到网址映射，以确保您的网址映射按预期将请求路由到后端服务或后端存储桶。

本部分介绍如何将测试添加到已部署的网址映射。如果您想测试对网址映射的新更改而无需实际部署该映射，请参阅验证网址映射配置。

当您修改网址映射时，测试会运行，并且在测试失败时系统会显示错误消息：

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'.

您可以选择向网址映射添加测试。

控制台

如需通过 Google Cloud 控制台运行测试，请执行以下操作：

1. 打开负载均衡页面。

   转到“负载均衡”

2. 点击负载均衡器的名称。
3. 在负载均衡器详情页面上，点击所选负载均衡器对应的 修改。
4. 点击路由规则。对于传统应用负载均衡器，这是主机和路径规则。
5. 点击显示配置测试。
6. 点击添加配置测试。添加以下测试网址和后端。
   • 测试主机和路径 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 向网址映射添加测试，请使用 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

请注意，如果您未在主机规则中指定主机，则所有主机（example.com 和 example.net）中的网址都可以匹配。如果您有追加规则，则必须创建能够同时匹配 example.com 和 example.net 的规则。

列出网址映射

控制台

您无法在 Google Cloud 控制台中列出所有网址映射。

gcloud

如需使用 Google Cloud CLI 显示网址映射列表，请使用 url-maps list 命令。

gcloud compute url-maps list

获取有关网址映射的信息

控制台

要获取有关网址映射的信息，请执行以下步骤：

1. 打开负载均衡页面。

   转到“负载均衡”

2. 点击负载均衡器的名称。
3. 在负载均衡器详情页面上，点击所选负载均衡器对应的 修改。
4. 查看主机和路径规则。

gcloud

如需使用 Google Cloud CLI 获取单个网址映射的相关信息，请使用 url-maps describe 命令。

gcloud compute url-maps describe URL_MAP_NAME

删除网址映射

仅在删除引用网址映射的所有目标代理后，您才能删除该网址映射。如需了解详情，请参阅删除目标代理。

控制台

要删除网址映射，请执行以下步骤：

1. 打开负载均衡页面。

   转到“负载均衡”

2. 点击负载均衡器的名称。
3. 在负载均衡器详情页面上，点击所选负载均衡器对应的 修改。
4. 在负载均衡器详情页面上，查看主机和路径规则。
5. 点击网址映射右侧的“X”将其删除，相应网址映射会随即消失。
6. 在主机和路径规则左侧看到蓝色对勾标记后，点击更新按钮。

gcloud

如需使用 Google Cloud CLI 删除网址映射，请使用 url-maps delete 命令。必须先删除引用该网址映射的所有目标 HTTP 代理，才能删除该网址映射。

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

删除路径匹配器

控制台

如需删除路径匹配器，请执行以下步骤：

1. 打开负载均衡页面。

   转到“负载均衡”

2. 点击负载均衡器的名称。
3. 在负载均衡器详情页面上，点击所选负载均衡器对应的 修改。
4. 选择主机和路径规则。
5. 在现有网址映射的路径字段中，点击路径匹配器名称上的“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. 在现有网址映射的主机字段中，点击主机名称上的“x”。
6. 在主机和路径规则左侧看到蓝色对勾标记后，点击更新按钮。

gcloud

要从网址映射中删除主机规则，请使用 gcloud compute url-maps remove-host-rule 命令：

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

例如，要从名为 my-map 的网址映射中移除包含主机 altostrat.com 的主机规则，请运行以下命令：

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

流量管理指南

并非所有网址映射都能用于所有产品。网址映射与负载均衡器一起使用，以支持多种高级流量管理功能，传统应用负载均衡器并非支持所有这些功能。

请使用下表了解管理作业的网址映射功能。

产品	网址映射功能和流量管理指南
全球外部应用负载均衡器	负载均衡器功能：路由和流量管理 流量管理概览 设置流量管理 设置网址重定向 设置 HTTP 到 HTTPS 重定向 主机名和路径 路由请求 Cookie
传统应用负载均衡器	负载均衡器功能：路由和流量管理 流量管理概览 设置网址重定向 设置 HTTP 到 HTTPS 重定向 主机名和路径 基于标头和查询参数的路由
区域级外部应用负载均衡器	负载均衡器功能：路由和流量管理 流量管理概览 设置流量管理 设置网址重定向 设置 HTTP 到 HTTPS 重定向 主机名和路径 路由请求 Cookie
内部应用负载均衡器	负载均衡器功能：路由和流量管理 流量管理概览 设置流量管理 设置网址重定向 设置 HTTP 到 HTTPS 重定向 Cookie 主机名和路径
Cloud Service Mesh	Cloud Service Mesh 功能：路由和流量管理 高级流量管理概览 配置高级流量管理

API 和 gcloud CLI 参考

除了 Google Cloud 控制台之外，您还可以使用 API 和 gcloud CLI 来创建网址映射。

API

如需了解通过 REST API 使用 URL 映射时可用的属性和方法的说明，请参阅以下内容：

产品	API 文档
外部应用负载均衡器	urlMaps
内部应用负载均衡器	regionUrlMaps
Cloud Service Mesh	urlMaps

注意：在网址映射 API 中，HttpRouteRuleMatch 表示 pathMatchers[].routeRules[].matchRules[] 的实例。

gcloud CLI

对于 Google Cloud CLI 中的 Google Cloud CLI，请参阅以下内容：

• gcloud compute url-maps

• 全球：--global

• 区域级：--region=[REGION]

如需高级流量管理，请使用 YAML 文件并使用 gcloud compute url-maps import 命令导入这些文件。

后续步骤

• 如需了解网址映射的工作原理，请参阅网址映射概览。
• 如需了解网址映射在外部应用负载均衡器中的工作原理，请参阅外部应用负载均衡器概览。
• 如需了解网址映射在内部应用负载均衡器中的工作原理，请参阅内部应用负载均衡器概览。