API Gateway:Perguntas frequentes

O Cloud-native API Gateway suporta IPv6?

Sim.

O Cloud-native API Gateway suporta o header de requisição x-forwarded-for?

Sim.

Se uma requisição já incluir o header x-forwarded-for, o gateway anexa o endereço IP do salto anterior. Caso contrário, o gateway adiciona o header com esse endereço IP.

Resolução de erros "upstream connect error or disconnect/reset header"

Esse erro indica que o grupo de segurança do service de backend está bloqueando o acesso da instância do gateway.

Para resolver, acesse a página OverviewOverview da sua instância do gateway, clique na aba Security Group Authorizations e, em seguida, clique em Add Security Group Rule para adicionar uma configuração de grupo de segurança. O gateway encaminha requisições diretamente para o endereço IP do Pod no ACK, portanto, é necessário abrir a porta usada pelo pod na regra do grupo de segurança.

Uso de um header para corresponder a um nome de domínio

Adicione uma regra de correspondência de header de requisição ao criar uma rota.

Defina o nome do campo do header como :authority e o valor do header como o nome de domínio específico.

Resolução de falhas de requisição devido a corpo grande

Esse problema ocorre porque o buffer de conexão do gateway é muito pequeno. Aumente o tamanho do buffer:

• Para HTTP/1.x: ajuste o parâmetro DownstreamConnectionBufferLimits no console.

• Para HTTP/2: ajuste os parâmetros DownstreamConnectionBufferLimits e InitialStreamWindowSize no console.

Limites na adição de sources de service

• Uma única instância de gateway pode ser associada a até três clusters ACK.

• Uma única instância de gateway pode ser associada a apenas uma instância Nacos.

Impossibilidade de selecionar uma source de service Nacos ou ACK existente

O Cloud-native API Gateway só pode adicionar instâncias Nacos ou clusters ACK que estejam na mesma VPC.

O Cloud-native API Gateway suporta certificados HTTPS personalizados?

O Cloud-native API Gateway não hospeda certificados diretamente. Em vez disso, ele os obtém do Certificate Management ServiceCertificate Management Service da Alibaba Cloud. Carregue seu certificado no Certificate Management Service e configure-o para o nome de domínio no gateway.

Efeitos da alteração de parâmetros no tráfego existente

• Alterações em XffTrustedNum exigem reinicialização do gateway para entrar em vigor.

• Alterações em UpstreamIdleTimeout causam desconexão e reconexão das conexões upstream.

• Alterações em DownstreamIdleTime causam desconexão e reconexão das conexões downstream.

Status anormal de verificação de integridade para um service de backend

Um status anormal de verificação de integridade pode ter várias causas:

• Para um service privado dentro de uma VPC, verifique se o grupo de segurança do service de backend permite que o gateway acesse a porta necessária. Para mais informações, consulte {{XREF_0}}.

• Para um service voltado ao público, verifique se a VPC tem acesso à Internet. Utilize o recurso SNAT de um NAT gateway de Internet para acessar a Internet. Para mais informações, consulte {{XREF_1}}.

• Em verificações de integridade baseadas em HTTP, garanta que o caminho da requisição e o domínio da requisição estejam configurados corretamente.

• Nas verificações de integridade via HTTP, caso o endpoint de health check do service de backend exija acesso por HTTPS, defina a política do service como modo TLS em Policy Configuration.

• Se todas as configurações acima estiverem corretas em verificações HTTP, o problema pode ser a coincidência entre o intervalo de verificação de integridade e o tempo de keep-alive da conexão do service de backend. Tente aumentar o intervalo de verificação de integridade.

Identificação da causa de um erro de requisição

• Verifique se o header de resposta contém x-envoy-upstream-service-time. Se contiver, o gateway já encaminhou a requisição para o service de backend. É provável que o erro tenha origem no service de backend.

• Confira se o campo upstream_service_time no log de acesso do gateway está vazio. Se não estiver vazio, o gateway já encaminhou a requisição para o service de backend. O erro provavelmente se origina no service de backend.

Certificado HTTPS atualizado não entra em vigor

Geralmente, esse problema ocorre quando um certificado HTTPS também está configurado em um service upstream do gateway, como CLB, DCDN, WAF ou Anti-DDoS Proxy. Verifique se o certificado no service upstream também foi atualizado. Como prática recomendada, configure certificados HTTPS em apenas um local. Se houver DCDN ou WAF implantado no upstream, configure HTTPS apenas no DCDN ou WAF e use HTTP para requisições back-to-origin ao gateway.

Priorização de rotas

Na página Route Settings de uma instância de gateway, a ordem das rotas na lista representa sua prioridade de correspondência, da maior para a menor. A prioridade é determinada pelo domínio e pelas regras de rota. A prioridade de correspondência de domínio é exact domain name > wildcard domain name. Por exemplo, test.example.com tem prioridade maior que *.example.com. Para o mesmo domínio, a prioridade de correspondência de caminho é Exact Match>Prefix Match>Match Regular Expression. Para o mesmo domínio e caminho, regras com more matching conditions têm prioridade maior do que aquelas com fewer matching conditions (as condições de correspondência incluem parâmetros Header e Query).

Falhas em requisições HTTPS com DCDN

Normalmente, essa falha acontece porque o DCDN não inclui Server Name Indication (SNI) nas requisições back-to-origin para o gateway. Para resolver, configure o SNI back-to-origin nas configurações do seu DCDN.

Falhas em requisições HTTPS com WAF

Essa questão geralmente surge porque o WAF não inclui Server Name Indication (SNI) nas requisições back-to-origin para o gateway. Se você estiver usando o modo de acesso CNAME no WAF, modifique as configurações do domínio correspondente. Na etapa Enter Your Website Information, selecione Enable Origin SNI.

O Cloud-native API Gateway suporta WebSocket?

Sim, há suporte a WebSocket e ele vem ativado por padrão.

O Cloud-native API Gateway suporta gRPC?

Sim. O gRPC utiliza o protocolo HTTP/2 para transporte. Garanta que EnableHttp2 = true esteja definido na página Parameter Settings do gateway.

O Cloud-native API Gateway suporta descompressão GZIP?

Sim. Certifique-se de que EnableGzip = true esteja definido na página Parameter Settings do gateway. Os algoritmos suportados são Gzip e Brotli, configurados por meio do parâmetro ZipAlgorithm. O padrão é Gzip.

Preservação de maiúsculas e minúsculas nos headers

Sim. Defina PreserveHeaderFormat = true na página Parameter Settings do gateway. Esse parâmetro aplica-se apenas a HTTP/1.0 e HTTP/1.1. A especificação do protocolo HTTP/2 exige que todos os headers de requisição e resposta estejam em letras minúsculas.

O Cloud-native API Gateway suporta HTTP/3?

Sim. Configure EnableHttp3 = true na página Parameter Settings do gateway.

Conversão de headers para letras minúsculas

Por padrão, o gateway converte todos os headers de requisição e resposta para letras minúsculas. Para preservar o formato original, defina PreserveHeaderFormat = true na página Parameter Settings do gateway.

Falhas em requisições para um service de domínio DNS

Se o domínio DNS configurado for público, configure SNAT em um NAT gateway de Internet para habilitar o acesso à internet. Por padrão, uma instância de gateway não acessa a internet.

Recebimento de erro 404 ao usar um nome de domínio DNS como service de backend

Quando um service de backend é acessado por meio de um nome de domínio DNS, o gateway não reescreve o header Host da requisição por padrão. Se o service de backend corresponder rotas com base no header Host, a requisição retornará um erro 404.

Adicione uma política de reescrita HTTP à configuração da rota para reescrever o header Host para o nome de domínio real do service de backend. Para mais informações, consulte {{XREF_2}}.

Utilize o campo response_flags no log de acesso do gateway para investigar melhor a causa do erro 404. Para mais detalhes, veja a seção "Recebimento de erro 404" neste tópico.

Informações de rastreamento ausentes no console ARMS

Verifique se o parâmetro EnableGenerateRequestId está definido como true na configuração do gateway. Se estiver definido como false, inclua um header x-request-id compatível nas suas requisições. Caso contrário, o gateway não conseguirá relatar informações de rastreamento.

Recebimento de erro 400

Esse erro geralmente é causado por um dos seguintes motivos:

• O cliente enviou uma requisição com erro de protocolo. Verifique no log de acesso do gateway se há response_flags = DPE.

• O service de backend retornou um erro 400. Consulte o log de acesso do gateway. Se o campo response_flags estiver vazio e o campo upstream_host tiver um valor, isso indica que o service de backend retornou o erro 400. O valor de upstream_host corresponde ao endereço IP do service de backend que recebeu a requisição.

Recebimento de erro 401

As causas mais comuns para esse erro incluem:

• O gateway retornou o erro, indicando credenciais de acesso ausentes. Verifique se você ativou autenticação, autorização ou um plug-in WebAssembly.

• O service de backend retornou um erro 401. Analise o log de acesso do gateway. Quando o campo response_flags estiver vazio e upstream_host possuir valor, significa que o erro 401 veio do service de backend. O valor em upstream_host é o endereço IP do service de backend que recebeu a requisição.

Recebimento de erro 403

Esse erro normalmente resulta de uma das seguintes situações:

• O gateway gerou o erro devido a permissões de acesso insuficientes. Verifique se há alguma lista de bloqueios ou lista de permissões de endereços IP, autenticação, autorização ou plug-in WebAssembly ativado.

• O service de backend devolveu um erro 403. Examine o log de acesso do gateway. Se response_flags estiver vazio e upstream_host apresentar valor, o erro 403 originou-se no service de backend. O valor de upstream_host representa o endereço IP do service de backend destinatário da requisição.

Recebimento de erro 404

Este erro costuma ocorrer pelos motivos abaixo:

• Não há regra de rota correspondente configurada no gateway. Consulte o log de acesso do gateway. Se o log contiver response_flags = NR, nenhuma rota foi encontrada.

• O service de backend retornou um erro 404. Verifique o log de acesso do gateway. Um campo response_flags vazio combinado com um valor presente em upstream_host sinaliza que o próprio service de backend emitiu o erro 404. O valor em upstream_host identifica o endereço IP do service de backend que processou a requisição.

Recebimento de erro 405

Com a proteção WAF ativada, a requisição pode ter acionado uma regra de proteção do WAF. Nesse cenário, o WAF retorna o código de status 405.

Recebimento de erro 413

Geralmente, esse erro decorre de um dos fatores a seguir:

• O tamanho da requisição ultrapassa o limite do buffer de conexão do gateway. Aumente o valor do parâmetro DownstreamConnectionBufferLimits na página Parameter Settings.

• O service de backend respondeu com erro 413. Inspecione o log de acesso do gateway. Caso response_flags esteja vazio e upstream_host contenha dados, confirma-se que o erro 413 partiu do service de backend. O conteúdo de upstream_host mostra o endereço IP do service de backend que recebeu a requisição.

Recebimento de erro 429

Uma regra de limitação do gateway foi acionada. Revise o log de acesso do gateway. Se o log apresentar response_flags = RL, verifique sua regra de limitação do gateway.

Recebimento de erro 502

As razões mais frequentes para esse erro são:

• O service de backend enviou uma resposta com erro de protocolo. Consulte o log de acesso do gateway. Se o log mostrar response_flags = UPE, a causa mais comum é um campo Transfer-Encoding duplicado no header de resposta do service de backend. Verifique seu service de backend.

• O service de backend emitiu um erro 502. Cheque o log de acesso do gateway. Quando response_flags estiver vazio e upstream_host tiver conteúdo, fica evidente que o erro 502 veio do service de backend. O valor de upstream_host aponta o endereço IP do service de backend que recebeu a requisição.

Recebimento de erro 503

Esse erro pode surgir devido aos seguintes motivos:

• O service alvo especificado na regra de rota não possui endereços IP íntegros. Consulte o log de acesso do gateway. Essa condição aparece como response_flags = UH.

• O service de backend encerrou a conexão enquanto o gateway encaminhava a requisição. Verifique o log de acesso do gateway. Isso é sinalizado por response_flags = UC. Frequentemente, ocorre porque o idle timeout de conexão do service de backend é inferior ao valor de UpstreamIdleTimeout do gateway. Reduza o valor de UpstreamIdleTimeout na página Parameter Settings do gateway.

• O gateway não consegue se conectar ao endereço IP do service de backend. Analise o log de acesso do gateway. Tal situação é indicada por response_flags = UF ou response_flags = URX. Muitas vezes, o grupo de segurança do service de backend bloqueia o acesso proveniente do gateway. Confirme se o grupo de segurança do service de backend foi configurado para permitir que o gateway acesse a porta. Para mais informações, consulte {{XREF_3}}.

• O service de backend não existe na configuração do gateway. Consulte o log de acesso do gateway. Essa situação é indicada por response_flags = NC. Isso pode acontecer por vários motivos:

  • O service correspondente deixou de existir.

  • Se o service de backend tiver múltiplas portas, selecione uma porta fixa, e não dinâmica, ao configurar o service alvo na rota.

  • Uma porta fixa foi selecionada para o service de backend, mas a porta do service mudou.

• O service de backend retornou um erro 503. Se o campo response_flags no log estiver vazio e o campo upstream_host não estiver vazio, isso indica que o service de backend retornou o erro 503. O valor de upstream_host é o endereço IP do service de backend que recebeu a requisição.

response_code igual a 0 no log de acesso

Um response_code igual a 0 indica que o cliente não recebeu resposta.

Isso geralmente acontece por dois motivos:

• O cliente fechou a conexão prematuramente, por exemplo, devido a uma rede móvel instável ou resposta lenta do backend. Isso é indicado por response_flags = "DC" no log de acesso.

• Uma requisição HTTPS foi enviada sem Server Name Indication (SNI), e nenhum certificado HTTPS estava configurado para um domínio curinga. SNI é uma extensão TLS que carrega informações do nome de domínio. Isso é indicado por um campo requested_server_name vazio no log de acesso.

Consumo de tráfego público por requisições sem rota correspondente

Sim. Todas as requisições que passam pelo gateway consomem tráfego público, inclusive aquelas que não correspondem a nenhuma rota. O gateway ainda utiliza tráfego para receber a requisição e enviar uma resposta.

Verifique o consumo de tráfego no log de acesso do gateway usando os seguintes campos:

• bytes_received: tamanho do corpo da requisição, representando o tráfego de entrada.

• bytes_sent: tamanho do corpo da resposta, representando o tráfego de saída.

Requisições sem rota correspondente são identificadas no log de acesso pelo valor response_code_details em route_not_found e pelo valor response_flags em NR.

Rastreamento da origem de requisições sem rota correspondente

Após ativar a entrega de logs para o gateway, pesquise requisições sem correspondência no Log Service e utilize os campos de log para identificar o endereço IP de origem. O log de acesso registra todas as requisições, incluindo as falhas. O endereço IP de origem encontra-se no campo downstream_remote_address.

No Log Service, execute a seguinte consulta para filtrar requisições sem correspondência:

response_code_details: "route_not_found"

Nos resultados da consulta, verifique os seguintes campos para identificar a origem da requisição:

• downstream_remote_address: endereço do cliente que se conectou ao gateway.

• x-forwarded-for: campo x-forwarded-for do header de requisição HTTP, que indica o endereço IP de origem original da requisição. Se a requisição passar por proxies, esse campo poderá conter vários endereços IP. O último endereço IP é o endereço do salto anterior ao gateway.

Para calcular o consumo de tráfego dessas requisições anômalas, execute a seguinte consulta no Log Service:

response_code_details: "route_not_found" | SELECT sum(bytes_sent + bytes_received) AS total_bytes

Como adicionar o header Referer do cliente aos logs de requisição do Cloud-native API Gateway?

O header Referer não é registrado nos logs de acesso do gateway por padrão. Para capturá-lo, ative o recurso de entrega de logs e configure uma regra de correspondência de header personalizado no console do gateway para incluir o Referer como um campo de header personalizado na saída do log.

Para mais informações sobre o recurso de entrega de logs, consulte {{XREF_4}}.