Resolução de problemas

Esta página fornece estratégias de resolução de problemas, bem como soluções para alguns erros comuns.

Ao resolver problemas do Knative Serving, confirme primeiro que consegue executar a imagem do contentor localmente.

Se a sua aplicação não estiver a ser executada localmente, tem de diagnosticar e corrigir o problema. Deve usar o Cloud Logging para ajudar a depurar um projeto implementado.

Ao resolver problemas de publicação do Knative, consulte as secções seguintes para ver possíveis soluções para o problema.

Verificar o resultado da linha de comandos

Se usar a Google Cloud CLI, verifique o resultado do comando para ver se foi bem-sucedido ou não. Por exemplo, se a implementação terminar sem êxito, deve ser apresentada uma mensagem de erro a descrever o motivo da falha.

As falhas de implementação devem-se, muito provavelmente, a um manifesto configurado incorretamente ou a um comando incorreto. Por exemplo, o resultado seguinte indica que tem de configurar a percentagem de tráfego da rota para somar 100.

Error from server (InternalError): error when applying patch:</p><pre>{"metadata":{"annotations":{"kubectl.kubernetes.io/last-applied-configuration":"{\"apiVersion\":\"serving.knative.dev/v11\",\"kind\":\"Route\",\"metadata\":{\"annotations\":{},\"name\":\"route-example\",\"namespace\":\"default\"},\"spec\":{\"traffic\":[{\"configurationName\":\"configuration-example\",\"percent\":50}]}}\n"}},"spec":{"traffic":[{"configurationName":"configuration-example","percent":50}]}}
to:
&{0xc421d98240 0xc421e77490 default route-example STDIN 0xc421db0488 264682 false}
for: "STDIN": Internal error occurred: admission webhook "webhook.knative.dev" denied the request: mutation failed: The route must have traffic percent sum equal to 100.
ERROR: Non-zero return code '1' from command: Process exited with status 1

Verificar registos do seu serviço

Pode usar o Cloud Logging ou a página de envio do Knative na Google Cloud consola para verificar os registos de pedidos e os registos de contentores. Para ver os detalhes completos, leia o artigo Registo e visualização de registos.

Se usar o Cloud Logging, o recurso no qual tem de filtrar é o contentor do Kubernetes.

A verificar o estado do serviço

Execute o seguinte comando para obter o estado de um serviço Knative Serving implementado:

gcloud run services describe SERVICE

Pode adicionar --format yaml(status) ou --format json(status) para obter o estado completo, por exemplo:

gcloud run services describe SERVICE --format 'yaml(status)'

As condições em status podem ajudar a localizar a causa da falha. As condições podem incluir True, False ou Unknown:

Para ver detalhes adicionais sobre as condições de estado, consulte o artigo Sinalização de erros do Knative.

A verificar o estado do trajeto

Cada serviço de publicação do Knative gere uma rota que representa o estado de encaminhamento atual em relação às revisões do serviço.

Pode verificar o estado geral da rota consultando o estado do serviço:

gcloud run services describe SERVICE --format 'yaml(status)'

A condição RoutesReady em status fornece o estado do trajeto.

Pode diagnosticar ainda mais o estado do trajeto executando o seguinte comando:

kubectl get route SERVICE -o yaml

As condições em status indicam o motivo de uma falha. Nomeadamente:

  • Pronto indica se o serviço está configurado e tem back-ends disponíveis. Se for true, o trajeto está configurado corretamente.

  • AllTrafficAssigned indica se o serviço está configurado corretamente e tem back-ends disponíveis. Se o status desta condição não for True:

  • IngressReady indica se o Ingress está pronto. Se o status desta condição não for True, experimente verificar o estado de entrada.

  • CertificateProvisioned indica se os certificados do Knative foram aprovisionados. Se a condição status não for True, experimente resolver problemas de TLS gerido.

Para ver detalhes adicionais sobre as condições de estado, consulte o artigo Condições de erro e relatórios do Knative.

A verificar o estado do Ingress

O Knative Serving usa um serviço de balanceador de carga denominado istio-ingressgateway, que é responsável pelo processamento do tráfego recebido de fora do cluster.

Para obter o IP externo do balanceador de carga, execute o seguinte comando:

kubectl get svc istio-ingressgateway -n ASM-INGRESS-NAMESPACE

Substitua ASM-INGRESS-NAMESPACE pelo espaço de nomes onde se encontra a entrada do Cloud Service Mesh. Especifique istio-system se tiver instalado o Cloud Service Mesh com a respetiva configuração predefinida.

O resultado tem um aspeto semelhante ao seguinte:

NAME                   TYPE           CLUSTER-IP     EXTERNAL-IP  PORT(S)
istio-ingressgateway   LoadBalancer   XX.XX.XXX.XX   pending      80:32380/TCP,443:32390/TCP,32400:32400/TCP

em que o valor EXTERNAL-IP é o seu endereço IP externo do LoadBalancer.

Se o EXTERNAL-IP for pending, consulte a secção O EXTERNAL-IP é pending durante muito tempo abaixo.

Verificar o estado da revisão

Para obter a revisão mais recente do seu serviço Knative serving, execute o seguinte comando:

gcloud run services describe SERVICE --format='value(status.latestCreatedRevisionName)'

Execute o seguinte comando para obter o estado de uma revisão de serviço do Knative específica:

gcloud run revisions describe REVISION

Pode adicionar --format yaml(status) ou --format json(status) para ver o estado completo:

gcloud run revisions describe REVISION --format yaml(status)

As condições em status indicam os motivos de uma falha. Nomeadamente:

  • Ready indica se os recursos de tempo de execução estão prontos. Se for true, a revisão está configurada corretamente.
  • ResourcesAvailable indica se os recursos subjacentes do Kubernetes foram aprovisionados. Se o status desta condição não for True, experimente verificar o estado do Pod.
  • ContainerHealthy indica se a verificação de disponibilidade da revisão foi concluída. Se o status desta condição não for True, experimente verificar o estado do Pod.
  • Ativo indica se a revisão está a receber tráfego.

Se alguma destas condições status não for True, experimente verificar o estado do Pod.

A verificar o estado do Pod

Para obter os pods de todas as suas implementações:

kubectl get pods

Isto deve apresentar todos os pods com um breve estado. Por exemplo:

NAME                                                      READY     STATUS             RESTARTS   AGE
configuration-example-00001-deployment-659747ff99-9bvr4   2/2       Running            0          3h
configuration-example-00002-deployment-5f475b7849-gxcht   1/2       CrashLoopBackOff   2          36s

Escolha uma e use o seguinte comando para ver informações detalhadas sobre o respetivo status. Alguns campos úteis são conditions e containerStatuses:

kubectl get pod POD-NAME -o yaml

O EXTERNAL-IP está <pending> há muito tempo

Por vezes, pode não receber um endereço IP externo imediatamente após criar um cluster, mas, em vez disso, ver o IP externo como pending. Por exemplo, pode ver isto invocando o comando:

Para obter o IP externo do balanceador de carga, execute o seguinte comando:

kubectl get svc istio-ingressgateway -n ASM-INGRESS-NAMESPACE

Substitua ASM-INGRESS-NAMESPACE pelo espaço de nomes onde se encontra a entrada do Cloud Service Mesh. Especifique istio-system se tiver instalado o Cloud Service Mesh com a respetiva configuração predefinida.

O resultado tem um aspeto semelhante ao seguinte:

NAME                   TYPE           CLUSTER-IP     EXTERNAL-IP  PORT(S)
istio-ingressgateway   LoadBalancer   XX.XX.XXX.XX   pending      80:32380/TCP,443:32390/TCP,32400:32400/TCP

em que o valor EXTERNAL-IP é o seu endereço IP externo do LoadBalancer.

Isto pode significar que esgotou a quota de endereços IP externos no Google Cloud. Pode verificar a possível causa invocando:

kubectl describe svc istio-ingressgateway -n INGRESS_NAMESPACE
 onde INGRESS_NAMESPACE é o espaço de nomes da entrada do ASM, que, por predefinição, é `istio-system`. Isto gera uma saída semelhante à seguinte: 
Name:                     istio-ingressgateway
Namespace:                INGRESS_NAMESPACE
Labels:                   app=istio-ingressgateway
                          istio=ingressgateway
                          istio.io/rev=asm-1102-3
                          operator.istio.io/component=IngressGateways
                          operator.istio.io/managed=Reconcile
                          operator.istio.io/version=1.10.2-asm.3
                          release=istio
Annotations:              kubectl.kubernetes.io/last-applied-configuration={"apiVersion":"v1","kind":"Service","metadata":{"annotations":{},"labels":{"addonmanager.kubernetes.io/mode":"Reconcile","app":"istio-ingressgateway","...
Selector:                 app=istio-ingressgateway,istio=ingressgateway
Type:                     LoadBalancer
IP:                       10.XX.XXX.XXX
LoadBalancer Ingress:     35.XXX.XXX.188
Port:                     http2  80/TCP
TargetPort:               80/TCP
NodePort:                 http2  31380/TCP
Endpoints:                XX.XX.1.6:80
Port:                     https  443/TCP
TargetPort:               443/TCP
NodePort:                 https  3XXX0/TCP
Endpoints:                XX.XX.1.6:XXX
Port:                     tcp  31400/TCP
TargetPort:               3XX00/TCP
NodePort:                 tcp  3XX00/TCP
Endpoints:                XX.XX.1.6:XXXXX
Port:                     tcp-pilot-grpc-tls  15011/TCP
TargetPort:               15011/TCP
NodePort:                 tcp-pilot-grpc-tls  32201/TCP
Endpoints:                XX.XX.1.6:XXXXX
Port:                     tcp-citadel-grpc-tls  8060/TCP
TargetPort:               8060/TCP
NodePort:                 tcp-citadel-grpc-tls  31187/TCP
Endpoints:                XX.XX.1.6:XXXX
Port:                     tcp-dns-tls  853/TCP
TargetPort:               XXX/TCP
NodePort:                 tcp-dns-tls  31219/TCP
Endpoints:                10.52.1.6:853
Port:                     http2-prometheus  15030/TCP
TargetPort:               XXXXX/TCP
NodePort:                 http2-prometheus  30944/TCP
Endpoints:                10.52.1.6:15030
Port:                     http2-grafana  15031/TCP
TargetPort:               XXXXX/TCP
NodePort:                 http2-grafana  31497/TCP
Endpoints:                XX.XX.1.6:XXXXX
Session Affinity:         None
External Traffic Policy:  Cluster
Events:
  Type    Reason                Age                  From                Message
  ----    ------                ----                 ----                -------
  Normal  EnsuringLoadBalancer  7s (x4318 over 15d)  service-controller  Ensuring load balancer

Se o resultado contiver uma indicação de que a IN_USE_ADDRESSESquota foi excedida, pode pedir quota adicional navegando para a página IAM e administração na Google Cloud consola para pedir quota adicional.

O gateway continua a tentar até ser atribuído um endereço IP externo. Esta ação pode demorar alguns minutos.

Resolução de problemas de domínios personalizados e TLS gerido

Use os passos de resolução de problemas indicados abaixo para resolver problemas gerais relacionados com domínios personalizados e a funcionalidade de certificados TLS geridos.

Domínios personalizados para redes privadas internas

Se mapeou um domínio personalizado para o cluster ou os serviços do Knative Serving numa rede interna privada, tem de desativar os certificados TLS geridos caso contrário, a configuração do domínio não vai atingir o estado ready. Por predefinição, o balanceador de carga interno não consegue comunicar externamente com a autoridade de certificação.

Verifique o estado de um mapeamento de domínio específico

Para verificar o estado de um mapeamento de domínio específico:

  1. Execute o comando:

    gcloud run domain-mappings describe --domain DOMAIN --namespace NAMESPACE

    Substituir

    • DOMAIN com o nome do domínio que está a usar.
    • NAMESPACE com o espaço de nomes que usa para o mapeamento de domínios.

  2. Nos yamlresultados deste comando, examine a condição do campo CertificateProvisioned para determinar a natureza do erro.

  3. Se for apresentado um erro, este deve corresponder a um dos erros nas tabelas abaixo. Siga as sugestões nas tabelas para resolver o problema.

Erros de configuração do utilizador

Código de erro Detalhes
DNSErrored Mensagem: O Registo de DNS não está configurado corretamente. Tem de mapear o domínio [XXX] para o IP XX.XX.XX.XX

Siga as instruções fornecidas para configurar corretamente o seu Registo de DNS.

RateLimitExceeded Mensagem: acme: urn:ietf:params:acme:error:rateLimited: Error creating new order
:: too many certificates already issued for exact set of domains:
test.your-domain.com:
see https://letsencrypt.org/docs/rate-limits/

A quota do Let's Encrypt foi excedida. Tem de aumentar a quota de certificados da Let's Encrypt para esse anfitrião.

InvalidDomainMappingName Mensagem: O nome DomainMapping %s não pode ser igual ao anfitrião do URL da rota %s.

O nome DomainMapping não pode ser exatamente igual ao anfitrião para o qual o mapeamento é feito. Use um domínio diferente para o nome DomainMapping.

ChallengeServingErrored Mensagem: O sistema não conseguiu processar o pedido HTTP01.

Este erro pode ocorrer se o serviço istio-ingressgateway não conseguir publicar o pedido do Let's Encrypt para validar a propriedade do domínio.

  1. Certifique-se de que o seu serviço istio-ingressgateway está acessível a partir da Internet pública sem usar a nuvem privada virtual.
  2. Certifique-se de que o seu serviço istio-ingressgateway aceita pedidos do URL http://DOMAIN/.well-known/acme-challenge/..., em que DOMAIN é o domínio que está a ser validado.

Erros do sistema

Código de erro Detalhes
OrderErrored

AuthzErrored

ChallengeErrored

Estes 3 tipos de erros ocorrem se a validação da propriedade do domínio por parte da Let's Encrypt falhar.

Normalmente, estes erros são erros temporários e o Knative serving tenta novamente.

O atraso de nova tentativa é exponencial, com um mínimo de 8 segundos e um máximo de 8 horas.

Se quiser tentar novamente o erro manualmente, pode eliminar manualmente a encomenda com falha.

kubectl delete order DOMAIN -n NAMESPACE

ACMEAPIFailed Este tipo de erro ocorre quando o Knative serving não consegue chamar o Let's Encrypt. Normalmente, este é um erro temporário e o Knative serving vai tentar novamente.

Se quiser tentar novamente o erro manualmente, elimine manualmente a encomenda com falha.

kubectl delete order DOMAIN -n NAMESPACE

UnknownErrored Este erro indica um erro do sistema desconhecido, que deve ocorrer muito raramente no cluster do GKE. Se vir esta mensagem, contacte o apoio técnico do Google Cloud para receber ajuda na depuração.

Verifique o estado da encomenda

O estado da encomenda regista o processo de interação com o Let's Encrypt e, por isso, pode ser usado para depurar os problemas relacionados com o Let's Encrypt. Se for necessário, verifique o estado da encomenda executando este comando:

kubectl get order DOMAIN -n NAMESPACE -oyaml

Substituir

  • DOMAIN com o nome do domínio que está a usar.
  • NAMESPACE com o espaço de nomes que usa para o mapeamento de domínios.

Os resultados contêm os certificados emitidos e outras informações se a encomenda tiver sido bem-sucedida.

Tempo limite da encomenda

O objeto Order vai expirar após 20 minutos se ainda não conseguir obter certificados.

  1. Verifique o estado do mapeamento de domínios. Para um limite de tempo, procure uma mensagem de erro como esta no resultado do estado:

    order (test.your-domain.com) timed out (20.0 minutes)

  2. Uma causa comum do problema de limite de tempo é o facto de o seu registo de DNS não estar configurado corretamente para mapear o domínio que está a usar para o endereço IP do serviço de entrada. Execute o seguinte comando para verificar o registo DNS:

    host DOMAIN

  3. Verifique o endereço IP externo do balanceador de carga de entrada:

    Para obter o IP externo do balanceador de carga, execute o seguinte comando:

    kubectl get svc istio-ingressgateway -n ASM-INGRESS-NAMESPACE

    Substitua ASM-INGRESS-NAMESPACE pelo espaço de nomes onde se encontra a entrada do Cloud Service Mesh. Especifique istio-system se tiver instalado o Cloud Service Mesh com a respetiva configuração predefinida.

    O resultado tem um aspeto semelhante ao seguinte:

    NAME                   TYPE           CLUSTER-IP     EXTERNAL-IP  PORT(S)
istio-ingressgateway   LoadBalancer   XX.XX.XXX.XX   pending      80:32380/TCP,443:32390/TCP,32400:32400/TCP

    em que o valor EXTERNAL-IP é o seu endereço IP externo do LoadBalancer.

    Se o endereço IP externo do seu domínio não corresponder ao endereço IP de entrada, reconfigure o registo DNS para mapear para o endereço IP correto.

  4. Depois de o registo DNS (atualizado) entrar em vigor, execute o seguinte comando para eliminar o objeto Order de modo a acionar novamente o processo de pedido de um certificado TLS:

    kubectl delete order DOMAIN -n NAMESPACE

    Substituir

    • DOMAIN com o nome do domínio que está a usar.
    • NAMESPACE com o espaço de nomes que usa.

Falhas de autorização

As falhas de autorização podem ocorrer quando um registo de DNS não é propagado globalmente a tempo. Como resultado, o Let's Encrypt não consegue validar a propriedade do domínio.

  1. Verifique o estado da encomenda. Descubra o link de autorização no campo acmeAuthorizations do estado. O URL deve ter o seguinte aspeto:

    https://acme-v02.api.letsencrypt.org/acme/authz-v3/1717011827

  2. Abra o link. Se vir uma mensagem semelhante a: 

    urn:ietf:params:acme:error:dns

    Nesse caso, o problema deve-se à propagação incompleta do DNS.

  3. Para resolver o erro de propagação de DNS:

    1. Verifique o endereço IP externo do balanceador de carga de entrada:

      Para obter o IP externo do balanceador de carga, execute o seguinte comando:

      kubectl get svc istio-ingressgateway -n ASM-INGRESS-NAMESPACE

      Substitua ASM-INGRESS-NAMESPACE pelo espaço de nomes onde se encontra a entrada do Cloud Service Mesh. Especifique istio-system se tiver instalado o Cloud Service Mesh com a respetiva configuração predefinida.

      O resultado tem um aspeto semelhante ao seguinte:

      NAME                   TYPE           CLUSTER-IP     EXTERNAL-IP  PORT(S)
istio-ingressgateway   LoadBalancer   XX.XX.XXX.XX   pending      80:32380/TCP,443:32390/TCP,32400:32400/TCP

      em que o valor EXTERNAL-IP é o seu endereço IP externo do LoadBalancer.

    2. Verifique o registo de DNS do domínio executando o seguinte comando: 

      host DOMAIN

      Se o endereço IP do Registo de DNS não corresponder ao IP externo do balanceador de carga de entrada, configure o Registo de DNS para mapear o domínio do utilizador para o IP externo.

    3. Depois de o registo DNS (atualizado) entrar em vigor, execute o seguinte comando para eliminar o objeto Order de modo a acionar novamente o processo de pedido de um certificado TLS:

      kubectl delete order DOMAIN -n NAMESPACE

    Substituir

    • DOMAIN com o nome do domínio que está a usar.
    • NAMESPACE com o espaço de nomes que usa para o mapeamento de domínios.

Falha na implementação no cluster privado: erro de chamada do webhook

A sua firewall pode não estar configurada corretamente se a implementação num cluster privado falhar com a mensagem:

Error: failed calling webhook "webhook.serving.knative.dev": Post
https://webhook.knative-serving.svc:443/?timeout=30s: context deadline exceeded (Client.Timeout
exceeded while awaiting headers)

Para obter informações sobre as alterações à firewall necessárias para suportar a implementação num cluster privado, consulte o artigo Ativar implementações num cluster privado.

Os serviços comunicam o estado IngressNotConfigured

Se IngressNotConfigured for apresentado no estado do serviço, pode ter de reiniciar a implementação do istiod no espaço de nomes istio-system se estiver a usar a malha de serviços na nuvem do plano de controlo no cluster. Este erro, que tem sido observado com maior frequência no Kubernetes 1.14, pode ocorrer se os serviços forem criados antes de istiod estar pronto para começar o seu trabalho de reconciliação de VirtualServices e envio da configuração do Envoy para os gateways de entrada.

Para corrigir este problema, aumente a escala da implementação e, em seguida, diminua-a novamente com comandos semelhantes aos seguintes:

kubectl scale deployment istiod -n istio-system --replicas=0
kubectl scale deployment istiod -n istio-system --replicas=1

Faltam métricas de contagem de pedidos e latência de pedidos

O seu serviço pode não comunicar a contagem de pedidos de revisão e as métricas de latência de pedidos se tiver a Workload Identity Federation para o GKE ativada e não tiver concedido determinadas autorizações à conta de serviço usada pelo seu serviço.

Pode corrigir este problema seguindo os passos na Secção Ativar métricas num cluster com a Workload Identity Federation para o GKE.