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 / proxy | O que definir |
|---|---|
| nginx | proxy-buffering: "off", proxy-request-buffering: "off", proxy-read-timeout: "300", proxy-send-timeout: "300" |
| Traefik | Sem buffer por padrão. Para uma garantia forte, defina flushInterval: "1ms" em um ServersTransport/TraefikService. |
| HAProxy | haproxy.org/timeout-server: "300s", haproxy.org/response-buffer-size: "0" |
| AWS ALB | alb.ingress.kubernetes.io/target-group-attributes: stickiness.enabled=true,deregistration_delay.timeout_seconds=300 |
| GCE | Um BackendConfig com timeoutSec: 300; anotações sozinhas não resolvem isso no GCE. |
| Contour | Um 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:
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/sessionse 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.