Pular para o conteúdo

Operação

Solução de problemas

Modos de falha reais, indexados por sintoma. Os três primeiros são problemas específicos já descobertos, que você vai encontrar se pular esta página; o restante é a classe de problema que o desenho deste contrato implica. Se o seu sintoma não estiver aqui, olhe primeiro a tabela de falhas de probe do operations.md e depois o security.md para qualquer coisa com cara de autenticação ou de rede.

O pod do web entra em CrashLoopBackOff na startup probe no Kubernetes

Escopo: só em imagens anteriores à mudança. As imagens atuais servem /healthz sozinhas, a partir do próprio proxy de autenticação do web, respondido antes da autenticação e antes do roteamento de locale (veja security.md). O chart e os manifestos kubectl puros já fazem probe em /healthz para o web como em qualquer outro componente. Se essa é a imagem que você está rodando, esta entrada não é o seu bug. Ela continua valendo para qualquer imagem construída antes dessa mudança.

Sintoma. kubectl get pods -n sreorbit mostra o sreorbit-web ciclando em CrashLoopBackOff. kubectl describe pod mostra a startup ou a liveness probe falhando contra /healthz. Isso não aparece no docker compose: o healthcheck do compose para o web passa.

Causa. O CONTRACT.md limita /healthz e /readyz apenas aos dois serviços de backend; o web não tem essa rota. Pior: não é um 404 limpo e pronto. O middleware next-intl do apps/web reescreve qualquer path não casado para dentro da árvore de rotas por locale, em vez de emitir um redirecionamento, então uma probe contra /healthz resolve para uma resposta 404 real. A probe httpGet do Kubernetes só trata os status 200 a 399 como sucesso, então esse 404 reprova a probe de imediato. (Se o middleware tivesse redirecionado em vez de reescrito, o status 3xx teria caído acidentalmente dentro da faixa de sucesso e mascarado o problema; é por isso que o comportamento é "reescreve, não redireciona".) O healthcheck do próprio compose não esbarra nisso porque é um one-liner Node escrito à mão que aceita explicitamente qualquer status abaixo de 500.

Correção. Em uma imagem anterior à mudança, faça probe em / para o web, não em /healthz: é isso que essas imagens servem, e é o que um chart Helm ou manifesto kubectl antigo já faz por default; se você escreveu um ingress ou uma configuração de probe à mão, siga isso. Em uma imagem atual, faça o oposto: o chart e os manifestos kubectl puros já apontam as probes de startup, liveness e readiness do web para /healthz, respondida pelo próprio proxy, então não "conserte" de volta para /.

Toda requisição ao web responde 401, ou o navegador não para de pedir credencial

Sintoma. Toda página, o Orbit Deck e o /api/* respondem 401 com WWW-Authenticate: Basic realm="SRE Orbit", charset="UTF-8"; o navegador fica repetindo o pedido de usuário e senha, ou não aceita nenhuma combinação que você tenta.

Causa. WEB_AUTH_MODE=basic está ligado e ou a credencial que você está digitando não bate com WEB_AUTH_USER/WEB_AUTH_VERIFIER, ou você também está rodando basic auth no nível do ingress: o ingress-nginx limpa o cabeçalho Authorization assim que a própria checagem dele dá certo. Para evitar isso, o render do Helm recusa de saída quando ingress.basicAuth.enabled e a autenticação do web estão ligados ao mesmo tempo.

Correção. Confira a credencial contra a senha que você hasheou com hash-password.mjs; gere de novo o WEB_AUTH_VERIFIER se estiver em dúvida (veja configuration.md) e reinicie os pods do web para aplicar. Se você quer mesmo a basic auth no nível do ingress, desligue o components.web.auth.enabled em vez de rodar as duas.

Os pods do web nunca ficam Ready, e todo path responde 503

Sintoma. kubectl get pods mostra o web nunca Ready; todo path, inclusive /healthz, responde 503 com código de corpo not_ready. Uma linha de log começando com web auth: é impressa uma vez por pod.

Causa. WEB_AUTH_MODE=basic está definido, mas WEB_AUTH_USER ou WEB_AUTH_VERIFIER está ausente ou malformado. O web falha fechado em vez de servir tráfego com autenticação quebrada: o pod nunca é marcado Ready, por desenho, então um rollout com um verificador ruim trava em vez de substituir pods que funcionam.

Correção. Leia a linha de log web auth: para o problema específico, corrija as chaves do Secret (veja configuration.md) e então reinicie o deployment: kubectl -n <ns> rollout restart deploy/<release>-web.

Pod do web travado em CreateContainerConfigError: não encontra a chave WEB_AUTH_USER

Sintoma. kubectl get pods mostra o web em CreateContainerConfigError; kubectl describe pod nomeia o erro: couldn't find key WEB_AUTH_USER in Secret ... (ou o mesmo para WEB_AUTH_VERIFIER).

Causa. A autenticação do web está ligada (components.web.auth.enabled), e o chart conecta WEB_AUTH_USER/WEB_AUTH_VERIFIER a partir do Secret do release via secretKeyRef sem optional, de propósito: um Secret sem uma das duas chaves falha na hora e às claras, em vez de subir o web com a autenticação pela metade.

Correção. Adicione a(s) chave(s) que falta(m) ao Secret. Não precisa reiniciar depois disso: o pod já existe em estado de falha e sobe sozinho assim que as chaves existirem.

429 rate_limited ao entrar no web

Sintoma. Entrar no web responde 429 com código de corpo rate_limited, com um cabeçalho Retry-After: 1 ou, se este cliente já errou antes, um Retry-After maior que cresce conforme os palpites errados dele se acumulam.

Causa. São duas camadas, e o cabeçalho diz qual delas disparou. Retry-After: 1 é a camada global: mais de duas derivações de senha já estão em andamento (geralmente muitos palpites errados, ou sondagem automatizada, chegando ao mesmo tempo), e ela limita a CPU que uma enxurrada pode queimar, não importa a origem. Um Retry-After maior é a camada por cliente: depois de 5 palpites errados do mesmo cliente, cada novo erro dobra a espera (1, 2, 4 s, até 60 s) até passarem 15 minutos sem erro, ou até a senha certa zerar tudo. O cliente é o último salto do X-Forwarded-For, que um pod capaz de alcançar o web diretamente consegue forjar e trocar, então espalhar a enxurrada por clientes falsos ainda esbarra na camada global acima.

Correção. Espere os segundos que o Retry-After mandar e tente de novo. Se isso for constante em vez de ocasional, alguma coisa está martelando o web com credenciais: persiga a origem desse tráfego em vez de aumentar qualquer um dos dois limites. Se as tentativas nunca derem certo, o problema é a credencial: confira-a contra a senha que você hasheou com hash-password.mjs.

As respostas do chat chegam todas de uma vez, em vez de token a token

Sintoma. A UI de chat do Nocturne AI (ou um curl direto contra /api/v1/nocturne/chat) fica sem saída e então ou despeja a resposta inteira de uma vez ou corta por volta dos 60 segundos, em vez de transmitir os tokens conforme são gerados.

Causa. Um ingress ou reverse proxy entre o chamador e o nocturne está fazendo buffer da resposta. Um stream com buffer anula o SSE por definição, e um proxy_read_timeout padrão de cerca de 60s também vai cortar uma geração mais longa no meio da resposta. É por isso que o chart Helm renderiza automaticamente anotações seguras para SSE para ingress.className: nginx (proxy-buffering: "off", proxy-request-buffering: "off", proxy-read-timeout: "300", proxy-send-timeout: "300" e um teto de corpo de 1m alinhado ao contrato) e por que o deploy/kubectl/60-ingress.yaml entrega as mesmas anotações escritas à mão.

Correção. Se você está no nginx via chart Helm, isso já está resolvido; não sobrescreva ingress.annotations com um valor de proxy-buffering "on". Se você usa outra classe de ingress ou um proxy escrito à mão à frente de qualquer um destes três componentes, aplique o equivalente daquela tecnologia:

Ingress / proxyO que definir
nginxproxy-buffering: "off", proxy-request-buffering: "off", proxy-read-timeout: "300", proxy-send-timeout: "300"
TraefikSem buffer por padrão. Para uma garantia forte, defina flushInterval: "1ms" em um ServersTransport/TraefikService.
HAProxyhaproxy.org/timeout-server: "300s", haproxy.org/response-buffer-size: "0"
AWS ALBalb.ingress.kubernetes.io/target-group-attributes: stickiness.enabled=true,deregistration_delay.timeout_seconds=300
GCEUm BackendConfig com timeoutSec: 300; anotações sozinhas não resolvem isso no GCE.
ContourUm HTTPProxy com timeoutPolicy.response: 300s

Confirme também que o timeout da aplicação não é o teto real: NOCTURNE_TIMEOUT (default 120s) é o timeout do provedor upstream, independente de qualquer ajuste de proxy.

Um rollback de Helm não cai sobre os bytes que você testou

Sintoma. helm -n sreorbit rollback sreorbit "tem sucesso", mas o comportamento que você vê depois não é o que você lembra de ter testado antes da release ruim, como se o rollback não tivesse restaurado a versão antiga.

Causa. Sem um digest de imagem, a referência de imagem de um componente no chart é uma tag (ghcr.io/sreorbit/orbit-api:0.1.0), e uma tag é um ponteiro mutável. Se alguém publicou uma nova imagem nessa mesma tag entre a sua instalação original e o rollback, o helm rollback reaplica os valores registrados da release, que continuam dizendo :0.1.0, e o Kubernetes baixa o que quer que :0.1.0 resolva agora, não o que resolvia no momento da instalação. O rollback é idêntico byte a byte ao registro da release, não necessariamente aos bytes que rodaram.

Correção. Nunca instale produção sobre uma tag pura. O values-prod.yaml define requireDigest: true para que o chart se recuse a renderizar por completo se o image.digest de qualquer componente habilitado estiver vazio. Resolva todo digest no CI antes (deploy/helm/sreorbit/digests.example.yaml traz o loop exato com crane digest) e passe-o com -f digests.yaml ou --set-string components.<name>.image.digest=sha256:.... Com os digests travados, um rollback restaura exatamente o mesmo endereço de conteúdo imutável toda vez. Veja install/helm.md.

O orbit-api ou o nocturne não inicia de jeito nenhum: ele sai, sem crash loop

Sintoma. O contêiner/pod sai imediatamente no boot; ele nem chega à startup probe. Uma linha de log nomeia um token e uma contagem de bytes.

Causa. ORBIT_AUTH_MODE / NOCTURNE_AUTH_MODE têm default static, que exige que ORBIT_AUTH_TOKEN / NOCTURNE_AUTH_TOKEN tenham pelo menos 32 bytes. Um valor vazio (o default do próprio chart; ele nunca entrega um) ou um valor curto digitado à mão é recusado na inicialização, de propósito: configuração errada falha fechada, antes de servir uma única requisição, e não depois.

Correção. Gere um token de verdade e forneça-o como Secret: veja configuration.md → "Gerando um token estático" e a seção "Secrets" do seu caminho de instalação. Isto não é um bug a contornar; um serviço que subisse assim mesmo é que seria o defeito.

O orbit-api recusa mais cinco coisas do mesmo jeito, cada uma nomeada na última linha de log dele: um ORBIT_DATA_DIR em que ele não consegue gravar, ORBIT_ADMIN_USER sem ORBIT_ADMIN_PASSWORD_VERIFIER ou o contrário, um verificador que ele não consegue interpretar, um ORBIT_SESSION_SECRET com menos de 32 bytes e um session.key do tamanho errado (apague o arquivo para que ele gere um novo; todas as sessões terminam). Veja identity.md.

O orbit-api está rodando, mas nunca fica Ready

Sintoma. GET /readyz (ou kubectl get pods) mostra o orbit-api perpetuamente fora de Ready; os logs não mostram crash, só um 503 constante em /readyz.

Causa. ORBIT_DEMO_DATA=false (o default do overlay de produção) com ORBIT_KUBECONFIG não definida ou apontando para um caminho que não está montado. O orbit-api reporta "não consigo alcançar a minha fonte de dados" em vez de servir nada e dizer que está bem. Isto é a exigência de readiness do adendo funcionando como pretendido, não um processo travado.

Correção. Monte um kubeconfig real (via extraVolumes/extraVolumeMounts no Helm, ou um Volume/VolumeMount em um manifesto escrito à mão) e aponte ORBIT_KUBECONFIG para o caminho de montagem, ou defina ORBIT_DEMO_DATA=true se você pretende usar dados de demonstração naquele ambiente.

Um pod fica em ImagePullBackOff só no loop do k3d

Sintoma. Um ou mais entre web/orbit-api/nocturne nunca sai de ImagePullBackOff no sreorbit-dev, mesmo que o mesmo chart instale sem problemas em outros lugares.

Causa. values-dev.yaml define image.pullPolicy: Never de propósito, para que um k3d image import ausente falhe alto e na hora, em vez de silenciosamente tentar alcançar o ghcr.io e dar timeout. Se a imagem de um componente nunca foi construída e importada (o caso mais comum: o build dela falhou, ou SKIP_BUILD estava definido num cluster que nunca a teve, quando você rodou o loop), este é o sintoma esperado, não um bug de rede.

Correção. O ./deploy/k3d/up.sh (ou make k3d-up) já imprime note: <name> was not built, so the pods running <image> will not start. ao final da execução quando isso acontece; leia essa linha. Construa e importe a imagem que falta (rode de novo sem SKIP_BUILD) e depois make k3d-deploy.

Uma NetworkPolicy existe, é aplicada sem erro e não bloqueia nada

Sintoma. Um pod em um namespace sem relação ainda consegue alcançar o orbit-api ou o nocturne (ou fazer scrape em :9090) mesmo com o objeto NetworkPolicy correspondente presente e o kubectl get networkpolicy mostrando que foi aplicado sem erro.

Causa. A NetworkPolicy só é imposta por uma CNI que a implemente. O flannel sozinho não implementa; o k3s acrescenta o controlador de políticas do kube-router, então o cluster de install/local-k3d.md impõe, sim. A EKS só impõe com o agente de políticas de rede da VPC CNI ligado, e a maioria dos clusters EKS roda sem ele. O objeto ser aplicado sem erro prova que o YAML é válido; não prova nada sobre a imposição efetiva.

Correção. É uma propriedade da CNI, não deste chart: ligue a imposição (na EKS, enableNetworkPolicy no add-on da VPC CNI, ou um add-on Calico/Cilium) e comprove-a com um pod de outro namespace antes de confiar neste controle para qualquer coisa. Detalhe completo: security.md.

401 unauthorized com um token que você tem certeza de que está correto

Sintoma. Toda requisição recebe 401 / {"error":{"code":"unauthorized",...}} apesar de o cabeçalho Authorization visivelmente conter o token que você gerou.

Causa, quase sempre. Uma quebra de linha no final ou um caractere de espaço perdido foi embutido no valor do segredo, normalmente por mandar openssl rand -hex 32 via pipe direto para um comando que não remove a quebra de linha, ou por um copiar e colar que trouxe junto um fim de linha. O token armazenado e o token que você acha que definiu diferem por um byte invisível, e uma comparação em tempo constante não casa parcialmente.

Correção. Gere de novo e defina o valor com printf ou echo -n, nunca com um echo puro, e confira duas vezes se algum valor de --from-literal=/.env não tem quebra de linha no fim (xxd ou cat -A no arquivo mostram, se houver). Veja configuration.md.

401 com o bearer certo: "sign in: this needs a session"

Sintoma. Uma chamada ao orbit-api com um bearer que você sabe que está certo responde 401, e a mensagem diz sign in: this needs a session, and there is none or it ended, e não valid credentials are required.

Causa. O bearer passou; a sessão, não. Desde o Adendo v0.5, toda rota, exceto as probes, as rotas de login e o contact, também exige um usuário logado, enviado como X-Orbit-Session (pelo web, a partir do cookie orbit_session). A sessão está ausente, expirou (24 horas depois do login, ou 8 horas sem nenhuma requisição), foi revogada (logout, troca de senha, conta desativada, "Encerrar todas as sessões") ou foi assinada com uma chave que mudou desde então.

Correção. Faça login e envie o token: identity.md → "Entrar pelo shell". No navegador, entre de novo em /login. Use GET /api/v1/auth/state para checar só o bearer.

403 forbidden: "this needs the ... permission"

Sintoma. Uma página do Deck diz que você não tem acesso, ou uma chamada responde 403 citando uma permissão e o seu papel.

Causa. A sessão está em ordem, mas o papel dela não tem essa permissão. Cada recusa também vira um evento access.denied na trilha de auditoria. Um caso comum: um papel personalizado com dashboards.read, mas sem telemetry.query, abre os dashboards e tem todos os painéis recusados.

Correção. Um administrador dá ao usuário um papel que tenha a permissão, ou a acrescenta ao papel personalizado dele, em /deck/admin/roles; a mudança vale a partir da próxima requisição do usuário. Veja identity.md → "Papéis e permissões".

Ninguém consegue entrar como administrador

Sintoma. A senha do único administrador se perdeu, ou o código de configuração do log não funciona mais, ou o ORBIT_ADMIN_USER mudou e nada aconteceu.

Causa. O código de configuração só existe no processo em execução, e um código novo é impresso a cada inicialização enquanto não houver nenhum usuário; depois que existe um, não há mais código. O par de administrador no Secret só cria uma conta enquanto não houver nenhum usuário, e é ignorado a partir daí.

Correção. Outro usuário com users.manage redefine a senha em /deck/admin/users. Se não houver nenhum, esvazie as contas, mantenha todo o resto e deixe o par de administrador criar um administrador novo: pare o orbit-api, apague users/ e sessions/ do diretório de dados dele (papéis, dashboards e a trilha de auditoria continuam lá), defina ORBIT_ADMIN_USER e ORBIT_ADMIN_PASSWORD_VERIFIER e suba-o. No compose, coloque o par no .env e depois:

bash
docker compose --project-name sreorbit --env-file .env -f deploy/compose/docker-compose.yml stop orbit-apidocker run --rm -v sreorbit_orbit-api-data:/data busybox rm -rf /data/users /data/sessions

e suba a stack de novo do mesmo jeito que você a subiu antes, com make up ou make up-prod.

No Kubernetes, a imagem do orbit-api não tem shell: escale-o para 0, monte o claim dele em um pod temporário que tenha shell (o claim é ReadWriteOnce, então só depois que o orbit-api sair de cena), apague os mesmos dois diretórios e escale-o de volta para 1 com o par no Secret. Depois disso, todo usuário precisa entrar de novo; recrie as outras contas.

As páginas de APM estão vazias, ou dizem que o engine não está pronto

Sintoma. /deck/apm não mostra nenhum serviço, ou diz que o engine de telemetria não está pronto.

Causa, da mais para a menos provável. Nada está enviando spans na janela que você está olhando; o remetente é recusado (401 sem o bearer do engine, 415 por um Content-Type errado) ou fala gRPC, que o engine não atende; uma NetworkPolicy derruba a conexão do remetente com a porta 8082, o que aparece como timeout do lado do remetente, e não como erro aqui; ou o orbit-api não tem ORBIT_STACK_URL, e aí ele responde 503 not_ready em toda rota de APM.

Correção. Envie um span à mão (apm.md → "Pelo shell") e depois leia-o de volta pelo id. Se isso funcionar, confira o protocolo do exporter e o bearer do remetente, e adicione o namespace dele a components.orbit-stack.networkPolicy.allowFromNamespaces. O orbit_stack_spans_total conta o que chegou.

Todo evento de auditoria tem o mesmo endereço

Sintoma. O ip de todo evento da trilha de auditoria é o mesmo endereço privado.

Causa. Esse endereço é o do web, ou o do load balancer à frente do ingress. O web só repassa o cliente adiante com WEB_TRUST_PROXY=true (o compose define false), e o ingress controller só consegue repassar o cliente que ele próprio enxerga.

Correção. audit.md → "Como o IP do cliente é determinado": ligue o WEB_TRUST_PROXY atrás de um ingress e faça a borda preservar o endereço do cliente. Esses ajustes de borda valem para o controller inteiro, então a decisão cabe a quem é dono do cluster.

Para onde ir em seguida

  • O comportamento de probe/métrica sobre o qual estes sintomas se apoiam: operations.md.
  • O contrato exato que estas correções restauram: configuration.md, api.md.
  • O modelo de ameaças por trás de por que autenticação e NetworkPolicy falham fechadas: security.md.