Usar mapas de URL

Neste guia, você aprenderá a configurar os mapas de URL do Google Cloud. Um mapa de URL é um conjunto de regras para rotear solicitações recebidas HTTP para serviços de back-end específicos ou buckets de back-end. Um mapa de URL mínimo corresponde a todos os caminhos de solicitação recebida (/*).

Antes de segui-lo, familiarize-se com os conceitos do mapa de URL.

Observação: nesta página, descrevemos como configurar um componente ou recurso específico do balanceador de carga antes ou depois de criar esse balanceador. Trabalhar com componentes específicos é útil para configurações avançadas e necessário para algumas opções de configuração. Antes de usar as informações desta página, saiba o tipo de balanceador de carga do Google Cloud de que você precisa.

Os mapas de URL são usados com estes produtos do Google Cloud:

• Balanceador de carga de aplicativo externo (modosglobal, clássico e regional)
• Balanceador de carga de aplicativo interno

• Cloud Service Mesh

Os mapas de URL usados com balanceadores de carga de aplicativo externos globais, balanceadores de carga de aplicativo externos regionais balanceadores de carga de aplicativo internos, e o Cloud Service Mesh também dão suporte a vários recursos de gerenciamento de tráfego. Saiba mais em Conceitos do mapa de URL: gerenciamento avançado de tráfego.

Padrões do mapa de URLs

Os mapas de URLs têm dois padrões, conforme descrito na tabela a seguir.

Tipo padrão	Configuração	Significado
Padrão do mapa de URL	gcloud compute url-maps create --default-service | --default-backend-bucket	O serviço ou bucket de back-end padrão especificado será usado se nenhuma correspondência de caminho ou regra de host corresponder ao URL de entrada.
Padrão de correspondência de caminho	gcloud compute url-maps add-path-matcher --default-service | --default-backend-bucket	O serviço ou bucket de back-end padrão especificado será usado se o caminho do URL corresponder a uma correspondência de caminho, mas nenhuma das --path-rules especificada.

Regras do host

Uma regra de host define um conjunto de hosts para fazer a correspondência entre as solicitações.

Em uma regra de host, o nome do host precisa ser um nome de domínio totalmente qualificado (FQDN). O nome do host não pode ser um endereço IPv4 ou IPv6. Exemplo:

• Funciona: example.com
• Funciona: web.example.com
• Funciona: *.example.com
• Não funciona: 35.244.221.250

Configurar mapas de URL

Um mapa de URLs pode enviar tráfego para serviços de back-end ou buckets de back-end. Os buckets de back-end não são compatíveis com balanceadores de carga regionais e internos de aplicativos externos.

Importante: se você configurou originalmente o balanceador de carga no Console do Google Cloud, o nome do mapa de URL será o mesmo do balanceador de carga.

Console

Para adicionar um mapa de URLs usando o Console do Google Cloud, execute as etapas a seguir:

1. Acesse a página Balanceamento de carga.

   Acessar o "Balanceamento de carga"

2. Clique no Nome de um balanceador de carga.
3. Na página Detalhes do balanceador de carga, clique em Editar no balanceador de carga selecionado.
4. Selecione Regras de host e caminho.
5. Clique em Adicionar regra de host e caminho.

6. Preencha o campo Host, o campo Caminhos ou ambos e selecione um serviço de back-end ou bucket de back-end.

   1. Insira um Nome de host totalmente qualificado, como web.example.com.
   2. Digite o caminho, por exemplo, /video.
   3. Na página Regras de host e caminho, do menu Back-ends, selecione um serviço ou bucketde back-end disponível.
   Observação: se um serviçoou bucket de back-end não for adicionado às regras de host e de caminho do mapa de URL, o serviçoou o bucket de back-end permanece não usado pelo balanceador de carga. Por isso, ele não vai aparecer nas páginas Detalhes e Editar do balanceador de carga.

7. Procure a marca de seleção azul à esquerda de Regras de host e caminho e clique no botão Atualizar.

gcloud

Para adicionar um mapa de URLs usando a Google Cloud CLI, use o comando 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]

Para balanceadores de carga de aplicativo externos regionais e balanceadores de carga de aplicativo internos, certifique-se de incluir a sinalização --region ao criar o mapa de URL.

Para excluir uma correspondência de caminho, use o comando 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"]

Esse comando requer um serviço ou bucket de back-end padrão ao qual ele possa enviar solicitações não correspondidas. A flag --path-rules define mapeamentos entre caminhos de solicitação e serviços ou bucketsde back-end. O exemplo a seguir roteia os caminhos de solicitação /video/ e /video/* para o serviço de back-end video-service:

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

Para criar uma regra de host, use o comando gcloud compute url-maps add-host-rule:

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

Por exemplo, o valor --hosts a seguir corresponde a solicitações para www.example.com e qualquer subdomínio de altostrat.com:

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

Para alterar o serviço ou o bucket padrão de um mapa de URLs, use o comando 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

Para criar um mapa de URLs global, use o recurso google_compute_url_map.

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

Para criar um mapa de URLs regional, use o recurso 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
}

Validar a configuração do mapa de URLs

Observação: o comando gcloud compute url-maps validate não é compatível com o balanceador de carga regional e externo do aplicativo.

Antes de implantar um mapa de URLs, valide a configuração do mapa de URL para confirmar se o mapa está roteando as solicitações para os back-ends apropriados, conforme o esperado. Para fazer isso, adicione testes à configuração do mapa de URL. Você pode testar diferentes regras de mapa de URL e executar quantos testes forem necessários para ter certeza de que o mapa encaminhará o tráfego adequadamente quando implantado. Além disso, se forem necessárias alterações de regra no futuro, é possível testá-las antes de realmente publicar com a nova configuração.

Use o comando gcloud compute url-maps validate para validar a configuração do mapa de URL. Esse comando testa apenas a configuração fornecida. Independentemente dos testes serem aprovados ou reprovados, nenhuma alteração é salva no mapa de URLs implantado. Esse comportamento é diferente de outros comandos do mapa de URL (edit e import), que também executam os mesmos testes, mas salvarão a nova configuração se forem aprovados. Quando você quiser testar uma nova configuração de roteamento sem fazer alterações no mapa de URL implantado, use o comando validate.

O comando validate permite que você teste configurações de rota avançadas, como roteamento com base em cabeçalhos e parâmetros de consulta, redirecionamentos HTTP para HTTPS e substituições de URL.

Console

Não é possível usar o Console do Google Cloud para validar a configuração do mapa de URL. Use gcloud ou a API REST.

gcloud

Para validar a configuração do mapa de URL, use o comando gcloud compute url-maps validate.

Para o balanceador de carga de aplicativo externo global:

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

Para o balanceador de carga clássico do aplicativo:

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

• PATH_TO_URL_MAP_CONFIG_FILE: substitua por um caminho para o arquivo que contém a configuração do mapa de URL para validação.

Validar alterações em um mapa de URL do balanceador de carga existente

Se você tiver um balanceador de carga que precise de alterações no mapa de URLs, teste essas alterações de configuração antes de ativá-las.

1. Exporte o mapa de URLs atual do balanceador de carga para um arquivo YAML.

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

2. Edite o arquivo YAML com a nova configuração. Por exemplo, se você quiser editar um balanceador de carga de aplicativo externo e enviar todas as solicitações com o caminho /video para um novo serviço de back-end chamado video-backend-service, adicione testes à configuração do mapa de URL da seguinte maneira:

   Configuração de mapa de URL existente com um único web-backend-service padrão:

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

   Configuração editada do mapa de URL com correspondência de caminhos e testes adicionados para o serviço de back-end padrão web-backend-service e o novo serviço de back-end 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. Valide a nova configuração.

   gcloud compute url-maps validate --source PATH_TO_URL_MAP_CONFIG_FILE
   

   Se todos os testes forem aprovados, você verá uma mensagem de sucesso como:

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

   Se os testes falharem, uma mensagem de erro será exibida. Faça as correções necessárias no arquivo de configuração do mapa de URL e tente fazer a validação novamente.

   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. Assim que nova configuração estiver funcionando e sem risco de afetar a configuração existente, será possível importá-la para o mapa de URL. Essa etapa também implanta o mapa de URLs com a nova configuração.

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

Adicionar testes a um mapa de URL

Observação: a adição de testes a mapas de URL não é compatível com o balanceador de carga de aplicativo externo regional e o interno.

É possível adicionar testes de configuração a um mapa de URL para garantir que seu mapa encaminhe as solicitações para os serviços ou buckets de back-end conforme esperado.

Esta seção descreve como adicionar testes a um mapa de URL que já foi implantado. Se você quiser testar novas alterações em um mapa de URL sem implantar o mapa, consulte Como validar a configuração do mapa de URL.

Quando você edita seu mapa de URL, os testes são executados. Se um teste falhar, uma mensagem de erro é exibida:

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

A adição de testes a mapas de URL é opcional.

Console

Para executar testes no Console do Google Cloud, faça o seguinte:

1. Acesse a página Balanceamento de carga.

   Acessar o "Balanceamento de carga"

2. Clique no Nome de um balanceador de carga.
3. Na página Detalhes do balanceador de carga, clique em Editar no balanceador de carga selecionado.
4. Clique em Regras de roteamento. Para um balanceador de carga de aplicativo clássico, são as regras de host e caminho.
5. Clique em Mostrar testes de configuração.
6. Clique em Adicionar teste de configuração. Adicione os seguintes URLs de teste e back-ends:
   • Host de teste e caminho 1 example.com e back-end www-service.
   • Host de teste e caminho 2 example.net e Back-end www-service.
   • Host de teste e caminho 3 example.net/web e Back-end www-service.
   • Host de teste e caminho 4 example.com/videos e back-end video-service.
   • Host de teste e caminho 5 example.com/videos/browse e Back-end video-service.
   • Host de teste e caminho 6 example.net/static e Back-end static-service.
   • Host de teste e caminho 7 example.net/static/images e back-end static-service.
7. Procure a marca de seleção azul à esquerda de Regras de roteamento e clique no botão Atualizar. Para um balanceador de carga de aplicativo clássico, procure a marca azul ao lado de Regras de host e caminho.

gcloud

Para adicionar testes ao mapa de URL usando a Google Cloud CLI, use o comando gcloud compute url-maps edit:

gcloud compute url-maps edit URL_MAP_NAME

Isso inicia um editor de texto. Para balanceadores de carga de aplicativo externos, os testes precisam usar o seguinte formato:

  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

Se você não especificar um host em uma regra de host, os URLs de todos os hosts (example.com e example.net) poderão ser correspondentes. Se você tiver regras de host, precisará criar regras correspondentes a example.com e example.net.

Listar mapas de URL

Console

Não é possível listar todos os mapas de URL no Console do Google Cloud.

gcloud

Para exibir uma lista de mapas de URL usando a Google Cloud CLI, use o comando url-maps list.

gcloud compute url-maps list

Receber informações sobre um mapa de URL

Console

Para ver informações sobre um mapa de URLs, execute estas etapas:

1. Acesse a página Balanceamento de carga.

   Acessar o "Balanceamento de carga"

2. Clique no Nome de um balanceador de carga.
3. Na página Detalhes do balanceador de carga, clique em Editar no balanceador de carga selecionado.
4. Veja as Regras de host e caminho.

gcloud

Para informações sobre um único mapa de URL usando a Google Cloud CLI, use o comando url-maps describe.

gcloud compute url-maps describe URL_MAP_NAME

Excluir um mapa de URL

Só é possível excluir um mapa de URL depois de ter excluído todos os proxies de destino que se referem a ele. Saiba mais em Como excluir um proxy de destino.

Console

Para excluir um mapa de URLs, execute as seguintes etapas:

1. Acesse a página Balanceamento de carga.

   Acessar o "Balanceamento de carga"

2. Clique no Nome de um balanceador de carga.
3. Na página Detalhes do balanceador de carga, clique em Editar no balanceador de carga selecionado.
4. Na página Detalhes do balanceador de carga, acessa as Regras de host e caminhos.
5. Clique no "X", à direita de um mapa de URLs para excluí-lo. O mapa de URLs desaparecerá.
6. Procure a marca de seleção azul à esquerda de Regras de host e caminho e clique no botão Atualizar.

gcloud

Para excluir um mapa de URLs usando a Google Cloud CLI, use o comando url-maps delete. Antes de excluir um mapa de URLs, primeiro é preciso excluir todos os proxies HTTP de destino que fizerem referência ao mapa de URL.

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

Excluir uma correspondência de caminho

Console

Para excluir uma correspondência de caminho, execute as seguintes etapas:

1. Acesse a página Balanceamento de carga.

   Acessar o "Balanceamento de carga"

2. Clique no Nome de um balanceador de carga.
3. Na página Detalhes do balanceador de carga, clique em Editar no balanceador de carga selecionado.
4. Selecione Regras de host e caminho.
5. No campo Caminhos, de um mapa de URLs, clique no “x” no nome da correspondência de caminho.
6. Procure a marca de seleção azul à esquerda de Regras de host e caminho e clique no botão Atualizar.

gcloud

Para excluir uma correspondência de caminho, use o comando gcloud compute url-maps remove-path-matcher:

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

Excluir uma regra de host

Console

Para excluir uma regra de host, execute as seguintes etapas:

1. Se você ainda não estiver na página Regras de host e caminho, acesse a página de Balanceamento de carga.

   Acessar o "Balanceamento de carga"

2. Clique no Nome de um balanceador de carga.
3. Na página Detalhes do balanceador de carga, clique em Editar no balanceador de carga selecionado.
4. Selecione Regras de host e caminho.
5. No campo Hosts de um mapa de URLs, clique no “x” no nome do host.
6. Procure a marca de seleção azul à esquerda de Regras de host e caminho e clique no botão Atualizar.

gcloud

Para excluir uma regra de host do seu mapa de URL, use o comando gcloud compute url-maps remove-host-rule:

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

Por exemplo, para remover uma regra de host que contém o host altostrat.com de um mapa de URL denominado my-map, execute o comando a seguir:

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

Guias de gerenciamento de tráfego

Nem todos os recursos do mapa de URL estão disponíveis para todos os produtos. Os mapas de URL são usados com balanceadores de carga para aceitar vários recursos avançados de gerenciamento de tráfego, mas nem todos são compatíveis com o balanceador de carga de aplicativo clássico.

Use a tabela a seguir para saber mais sobre os recursos do mapa de URL para trabalhos de gerenciamento.

Produto	Recursos de mapa de URL e guias de gerenciamento de tráfego
Balanceador de carga de aplicativo externo global	Recursos do balanceador de carga: roteamento e gerenciamento de tráfego Visão geral do gerenciamento de tráfego Como configurar o gerenciamento de tráfego Como configurar um redirecionamento de URL Como configurar um redirecionamento HTTP para HTTPS Nome e caminho do host Como encaminhar solicitações Cookies
Balanceador de carga de aplicativo clássico	Recursos do balanceador de carga: roteamento e gerenciamento de tráfego Visão geral do gerenciamento de tráfego Como configurar um redirecionamento de URL Como configurar um redirecionamento HTTP para HTTPS Nome e caminho do host Roteamento com base em parâmetros de cabeçalho e consulta
Balanceador de carga de aplicativo externo regional	Recursos do balanceador de carga: roteamento e gerenciamento de tráfego Visão geral do gerenciamento de tráfego Como configurar o gerenciamento de tráfego Como configurar um redirecionamento de URL Como configurar um redirecionamento HTTP para HTTPS Nome e caminho do host Como encaminhar solicitações Cookies
Balanceador de carga de aplicativo interno	Recursos do balanceador de carga: roteamento e gerenciamento de tráfego Visão geral do gerenciamento de tráfego Como configurar o gerenciamento de tráfego Como configurar redirecionamentos de URL Como configurar redirecionamentos HTTP-HTTPS Cookies Nome e caminho do host
Cloud Service Mesh	Cloud Service Mesh recursos: gerenciamento de tráfego e roteamento Visão geral do gerenciamento de tráfego avançado Configurar o gerenciamento de tráfego avançado

Referência da CLI gcloud e da API

Além do Console do Google Cloud, é possível usar a API e a CLI gcloud para criar mapas de URL.

API

Veja descrições das propriedades e dos métodos disponíveis ao trabalhar com mapas de URL por meio da API REST em:

Produto	Documentação da API
Balanceador de carga de aplicativo externo	urlMaps
Balanceador de carga de aplicativo interno	regionUrlMaps
Cloud Service Mesh	urlMaps

Observação: na API do mapa de URL, HttpRouteRuleMatch significa uma instância de pathMatchers[].routeRules[].matchRules[].

CLI gcloud

Para a Google Cloud CLI na Google Cloud CLI, consulte:

• gcloud compute url-maps

• Global: --global

• Regional: --region=[REGION]

Para gerenciamento de tráfego avançado, use arquivos YAML e importe-os com o comando gcloud compute url-maps import.

A seguir

• Saiba mais sobre como os mapas de URL funcionam em Visão geral dos mapas de URL.
• Consulte Visão geral do balanceador de carga de aplicativo externo para informações sobre como os mapas de URL funcionam em balanceadores de carga de aplicativo externos.
• Consulte Visão geral do balanceador de carga interno do aplicativo para informações sobre como os mapas de URL funcionam nos balanceadores de carga internos do aplicativo.