Usar mapas de URL

Neste guia, você aprenderá a configurar os mapas de URL do Google Cloud. Antes de segui-lo, familiarize-se com os conceitos do mapa de URL.

Observação: esta página descreve como criar um componente específico do balanceador de carga antes ou depois de criar um balanceador de carga. 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. Para dar os primeiros passos rapidamente com a configuração do balanceador de carga, siga um exemplo completo de configuração.

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

• Balanceamento de carga HTTP(S) externo (modos global, regional e clássico)
• Balanceamento de carga HTTP(S) interno
• Traffic Director

Os mapas de URL usados com balanceadores de carga HTTP(S) externos globais, balanceadores de carga HTTP(S) externos regionais, balanceadores de carga HTTP(S) internos e o Traffic Director também tem suporte a vários recursos avançados de gerenciamento de tráfego. Saiba mais em Conceitos do mapa de URL: gerenciamento avançado de tráfego.

Configurar mapas de URL

É possível adicionar serviços de back-end e buckets de back-end a um mapa de URL.

Os buckets de back-end não tem suporte a balanceadores de carga HTTP(S) externos regionais e a balanceadores de carga HTTP(S) internos.

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

Adicionar um mapa de URL

Console

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

1. Acesse a página Balanceamento de carga.

   Acessar a página "Balanceamento de carga"

2. Clique no Nome de um balanceador de carga.
3. Na tela 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.
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 URL usando a ferramenta de linha de comando gcloud, 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 HTTP(S) externos regionais e internos, inclua a sinalização --region ao criar o mapa de URL.

Um mapa de URL recém-criado corresponde apenas a um caminho, o padrão (/*). Essa correspondência de caminho padrão é criada automaticamente. Todo tráfego que não coincide com uma correspondência de caminho ou regra de host criadas manualmente é enviado para o serviço de back-end padrão do mapa de URL.

Adicionar uma correspondência de caminho

Uma correspondência de caminho mapeia os caminhos de solicitação HTTP(S) ou os prefixos de caminho, por exemplo, /video, em serviços de back-end. Todo o tráfego correspondente ao caminho especificado é processado pelas regras de caminho na correspondência de caminho. Se um caminho corresponde a uma regra de caminho, a solicitação é encaminhada para os back-ends associados a essa regra. Se uma solicitação corresponder às regras no path da correspondência de caminho, ela será encaminhada para o back-end padrão dele.

Console

Para criar uma correspondência de caminho usando o Console do Cloud, execute as etapas a seguir:

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

   Acessar a página "Balanceamento de carga"

2. Clique no Nome de um balanceador de carga.
3. Na tela Detalhes do balanceador de carga, clique em Editar no balanceador de carga selecionado.
4. Na tela Regras de host e caminho, clique em Adicionar regra de host e caminho ou clique em um campo de Caminhos atuais.
5. Digite o caminho para configurar, por exemplo, /video.
6. Procure a marca de seleção azul à esquerda de Regras de host e caminho e clique no botão Atualizar.

gcloud

Para criar uma correspondência de caminho usando a ferramenta de linha de comando gcloud, use o comando gcloud compute url-maps add-path-matcher:

gcloud compute url-maps add-path-matcher URL_MAP_NAME \
   --default-service BACKEND_SERVICE \
   --path-matcher-name PATH_MATCHER \
   [--path-rules="PATH=SERVICE"]

Esse comando requer um serviço de back-end padrão para o qual possa enviar solicitações sem correspondência. Se preferir, use a sinalização --path-rules para definir mapeamentos entre caminhos de solicitação e serviços 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"

Os comandos url-maps create e url-maps add-path-matcher têm um parâmetro --default-service. Em create, o serviço padrão é aquele usado se nenhuma das correspondências de caminho coincidir com o URL de entrada. Em add-path-matcher, o serviço padrão é aquele usado se o caminho coincidir com a correspondência de caminho, mas nenhuma das --path-rules corresponder.

Adicionar 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

Console

Para criar uma regra de host usando o Console do Cloud, execute as etapas as seguir:

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

   Acessar a página "Balanceamento de carga"

2. Clique no Nome de um balanceador de carga.
3. Na tela Detalhes do balanceador de carga, clique em Editar no balanceador de carga selecionado.
4. Na tela Regras de host e caminho, clique em Adicionar regra de host e caminho ou em um dos campos de Hosts atuais.
5. Insira um Nome de host totalmente qualificado, como web.example.com.
6. Procure a marca de seleção azul à esquerda de Regras de host e caminho e clique no botão Atualizar.

gcloud

Para criar uma regra de host usando a ferramenta de linha de comando gcloud, 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

A sinalização --hosts define um conjunto de hosts para fazer a correspondência entre as solicitações. Por exemplo, o valor --hosts a seguir corresponderia às solicitações www.example.com e qualquer subdomínio de google.com:

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

Selecione um serviço ou bucket de back-end

Console

Para selecionar um serviço ou bucket de back-end para um mapa de URL, execute as etapas a seguir:

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

   Acessar a página "Balanceamento de carga"

2. Clique no Nome de um balanceador de carga.
3. Na tela Detalhes do balanceador de carga, clique em Editar no balanceador de carga selecionado.
4. Na tela Regras de host e caminho, no menu suspenso do campo Back-ends, selecione um serviço ou bucket de back-end disponível.
5. Procure a marca de seleção azul à esquerda de Regras de host e caminho e clique no botão Atualizar.

gcloud

Para selecionar um serviço ou bucket de back-end usando a ferramenta de linha de comando gcloud, 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 ...]

Validar a configuração do mapa de URLs

Observação: este recurso não tem suporte ao balanceador de carga HTTP(S) externo global com recurso avançado de gerenciamento de tráfego. É possível usá-lo com o balanceador de carga HTTP(S) externo global (versão clássica).

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. Observe que esse comando apenas testa a configuração fornecida. Independentemente de os testes serem aprovados ou reprovados, nenhuma alteração é salva no mapa de URL que está implantado atualmente, o que difere dos outros comandos de mapas de URL (edit, import), que também executam os mesmos testes, mas salvarão a nova configuração se os testes forem aprovados. Use o comando validate quando quiser testar uma nova configuração de roteamento sem fazer alterações no mapa de URL implantado atualmente.

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. Não é necessário usar nenhum serviço ativo nem mesmo serviços existentes para os testes. Use qualquer nome de serviço de exemplo para criar e executar os testes. Isso é diferente de outros comandos de mapas de URL (como edit e import) em que o mapa de URL precisa referenciar serviços pré-existentes (mas não necessariamente ativos).

Console

Não é possível usar o Console do 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:

gcloud compute url-maps validate --source PATH_TO_URL_MAP_CONFIG_FILE

• 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 HTTP(S) 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. Observe que esta etapa também implantará o mapa de URL com a nova configuração.

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

Testar um mapa de URL

Observação: 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.

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

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 Cloud:

1. Acesse a página Balanceamento de carga.

   Acessar a página "Balanceamento de carga"

2. Clique no Nome de um balanceador de carga.
3. Na tela Detalhes do balanceador de carga, clique em Editar no balanceador de carga selecionado.
4. Clique em Regras de host e caminho.
5. Na tela Regras de host e caminho, clique em Mostrar testes de configuração.
6. Clique em Adicionar teste de configuração. Adicione os seguintes URLs de teste e back-ends:
   • URL de teste example.com e back-end www-service.
   • URL de teste example.net e back-end www-service.
   • URL de teste example.net/web e back-end www-service.
   • URL de teste example.com/videos e back-end video-service.
   • URL de teste example.com/videos/browse e back-end video-service.
   • URL de teste example.net/static e back-end static-service.
   • URL de teste example.net/static/images e back-end static-service.
7. Procure a marca de seleção azul à esquerda de Regras de host e caminho e clique no botão Atualizar.

gcloud

Para adicionar testes ao seu mapa de URL usando a ferramenta de linha de comando gcloud, 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 HTTP(S) externos, seus testes precisam usar o formato a seguir:

  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

Para balanceadores de carga HTTP(S) externos regionais e internos, os URLs de serviço precisam apontar para serviços de back-end regionais. Exemplo:

https://www.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/backendServices//www-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 Cloud.

gcloud

Para exibir uma lista de mapas de URL usando a ferramenta de linha de comando gcloud, 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 a página "Balanceamento de carga"

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

gcloud

Para acessar informações sobre apenas um mapa de URL usando a ferramenta de linha de comando gcloud, 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 a página "Balanceamento de carga"

2. Clique no Nome de um balanceador de carga.
3. Na tela Detalhes do balanceador de carga, clique em Editar no balanceador de carga selecionado.
4. Na tela Detalhes do balanceador de carga, veja 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 URL usando a ferramenta de linha de comando gcloud, 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 a página "Balanceamento de carga"

2. Clique no Nome de um balanceador de carga.
3. Na tela 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 tela Regras de host e caminho, acesse a página de Balanceamento de carga.

   Acessar a página "Balanceamento de carga"

2. Clique no Nome de um balanceador de carga.
3. Na tela 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

A seguir

• Saiba mais sobre como os mapas de URL funcionam em Visão geral dos mapas de URL.
• Saiba mais sobre como os mapas de URL funcionam no balanceamento de carga HTTP(S) externo em Visão geral do balanceamento de carga de HTTP(S) externo.
• Saiba mais sobre como os mapas de URL funcionam no balanceamento de carga de HTTP(S) interno em Visão geral do balanceamento de carga HTTP(S) interno.