Configurar uma extensão de rota

Com as extensões de serviço, os balanceadores de carga de aplicativo compatíveis podem usar plug-ins ou enviar chamadas para serviços de back-end e inserir processamento personalizado no caminho de processamento. As extensões de rota são executadas no caminho de processamento de solicitações quando o balanceador de carga recebe cabeçalhos de solicitação e antes de avaliar o mapa de URL. Nesta página, descrevemos como configurar extensões de rota.

Para uma visão geral das extensões do balanceador de carga de aplicativo, consulte Visão geral das extensões do Cloud Load Balancing.

Uma extensão de rota para um balanceador de carga de aplicativo aponta para os seguintes recursos:

  • Uma regra de encaminhamento para anexar
  • Um plug-in ou um serviço de back-end de destaque cujos back-ends executam a API gRPC ext_proc.

Uma extensão de rota agrupa serviços de extensão relacionados em uma cadeia. É possível configurar plug-ins e indicadores na mesma cadeia de extensão. A cadeia de extensões seleciona o tráfego em que vai agir usando condições de correspondência da Common Expression Language (CEL). O balanceador de carga avalia uma solicitação em relação às condições de correspondência de uma cadeia de maneira sequencial. Quando uma solicitação corresponde às condições definidas por uma cadeia, todas as extensões na cadeia agem na solicitação. Apenas uma cadeia corresponde a uma determinada solicitação.

A extensão faz referência à regra de encaminhamento do balanceador de carga a ser anexada. Depois de configurar o recurso, o balanceador de carga começa a enviar solicitações correspondentes aos serviços de extensão.

Para informações sobre os limites relacionados às extensões do balanceador de carga de aplicativo, consulte a página Cotas e limites.

Configurar usando plug-ins

Esta seção usa um exemplo para mostrar como configurar uma extensão de rota usando um plug-in que reescreve o cabeçalho de solicitação :host para service-extensions.com quando o caminho corresponde a /extensions. O host anterior e o recém-configurado são mapeados para serviços de back-end em regiões diferentes, o que demonstra o comportamento de roteamento.

Todos os recursos de extensão que fazem referência a um determinado plug-in precisam ser do mesmo tipo. As extensões também precisam ter o mesmo esquema de balanceamento de carga. Não é possível configurar extensões do Cloud Load Balancing com plug-ins já usados em extensões do Media CDN.

Antes de começar

  1. Crie um plug-in que contenha seu código personalizado.

  2. Crie e configure um balanceador de carga de aplicativo que ofereça suporte a plug-ins de extensão de rota.

    Siga as instruções na página Configurar um balanceador de carga de aplicativo interno entre regiões com back-ends de grupo de instâncias de VM para todas as etapas, exceto as seguintes:

    • Nomeie o serviço de back-end como service-one.
    • Aponte service-one para uma instância de máquina virtual (VM) na região A.
    • Aponte gl7-gilb-url-map para service-one por padrão.

  3. Configure um serviço de back-end adicional, service-two, e direcione-o para uma VM na região B.

  4. Adicione ao mapa de URL uma correspondência de caminho que direcione para service-two. Use o comando gcloud compute url-maps add-path-matcher com os seguintes valores de exemplo:

      gcloud compute url-maps add-path-matcher gl7-gilb-url-map \
      --path-matcher-name=rewrite-host \
      --default-service=service-two \
      --new-hosts=service-extensions.com \
      --location=global

  5. Configure uma maneira de enviar solicitações de teste ao seu serviço (por exemplo, executando curl). Se você estiver usando um balanceador de carga interno, crie uma VM de cliente para teste.

Configurar uma extensão de rota usando um plug-in

  1. Verifique o comportamento antes de configurar uma extensão.

    1. Verifique se uma solicitação sem um caminho explícito vai para a região A:

      curl FORWARDING_RULE_IP

      Substitua FORWARDING_RULE_IP pelo endereço IP da regra de encaminhamento. Para encontrar o endereço IP, use o comando gcloud compute forwarding-rules describe.

      A saída é semelhante a esta e indica que a página é servida de uma VM em region A:

      Page served from region-A-vm

    2. Verifique se não há correspondência para /extensions no mapa de URL:

      curl FORWARDING_RULE_IP/extensions

      Substitua FORWARDING_RULE_IP pelo endereço IP da regra de encaminhamento. Para encontrar o endereço IP, use o comando gcloud compute forwarding-rules describe.

      A saída indica que não há correspondência para /extensions no mapa de URL. O resultado será o seguinte:

      <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
<html><head>
<title>404 Not Found</title>
</head><body>
...

  2. Configure a extensão de rota.

    Console

    1. No console do Google Cloud , acesse a página Extensões de serviço.

      Acessar Extensões de serviço

    2. Clique em Criar extensão.

      Um assistente vai abrir para orientar você nas etapas iniciais.

    3. Para o produto, selecione Load Balancing. Em seguida, clique em Continuar.

      Uma lista de balanceadores de carga de aplicativo compatíveis aparece.

    4. Para o tipo de balanceador de carga, selecione "Balanceador de carga de aplicativo interno entre regiões". Depois clique em Continuar.

    5. Para o tipo de extensão, selecione Extensões de rota e clique em Continuar.

    6. Para abrir o formulário Criar extensão, clique em Continuar.

      No formulário Criar extensão, observe que as seleções anteriores, que aparecem na parte de cima da página, não podem ser editadas.

    7. Na seção Noções básicas, faça o seguinte:

      1. Especifique um nome exclusivo para a extensão.

        O nome precisa começar com uma letra minúscula seguida por até 62 letras minúsculas, números ou hifens e não pode terminar com um hífen.

      2. Opcional: insira uma breve descrição sobre a extensão usando no máximo 1.024 caracteres.

      3. Opcional: na seção Rótulos, clique em Adicionar rótulo. Em seguida, na linha que aparece, faça o seguinte:

        • Em Chave, insira um nome de chave.
        • Em Valor, insira um valor para a chave.

        Para adicionar mais pares de chave-valor, clique em Adicionar rótulo. É possível adicionar no máximo 64 pares de chave-valor.

        Para mais informações sobre rótulos, consulte Criar e atualizar rótulos para projetos.

    8. Em Regras de encaminhamento, selecione uma ou mais regras para associar à extensão, por exemplo, cr-ilb-forwarding-rule.

      As regras de encaminhamento já associadas a outra extensão não podem ser selecionadas e aparecem desativadas.

    9. Para Cadeias de extensão, adicione uma ou mais cadeias de extensão para executar em uma solicitação correspondente.

      Para adicionar uma cadeia de extensões, faça o seguinte e clique em Concluído:

      • Em Nova cadeia de extensão, especifique um nome exclusivo.

        O nome precisa estar em conformidade com a RFC-1034, usar apenas letras minúsculas, números e hifens e ter um comprimento máximo de 63 caracteres. Além disso, o primeiro caractere precisa ser uma letra, e o último, uma letra ou um número.

      • Para corresponder a solicitações em que a cadeia de extensão é executada, em Condição de correspondência, especifique uma expressão da Common Expression Language (CEL), por exemplo, request.path.startsWith("/extensions").

        Para mais informações sobre expressões CEL, clique em Receber ajuda com a sintaxe ou consulte a referência da linguagem de correspondência da CEL.

      • Adicione uma extensão para executar uma solicitação correspondente. Para extensões de rota, é possível especificar apenas uma extensão.

        Em Extensões, faça o seguinte e clique em Concluído:

        • Em Tipo de programação, selecione Plug-ins.

        • Em Nome da extensão, especifique um nome exclusivo.

          O nome precisa estar em conformidade com a RFC-1034, usar apenas letras minúsculas, números e hifens e ter um comprimento máximo de 63 caracteres. Além disso, o primeiro caractere precisa ser uma letra e o último, uma letra ou um número.

        • Em Plug-in, selecione um plug-in criado usando as extensões de serviço para o mesmo produto e tipo de extensão.

        • Em Encaminhar cabeçalhos, clique em Adicionar cabeçalho e adicione cabeçalhos HTTP para encaminhar à extensão (do cliente ou do back-end). Se um cabeçalho não for especificado, todos os cabeçalhos serão enviados.

        • Opcional: se a extensão atingir o tempo limite ou falhar e você quiser que o processamento de solicitações ou respostas continue, selecione Ativado em Falha aberta.

          Por padrão, a opção Falha ao abrir não está selecionada. Nesse caso, quando ocorre um erro, o processamento da solicitação ou da resposta é interrompido. Se os cabeçalhos de resposta não tiverem sido entregues ao cliente downstream, um código de status HTTP 500 genérico será retornado ao cliente. Se os cabeçalhos de resposta tiverem sido entregues, o fluxo HTTP para o cliente será redefinido.

          A opção padrão de manter Falha aberta desmarcada é preferível ao priorizar a segurança ou a integridade. Ativar a opção Falha aberta, principalmente para operações não críticas, ajuda a priorizar a disponibilidade.

    10. Clique em Criar extensão.

    gcloud

    1. Defina o plug-in em um arquivo YAML e associe-o a uma regra de encaminhamento global. Por exemplo, cr-ilb-forwarding-rule.

      cat >route-plugin.yaml <<EOF
    name: route-ext
    forwardingRules:
    - https://www.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/forwardingRules/cr-ilb-forwarding-rule
    loadBalancingScheme: INTERNAL_MANAGED
    extensionChains:
    - name: "chain1"
      matchCondition:
        celExpression: 'request.path.startsWith("/extensions")'
      extensions:
      - name: 'ext1'
        service: projects/PROJECT_ID/locations/LOCATION/wasmPlugins/WASM_PLUGIN
        failOpen: false
        supportedEvents:
        - REQUEST_HEADERS
EOF

      Substitua:

      • O ID do projeto.PROJECT_ID
      • REGION: a região da regra de encaminhamento. O valor precisa corresponder ao especificado para o local do plug-in.
      • LOCATION: o local do plug-in como global ou uma região.
      • WASM_PLUGIN: o ID ou o nome totalmente qualificado do plug-in.

    2. Importe a extensão de rota. Use o comando gcloud service-extensions lb-route-extensions import com os seguintes valores de exemplo.

      gcloud service-extensions lb-route-extensions import route-ext \
    --source=route-plugin.yaml \
    --location=global

    Depois que uma extensão de rota é criada, leva um tempo para o novo plug-in ser distribuído em todos os locais. O tempo pode variar entre os locais porque o plug-in não é entregue a todos os locais simultaneamente.

  3. Para verificar se a extensão de rota funciona conforme o esperado, use o mesmo comando curl:

    curl FORWARDING_RULE_IP/extensions

    A saída é semelhante a esta e indica que a página é servida de uma VM em region B:

    Page served from region-B-vm

    Para verificar se o plug-in é executado apenas para solicitações com o prefixo de caminho /extension, repita o comando curl sem um caminho.

    curl FORWARDING_RULE_IP

    O resultado será o seguinte:

    Page served from region-A-vm

Configurar usando frases de destaque

Nesta seção, mostramos como configurar uma extensão de rota usando uma callout.

Antes de começar

Crie os recursos necessários, conforme descrito em Configurar um serviço de back-end de callout.

Configurar uma extensão de rota usando uma frase de destaque

O exemplo a seguir mostra como configurar uma extensão de rota para chamar quando o caminho corresponder a /extensions. O servidor de destaque de rota em callout-vm muda o cabeçalho Host para service-extensions.com, define o caminho como / e envia uma instrução ao balanceador de carga para recalcular a rota. O tráfego flui para l7-ilb-backend-service2 em vez de l7-ilb-backend-service.

  1. Verifique se há uma correspondência para /extensions no mapa de URL.

    1. Execute o seguinte comando curl na regra de encaminhamento da VM do cliente:

      curl FORWARDING_RULE_IP/extensions

      Substitua FORWARDING_RULE_IP pelo endereço IP da regra de encaminhamento. Para encontrar o endereço IP, use o comando gcloud compute forwarding-rules describe.

      A saída indica que não há correspondência para /extensions no mapa de URL. O resultado será o seguinte:

      <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
<html><head>
<title>404 Not Found</title>
</head><body>
...

  2. Configure a extensão de rota.

    Console

    1. No console do Google Cloud , acesse a página Extensões de serviço.

      Acessar Extensões de serviço

    2. Clique em Criar extensão.

      Um assistente vai abrir para orientar você nas etapas iniciais.

    3. Para o produto, selecione Load Balancing. Em seguida, clique em Continuar.

      Uma lista de balanceadores de carga de aplicativo compatíveis aparece.

    4. Selecione um tipo de balanceador de carga. Para balanceadores de carga regionais, especifique também a região. Clique em Continuar.

    5. Para o tipo de extensão, selecione Extensões de rota e clique em Continuar.

    6. Para abrir o formulário Criar extensão, clique em Continuar.

      No formulário Criar extensão, observe que as seleções anteriores, que aparecem na parte de cima da página, não podem ser editadas.

    7. Na seção Noções básicas, faça o seguinte:

      1. Especifique um nome exclusivo para a extensão.

        O nome precisa começar com uma letra minúscula seguida por até 62 letras minúsculas, números ou hifens e não pode terminar com um hífen.

      2. Opcional: insira uma breve descrição sobre a extensão usando no máximo 1.024 caracteres.

      3. Opcional: na seção Rótulos, clique em Adicionar rótulo. Em seguida, na linha que aparece, faça o seguinte:

        • Em Chave, insira um nome de chave.
        • Em Valor, insira um valor para a chave.

        Para adicionar mais pares de chave-valor, clique em Adicionar rótulo. É possível adicionar no máximo 64 pares de chave-valor.

        Para mais informações sobre rótulos, consulte Criar e atualizar rótulos para projetos.

    8. Em Regras de encaminhamento, selecione uma ou mais regras para associar à extensão, por exemplo, l7-ilb-forwarding-rule.

      As regras de encaminhamento já associadas a outra extensão não podem ser selecionadas e aparecem desativadas.

    9. Para Cadeias de extensão, adicione uma ou mais cadeias de extensão para executar em uma solicitação correspondente.

      Para adicionar uma cadeia de extensões, faça o seguinte e clique em Concluído.

      • Em Nova cadeia de extensão, especifique um nome exclusivo.

        O nome precisa estar em conformidade com a RFC-1034, usar apenas letras minúsculas, números e hifens e ter um comprimento máximo de 63 caracteres. Além disso, o primeiro caractere precisa ser uma letra, e o último, uma letra ou um número.

      • Para corresponder a solicitações em que a cadeia de extensão é executada, em Condição de correspondência, especifique uma expressão da Common Expression Language (CEL), por exemplo, request.path.startsWith("/extensions").

        Para mais informações sobre expressões CEL, clique em Receber ajuda com a sintaxe ou consulte a referência da linguagem de correspondência da CEL.

      • Adicione uma extensão para executar uma solicitação correspondente. Para extensões de rota, é possível especificar apenas uma extensão.

        Em Extensões, faça o seguinte e clique em Concluído:

        • Em Tipo de programação, selecione Callouts.

        • Em Nome da extensão, especifique um nome exclusivo.

          O nome precisa estar em conformidade com a RFC-1034, usar apenas letras minúsculas, números e hifens e ter um comprimento máximo de 63 caracteres. Além disso, o primeiro caractere precisa ser uma letra e o último, uma letra ou um número.

        • Para Autoridade, insira o cabeçalho authority da solicitação gRPC enviada do balanceador de carga para o serviço de extensão.

        • Em Serviço de back-end, selecione um serviço de back-end criado seguindo as instruções em Configurar um serviço de back-end de callout.

        • Em Tempo limite, especifique um valor entre 10 e 1.000 milissegundos. Depois disso, uma mensagem no fluxo vai atingir o tempo limite enquanto o balanceador de carga ainda aguarda uma resposta do serviço ext_proc.

        • Em Encaminhar cabeçalhos, clique em Adicionar cabeçalho e adicione cabeçalhos HTTP para encaminhar à extensão (do cliente ou do back-end). Se um cabeçalho não for especificado, todos os cabeçalhos serão enviados.

        • Opcional: se a extensão atingir o tempo limite ou falhar e você quiser que o processamento de solicitações ou respostas continue, selecione Ativado em Falha aberta. As extensões subsequentes na cadeia também são executadas.

          Por padrão, a opção Falha ao abrir não está selecionada. Nesse caso, quando ocorre um erro, o processamento da solicitação ou da resposta é interrompido. Se os cabeçalhos de resposta não tiverem sido entregues ao cliente downstream, um código de status HTTP 500 genérico será retornado ao cliente. Se os cabeçalhos de resposta tiverem sido entregues, o fluxo HTTP para o cliente será redefinido.

          A opção padrão de manter Falha aberta desmarcada é preferível ao priorizar a segurança ou a integridade. Ativar a opção Falha aberta, principalmente para operações não críticas, ajuda a priorizar a disponibilidade.

        • Em Metadados, clique em Adicionar metadados e especifique valores de amostra conforme sugerido. Em Chave, especifique key e em Valor, especifique value.

          Clique em Adicionar metadados para adicionar outro par de chave-valor. Em Chave, especifique fr e em Valor, especifique forwarding_rule_id.

          O campo Metadados permite transmitir informações adicionais do balanceador de carga para o servidor de extensão. Os metadados são enviados em uma mensagem ProcessingRequest e codificados como protobuf.Struct. Qualquer texto nos metadados que corresponda ao ID da regra de encaminhamento especificada será substituído pelo URL do recurso totalmente qualificado da regra de encaminhamento associada à solicitação do cliente.

          O tamanho total dos metadados precisa ser inferior a 1 KiB. O número total de chaves nos metadados precisa ser menor que 16. O comprimento de cada chave precisa ser menor que 64 caracteres. O tamanho de cada valor precisa ser menor que 1.024 caracteres. Todos os valores precisam ser strings.

    10. Clique em Criar extensão.

    gcloud

    1. Defina o destaque em um arquivo YAML e associe-o à regra de encaminhamento. Use os valores de amostra fornecidos.

      cat >route.yaml <<EOF
    name: route-ext
    forwardingRules:
    - https://www.googleapis.com/compute/v1/projects/PROJECT_ID/regions/us-west1/forwardingRules/l7-ilb-forwarding-rule
    loadBalancingScheme: INTERNAL_MANAGED
    extensionChains:
    - name: "chain1"
      matchCondition:
        celExpression: 'request.path.startsWith("/extensions")'
      extensions:
      - name: 'ext11'
        authority: ext11.com
        service: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/regions/us-west1/backendServices/l7-ilb-callout-service
        failOpen: false
        timeout: 0.1s
        metadata:
          "key": "value"
          "fr": "forwarding_rule_id"
EOF

      Substitua PROJECT_ID pelo ID do projeto.

      O campo metadata na configuração da extensão permite transmitir qualquer informação adicional do balanceador de carga para o servidor de extensão. Os metadados são enviados em uma mensagem ProcessingRequest e codificados como protobuf.Struct. Qualquer texto nos metadados que corresponda ao ID da regra de encaminhamento especificada é substituído pelo URL do recurso totalmente qualificado da regra de encaminhamento associada à solicitação do cliente.

      O tamanho total de metadata precisa ser menor que 1 KiB. O número total de chaves nos metadados precisa ser menor que 16. O comprimento de cada chave precisa ser menor que 64 caracteres. O tamanho de cada valor precisa ser menor que 1.024 caracteres. Todos os valores precisam ser strings.

    2. Importe a extensão de rota. Use o comando gcloud service-extensions lb-route-extensions import com os seguintes valores de exemplo.

      gcloud service-extensions lb-route-extensions import route-ext \
    --source=route.yaml \
    --location=us-west1

  3. Verifique se a extensão de rota funciona conforme o esperado. Use o mesmo comando curl:

    curl FORWARDING_RULE_IP/extensions

    A saída indica que o tráfego correspondeu ao host virtual service-extensions.com e chegou ao serviço l7-ilb-backend-service2 mesmo que a solicitação original não tenha feito isso. O resultado será assim:

    Page served from second backend service

    Para validar se o callout está segmentando apenas solicitações com o prefixo /extension, repita o comando curl sem o prefixo path.

    curl FORWARDING_RULE_IP

    O resultado será o seguinte:

    Page served from: l7-ilb-backend-example-1c7t

Limitações para extensões de rota

  • As extensões de rota não são compatíveis com o processamento de corpo HTTP.
  • Uma resposta direta da extensão ao cliente não é compatível com extensões de rota. Se o servidor de extensão de rota responder a uma solicitação de processamento com uma resposta que contenha uma resposta direta, o balanceador de carga vai ignorar a resposta de processamento.

Para limitações aplicáveis a todas as extensões, consulte Limitações das extensões.

A seguir