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.

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

Os mapas de URL usados com balanceadores de carga de aplicativo externos globais, balanceadores de carga de aplicativo externo e regional, bem como o Traffic Director, também são compatíveis com vários recursos avançados 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.

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 host e regra de 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 bucket de back-end disponível.

  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 buckets de 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 google.com:

--hosts=[*.google.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

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

É 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 google.com de um mapa de URL denominado my-map, execute o comando a seguir:

gcloud compute url-maps remove-host-rule my-map --host google.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

Traffic Director Recursos do Traffic Director: roteamento e gerenciamento de tráfego

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
Traffic Director urlMaps

CLI gcloud

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

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

A seguir