Resposta rápida
O Cloudflare Tunnel vai ativar por padrão a normalização de URLs em novas versões do cloudflared a partir de 8 de fevereiro de 2027. Antes disso, atualize uma réplica de teste para a versão 2026.11.0 ou posterior, ligue a normalização com --disable-path-normalization=false e confirme qual regra de ingress recebe caminhos com barras repetidas, barras invertidas, segmentos . ou .. e parâmetros separados por ponto e vírgula.
A mudança só afeta o caminho usado pelo cloudflared para escolher a regra de ingress quando essa regra exige validação do Cloudflare Access. O caminho original continua sendo enviado à origem. Configurações sem regras que exigem validação do Access não são afetadas por essa alteração, segundo a Cloudflare.
O que mudou em 12 de novembro de 2026
A versão 2026.10.0 introduziu a opção de normalizar caminhos antes do matching de ingress. A versão 2026.11.0 estendeu o tratamento para parâmetros de caminho delimitados por ponto e vírgula. A data planejada para ativação padrão em novas versões foi alterada de 25 de janeiro para 8 de fevereiro de 2027, criando uma janela maior de teste.
Com a opção ligada, o matching remove segmentos de ponto conforme a RFC 3986, converte barras invertidas em barras normais, combina barras repetidas e, desde 2026.11.0, desconsidera os parâmetros delimitados por ponto e vírgula na escolha da regra. A origem ainda recebe o caminho como chegou ao cloudflared; a função não reescreve a URL entregue à aplicação.
Quem precisa agir agora
Priorize túneis que usam regras com path, várias origens no mesmo hostname e originRequest.access.required igual a true. Também revise expressões regulares que esperam ponto e vírgula no caminho ou dependem de formas alternativas como /api//v1, /api/../admin ou barras invertidas para cair em uma regra específica.
Se o túnel só encaminha um hostname para uma única origem, não usa matching por caminho ou não exige validação do Access no cloudflared, o comunicado não indica mudança de comportamento. Mesmo assim, registre a versão e a configuração atual antes de atualizar para não confundir esta mudança com um problema de certificado, DNS, origem ou conectividade do conector.
- Liste as réplicas e registre a saída de cloudflared version.
- Procure regras ingress com path e blocos originRequest que exigem Access.
- Identifique aplicações que usam ponto e vírgula, barras repetidas, barras invertidas ou segmentos de ponto em URLs válidas.
- Mapeie a regra e a origem esperadas para cada caminho de teste.
Como testar sem alterar todas as réplicas
Comece em homologação ou em uma réplica isolada. Instale cloudflared 2026.11.0 ou posterior pelo mesmo método usado atualmente e reinicie apenas essa instância. Atualizações do serviço podem interromper o tráfego atendido pela réplica; a documentação recomenda múltiplas instâncias ou Load Balancer quando o ambiente exige atualização sem indisponibilidade.
Ligue a normalização passando --disable-path-normalization=false antes do comando run. Em ambientes administrados por variável, use TUNNEL_DISABLE_PATH_NORMALIZATION=false e reinicie a réplica. O nome parece invertido porque a opção controla a desativação: false significa que a normalização fica ativa.
- Valide a sintaxe atual com cloudflared tunnel ingress validate.
- Use cloudflared tunnel ingress rule com URLs representativas para documentar a regra escolhida antes da mudança.
- Inicie uma réplica com cloudflared tunnel --disable-path-normalization=false run <NOME-OU-UUID>.
- Envie requisições de teste sem dados sensíveis e compare status, regra, origem e logs com o baseline.
- Repita o teste com caminhos que incluam as formas normalizadas e confirme que a aplicação recebe o caminho original.
Cenários que precisam entrar na matriz de teste
Não teste apenas a URL comum. Para cada regra baseada em path, inclua o caminho canônico e variações com barras repetidas, segmentos . e .., barra invertida e parâmetros de caminho com ponto e vírgula. Use apenas rotas e sistemas que você administra; não transforme o procedimento em teste contra serviços de terceiros.
Uma mudança de regra não significa necessariamente falha. O objetivo da normalização é tornar a escolha compatível com a forma canônica antes da validação do Access. O resultado esperado deve ser definido pela política de segurança: a requisição precisa cair na regra protegida correta, e não apenas retornar qualquer resposta 200.
- Caminho canônico: confirme a regra e a origem normalmente esperadas.
- Barras repetidas: verifique se a forma consolidada seleciona a mesma regra protegida.
- Segmentos . e ..: confirme o destino após a resolução canônica.
- Barra invertida: confirme o matching como barra normal sem assumir que a origem reescreveu o caminho.
- Parâmetro com ponto e vírgula: valide o comportamento específico da versão 2026.11.0.
Como interpretar 401, 403, 404 e origem errada
Um 401 ou 403 pode indicar que a requisição passou a alcançar uma regra que exige Access, mas a credencial, o JWT ou a política não autorizou o acesso. Um 404 pode vir da regra catch-all ou da própria aplicação, já que o caminho original continua chegando à origem. Compare o hostname, a regra identificada, o serviço de destino e os headers seguros antes de concluir a causa.
Se a URL funciona sem normalização e muda de destino com a opção ligada, revise a ordem e as expressões regulares das regras. O cloudflared avalia ingress de cima para baixo e usa a primeira correspondência. Toda configuração local precisa terminar com uma regra catch-all, por isso um teste também deve confirmar que caminhos não previstos não caem silenciosamente em uma origem permissiva.
Rollback e implantação gradual
Se uma rota legítima cair na regra errada durante o teste, volte a opção para --disable-path-normalization=true ou defina TUNNEL_DISABLE_PATH_NORMALIZATION=true e reinicie a réplica. Esse rollback recupera o comportamento de matching anterior enquanto você corrige as regras; ele não altera o caminho que a aplicação recebe.
Depois da homologação, avance uma réplica por vez, acompanhe erros e latência e mantenha capacidade suficiente nas instâncias restantes. Não misture versões e flags sem inventário: réplicas com comportamentos diferentes podem produzir falhas intermitentes difíceis de reproduzir. Conclua a migração antes de 8 de fevereiro de 2027 para não depender do valor padrão de uma versão futura.
- Aplique a flag em uma réplica e monitore os caminhos prioritários.
- Compare decisões de ingress e respostas da origem com o baseline.
- Corrija expressões e a ordem das regras, mantendo a regra catch-all no final.
- Expanda para as demais réplicas somente depois dos testes funcionais e de segurança.
- Documente explicitamente o valor da flag para não depender do padrão da versão instalada.
Limitações e próxima ação útil
Este guia foi verificado em 13 de novembro de 2026. A data de 8 de fevereiro de 2027 se refere à ativação padrão em novas versões do cloudflared, não a uma alteração instantânea em todas as instalações existentes. A Cloudflare pode ajustar o cronograma ou os detalhes, e a documentação não substitui testes com as regras reais do seu ambiente.
A próxima ação é executar cloudflared version em cada réplica, localizar regras com path e Access e montar uma matriz curta com o caminho canônico e as quatro variações normalizadas. Faça o primeiro teste em homologação com 2026.11.0 ou posterior, confirme a origem correta e registre um rollback antes de tocar a produção.
Faça o próximo teste
Fontes consultadas
Os links abaixo servem para conferir conceitos, orientações oficiais e o critério editorial usado neste conteúdo.
- Cloudflare Tunnel extends URL normalizationCloudflare Changelog
- Configuration file and ingress matchingCloudflare Docs
- Tunnel run parametersCloudflare Docs
- Origin parameters and Access validationCloudflare Docs
- Update cloudflaredCloudflare Docs
- Cloudflare StatusCloudflare