Pular para o conteúdo

Visão geral

Arquitetura

O SRE Orbit roda como quatro componentes, com uma fronteira de autenticação e uma superfície exposta ao navegador. Todas as outras páginas pressupõem que você já leu esta.

Os quatro componentes

ComponenteLinguagemImagemPorta(s) do contêinerFinalidade
webTypeScript, Next.js 16 (standalone)ghcr.io/sreorbit/web:0.1.03000Site institucional + UI do Orbit Deck. O único componente para o qual um ingress roteia.
orbit-apiRustghcr.io/sreorbit/orbit-api:0.1.08080 (API), 9090 (métricas)BFF do Deck: clusters, workloads, telemetria, FinOps; usuários, papéis, sessões, dashboards e a trilha de auditoria, em volume próprio, como réplica única. Também o reverse proxy à frente do nocturne.
nocturneRustghcr.io/sreorbit/nocturne:0.1.08081 (API), 9090 (métricas)Assistente de IA. Agnóstico de provedor, transmite por SSE. Nunca alcançável de fora da rede do cluster.
orbit-stackRustghcr.io/sreorbit/orbit-stack:0.1.08082 (API), 9090 (métricas)O engine de telemetria: remote-write do Prometheus e traces OTLP na entrada, PromQL e leitura de traces na saída, blocos colunares em zstd e segmentos de trace num volume. O orbit-api o consulta; os seus agentes e SDKs fazem push para ele. Nunca roteado por um ingress.

Namespace do Kubernetes: sreorbit. Chart Helm: deploy/helm/sreorbit. Cluster k3d de desenvolvimento: sreorbit-dev. Os quatro são entregues como imagens multi-stage e distroless (nodejs26-debian13:nonroot para o web; cc-debian13:nonroot para os três serviços em Rust): sem shell, sem gerenciador de pacotes, sem curl na camada final, USER 65532:65532 não-root.

Orbit Stack é o nome do engine, orbit-stack é o contêiner dele. A frase "um único binário" no material de marketing se refere a esse engine, nunca à plataforma, que são estes quatro contêineres. O que o engine armazena, seus endpoints e o PromQL que ele responde estão em orbit-stack.md; o que ele mediu contra o Prometheus está em benchmark.md.

O que conversa com o quê

text
                          Internet
                             │
                             ▼
                  ┌───────────────────────┐
                  │  Ingress / LB (seu)   │   roteia SOMENTE para web:3000
                  └───────────┬───────────┘
                              │ HTTPS
                              ▼
                  ┌───────────────────────┐        modo demo: dados sintéticos
                  │  web · Next.js :3000  │        gerados no processo, zero
                  │ marketing + UI do Deck│◄─────── salto de rede (veja abaixo)
                  └───────────┬───────────┘
                              │ /api/*: o SERVIDOR Next.js anexa o
                              │ ORBIT_AUTH_TOKEN e encaminha.
                              │ Este salto nunca roda no navegador.
                              ▼
                  ┌───────────────────────┐
                  │ orbit-api · Rust :8080│───▶ :9090  /metrics (listener próprio,
                  │ clusters / workloads /│      regra própria de NetworkPolicy)
                  │ telemetria / FinOps   │───▶ orbit-stack :8082, PromQL para
                  └───────────┬───────────┘     query_range (ORBIT_STACK_URL)
                              │                        ▲ remote-write dos agentes
                              │                        │ que você roda (ou do feed
                              │                        │ de telemetria do loop k3d)
                              │ POST /api/v1/nocturne/{chat,analyze,models}
                              │ reverse proxy com streaming, NOCTURNE_AUTH_TOKEN
                              │ anexado, SSE repassado sem buffer
                              ▼
                  ┌───────────────────────┐
                  │ nocturne · Rust :8081 │───▶ :9090  /metrics (listener próprio)
                  │ assistente de IA, SSE │
                  └───────────┬───────────┘
                              │ apenas quando NOCTURNE_PROVIDER != mock,
                              │ e apenas com egress explicitamente liberado
                              ▼
                   Provedor de modelo (compatível com OpenAI ou Anthropic)
                   (nunca contatado pela instalação padrão)

Três regras decorrem desse diagrama, e o resto desta documentação depende delas:

  1. O navegador nunca conversa diretamente com o orbit-api ou com o nocturne. O web é o único componente com ingress.enabled: true no chart Helm, o único com um path em deploy/kubectl/60-ingress.yaml e o único que o docker-compose expõe para algo além de depuração local. NEXT_PUBLIC_API_URL não existe neste contrato: uma URL de API embutida no build e visível no navegador era ao mesmo tempo um parâmetro de ajuste enganoso e um caminho documentado para contornar o proxy, então foi removida. O servidor Next.js do web faz proxy de /api/* para o orbit-api e anexa ele mesmo o ORBIT_AUTH_TOKEN; o token nunca chega ao JavaScript do cliente.
  2. O nocturne não tem superfície pública alguma. Ele não tem regra de ingress, não tem configuração de CORS e (no Kubernetes) tem uma NetworkPolicy que admite tráfego apenas do orbit-api. O orbit-api expõe POST /api/v1/nocturne/chat, POST /api/v1/nocturne/analyze e GET /api/v1/nocturne/models como um reverse proxy com streaming para o nocturne, anexando o NOCTURNE_AUTH_TOKEN nesse salto interno. Um endpoint de LLM alcançável pela internet deixa qualquer um que encontre a URL inflar a sua fatura de modelo; veja security.md.
  3. /metrics não faz parte da superfície pública da API em nenhum dos serviços de backend. Ele escuta em um endereço separado (ORBIT_METRICS_ADDR / NOCTURNE_METRICS_ADDR, default :9090) para o qual nenhum ingress roteia e que a lista de isenções do middleware de autenticação não cobre, porque não está no listener ao qual essa lista se aplica. No Kubernetes, alcançá-lo de fora do pod exige uma regra de NetworkPolicy nomeando explicitamente o namespace do seu Prometheus; veja security.md e operations.md.

A fronteira de autenticação

Toda requisição que entra no orbit-api ou no nocturne passa por um middleware de autenticação à frente do router, apenas no listener da API. Três modos (ORBIT_AUTH_MODE / NOCTURNE_AUTH_MODE):

  • static: comparação em tempo constante de Authorization: Bearer <token> contra ORBIT_AUTH_TOKEN / NOCTURNE_AUTH_TOKEN. O serviço se recusa a iniciar se o token estiver vazio ou tiver menos de 32 bytes. Este é o default.
  • oidc: um JWT RS256/ES256 verificado contra o JWKS de <PREFIX>_OIDC_ISSUER, conferindo exp/iss/aud, com um cache limitado de renovação de chaves.
  • disabled: apenas para demonstrações locais. O serviço registra um WARN nomeando o risco a cada inicialização e se recusa a iniciar se ORBIT_DEMO_DATA=false, então você não consegue, por acidente, rodar sem autenticação contra um cluster real.

GET /healthz e GET /readyz são isentos em todos os modos, em todos os serviços, sempre: um load balancer precisa conseguir fazer probe de um serviço antes que esse serviço possa provar que tem uma credencial válida para qualquer coisa. Nada mais é isento. Uma verificação que falha devolve 401 com {"error":{"code":"unauthorized","message":"..."}} e nunca distingue "sem token", "token errado" e "token expirado" nessa mensagem; o security.md explica por que isso é deliberado.

/metrics fica inteiramente fora dessa fronteira, do outro lado: está em um listener diferente daquele que o middleware de autenticação guarda, então a lista de isenções não se aplica a ele: não há nada de que isentá-lo. O isolamento dele é um controle de rede (endereço de bind + NetworkPolicy), não de autenticação.

A fronteira em uma frase: apenas o código renderizado no servidor do web e as funções de servidor do Next.js carregam o ORBIT_AUTH_TOKEN ou o NOCTURNE_AUTH_TOKEN; nada que rode no navegador, e nenhum componente além do web, jamais os carrega.

Quem está pedindo: usuários por cima do bearer

O bearer prova que a chamada passou pelo web; ele não diz que pessoa está por trás dela. O Adendo v0.5 acrescenta essa camada, e cada peça dela vive no orbit-api:

  • O navegador entra pela rota de login do próprio web, que recebe do orbit-api um token de sessão opaco e o guarda no cookie orbit_session, marcado como HttpOnly. O JavaScript da página nunca o enxerga.
  • Em toda chamada que passa pelo proxy e em toda leitura feita no servidor, o web copia esse valor para o X-Orbit-Session, ao lado do bearer, e nunca repassa o header Cookie do navegador.
  • O orbit-api confere o bearer, em seguida a sessão (primeiro a assinatura; depois, se ela existe, se ainda não expirou e se pertence a um usuário ativo) e, por fim, a única permissão que a rota exige, lida do papel do usuário naquela mesma requisição. Uma rota à qual ninguém atribuiu permissão continua exigindo sessão: a lista pública se resume às probes, às rotas de login e ao contact.
  • Quando alguém faz uma pergunta ao Nocturne, a sessão dessa pessoa vai junto até o nocturne e volta em cada chamada de ferramenta, de modo que o assistente lê com as permissões dela, e não com as do serviço.

Os papéis, o conjunto fechado de permissões e as regras de login estão em identity.md; o rastro que cada mudança deixa está em audit.md.

O único estado que o orbit-api guarda

Usuários, papéis, sessões, dashboards salvos, reconhecimentos de alertas, leads do formulário de contato e a trilha de auditoria são arquivos sob ORBIT_DATA_DIR: um documento JSON por objeto, gravado primeiro em um arquivo temporário, com fsync, e então renomeado; a trilha de auditoria fica em um arquivo JSONL append-only por dia. Um armazenamento em arquivos tem um único escritor, por isso o orbit-api roda como uma única réplica em qualquer caminho de instalação: o chart renderiza replicas: 1 não importa o que diga o replicaCount, recusa autoscaling para ele, deixa de gerar o PodDisruptionBudget dele e, com a persistência ligada, põe o diretório em um claim ReadWriteOnce com rollout Recreate. Esse é o teto desta versão: um rollout ou a perda de um node vira uma interrupção curta do console, e o orbit-api escala verticalmente, não horizontalmente. O caminho de evolução que o código-fonte aponta é o Postgres. Todo o resto que o Deck mostra continua sendo lido ao vivo, do Kubernetes e do engine, e nunca fica guardado aqui.

Traces: OTLP para dentro do engine

As aplicações, ou um OpenTelemetry Collector posicionado à frente delas, enviam spans por OTLP/HTTP ao orbit-stack na porta 8082, em /v1/traces, com o mesmo bearer que os agentes usam no remote-write. O engine grava esses spans em um log de traces e em um head em memória, corta o head em segmentos comprimidos e com checksum no volume dele e apaga segmentos inteiros quando passam de ORBIT_STACK_TRACE_RETENTION. Cada span aceito também alimenta um gerador que grava métricas de span e séries do grafo de serviços, com os nomes que o Tempo usa, no próprio armazenamento de séries temporais do engine, onde PromQL, dashboards e alertas as leem como qualquer outra métrica. O orbit-api repassa as cinco leituras de APM ao engine para uma sessão que tenha apm.read. Nada disso sai do volume do engine, e não entra em cena nenhum segundo armazenamento nem serviço de consulta. O caminho completo, e o que enviar, está em apm.md.

O que sai da sua conta: nada

O SRE Orbit é auto-hospedado. Não existe um backend da SRE Orbit, Inc. para o qual estes quatro contêineres liguem, não há endpoint de telemetria embutido em nenhuma imagem e não há chamada de rede para verificação de licença. Concretamente:

  • Do ponto de vista do navegador, o web não faz chamadas de saída: toda chamada de API que a UI faz é de mesma origem, para o próprio web, que então repassa pelo servidor.
  • O orbit-stack não chama nada. Ele escuta remote-write e responde consultas; seus blocos ficam no volume que você deu a ele.
  • O orbit-api chama o nocturne e o orbit-stack (dentro do cluster) e, quando ORBIT_DEMO_DATA=false, a API do Kubernetes para a qual o seu ORBIT_KUBECONFIG aponta. Ele não chama nada na internet pública, com uma única exceção, que só vale se você a ligar: defina ORBIT_CONTACT_WEBHOOK_URL e ele faz um POST, para a URL que você indicou, de cada lead que o formulário de contato do site guarda.
  • O nocturne chama um provedor de modelo apenas quando NOCTURNE_PROVIDER é openai ou anthropic, e apenas depois que você também tiver definido allowInternetEgress: true para ele. São duas opções separadas, e nenhuma aciona a outra. Com o default NOCTURNE_PROVIDER=mock, o nocturne faz zero chamadas de rede de saída; a demonstração roda sem credencial e sem egress. O que ele envia é a conversa e o que as ferramentas dele leem: o estado do cluster e, de uma conexão de banco que um admin abriu para o Nocturne, respostas de consulta que o orbit-api mascarou antes (databases.md, "Nocturne em um banco").
  • Nada neste repositório envia analytics de uso, relatórios de falha ou pings de verificação de versão para lugar algum. Se isso mudar algum dia, será uma variável de ambiente documentada no CONTRACT.md e desligada por padrão, e não um default silencioso.

O caminho do dado de uma métrica, do ingest ao pixel

Existem hoje dois caminhos distintos. Confundir os dois é o mal-entendido mais comum sobre este produto, então diga de qual deles você está falando.

Modo demo (NEXT_PUBLIC_DEMO_MODE=true, o default). O Orbit Deck lê diretamente de apps/web/src/lib/demo-estate.ts, um conjunto de dados determinístico, no processo, com o formato exato das respostas do orbit-api no CONTRACT.md (mesmos nomes de campo, mesmo formato de série de QueryResult). Não há salto de rede: um Server Component chama uma função, recebe um objeto de volta e o renderiza. É por isso que o hero do site e o Deck mostram números idênticos; o CLAIMS.md chama isso de "ONE estate, used by the marketing hero and the Deck alike". O tempo é congelado em um relógio fixo para que servidor e cliente renderizem os mesmos pixels sem divergência de hidratação.

Modo ao vivo (NEXT_PUBLIC_DEMO_MODE=false, ORBIT_DEMO_DATA=false). Uma requisição do navegador por uma página do Deck chega ao web; o servidor do web chama o orbit-api pelo proxy interno /api/* com o ORBIT_AUTH_TOKEN anexado; o orbit-api resolve a requisição contra a fonte ao vivo (services/rust/orbit-api/src/live.rs) em vez da fonte de demonstração e devolve JSON no mesmo formato (Cluster[], QueryResult etc.; veja api.md); o web o renderiza com os mesmos componentes (TimeChart, StatTile) que renderizam o parque de demonstração.

O que o modo ao vivo lê, e o que ele deriva

As credenciais vêm de ORBIT_KUBECONFIG (um cluster por contexto, sendo o {id} o nome do contexto em minúsculas com tudo fora de [a-z0-9-] substituído por -) ou, quando ela está vazia, da própria ServiceAccount do pod (ORBIT_CLUSTER_ID nomeia esse cluster único). O chart vincula um ClusterRole somente-leitura para o caminho dentro do cluster sob components.orbit-api.rbac.enabled; deploy/kubectl/15-rbac-orbit-api.yaml é a mesma coisa sem templating. Apenas get, list e watch, e nunca sobre secrets.

Lidos do API server: nodes, pods, namespaces, events, PersistentVolumes e Deployments, StatefulSets, DaemonSets e CronJobs (mais os ReplicaSets e Jobs necessários para rastrear um pod até o controller que o possui). A capacidade do node é a allocatable, não a capacidade bruta, de modo que a linha de um node e o painel de saturação de CPU sejam medidos contra o mesmo denominador. A utilização vem de metrics.k8s.io quando o API group está instalado (o k3s entrega o metrics-server); quando não está, o uso é 0, nunca uma estimativa, porque um request devolvido como se fosse medição é pior do que um espaço em branco.

Derivados, porque o Kubernetes não tem de onde lê-los:

  • Status do cluster. critical quando o control plane não responde ou a maioria dos nodes está NotReady; degraded quando algum node está NotReady, algum workload ficou abaixo do desejado por mais de 5 minutos ou algum pod está em CrashLoopBackOff; healthy caso contrário.
  • Alertas. Não há Alertmanager neste build, então seis regras rodam sobre os mesmos objetos e emitem o mesmo formato de Alert: NodeNotReady e PodCrashLooping (critical), PodPending acima de 5 minutos e DeploymentReplicasUnavailable (warning), KubeletVersionSkew e ContainerWithoutLimits (info). Todo alerta derivado tem state: "firing" e não carrega team: uma regra derivada não tem label de roteamento, e inventar uma aciona as pessoas erradas. A regra em si sempre diz ack: "open"; quem tem workloads.write pode reconhecer um alerta ou silenciá-lo por um tempo definido, e o orbit-api guarda isso no próprio armazenamento e aplica por cima de toda leitura, com quem fez e até quando. Cada regra, e o que checar quando ela dispara, está em alerts.md.
  • Custo. monthlyCost é a soma, sobre os nodes, de um preço por hora multiplicado por 730 horas. Onde o Karpenter roda (ORBIT_KARPENTER_NAMESPACE, default karpenter), cada node é precificado pelas estimativas da AWS do próprio Karpenter, conforme o tipo de instância, o tipo de capacidade (on-demand ou spot) e a zona, lidas na porta de métricas do líder a cada 10 minutos. Nos demais casos, vale uma tabela embutida de preços on-demand de us-east-1, com 1.371 tipos de EC2; um node spot custa 30% desse preço, a participação mediana do spot no dia em que a tabela foi tirada. Um tipo que não está em nenhuma das duas é precificado por ORBIT_NODE_HOURLY_USD (default 0). O gasto é rateado entre namespaces pelo request de CPU. A cobertura de spot é a parcela de nodes em spot, lida dos labels capacityType do mesmo jeito que o gráfico de spot do Deck conta. O desperdício é request menos uso. Todo payload de FinOps carrega um "source", que a página mostra: karpenter quando todos os nodes foram precificados pelo Karpenter, senão list-price, senão flat. Isto é uma estimativa e ela está errada de maneiras nomeadas: ignora Savings Plans, Reserved Instances, descontos EDP, armazenamento, rede e a taxa de control plane. Sem o Karpenter, também ignora o mercado spot ao vivo e toda região que não seja us-east-1. Não há mês anterior para comparar, então deltaPct é 0 e forecast é o formato de hoje repetido por um mês, não uma projeção. O Cost Explorer substitui tudo isso; até ele chegar, não leve esses números para o financeiro.
  • Recomendações. O rightsizing dispara quando um workload com duas ou mais réplicas consome menos da metade do seu request de CPU, com confiança low porque o uso aqui é uma amostra de metrics.k8s.io, não um p95 sobre uma janela. A elegibilidade para spot é medium (a tolerância a interrupção é inferida do kind do workload). PersistentVolumes órfãos são high, porque Released e Available são fatos que o API server afirma explicitamente.

Telemetria (GET /api/v1/query_range) não é armazenada pelo orbit-api de forma alguma. Com ORBIT_STACK_URL definida, cada MetricKey que o Deck pede vira PromQL sobre kube-state-metrics, node-exporter, cAdvisor ou as métricas do próprio TSDB do engine, e o painel ad hoc do Deck envia PromQL bruto literalmente; o errorType do engine decide se uma falha é de quem chamou (invalid_request) ou do engine (upstream_error). Uma métrica que o parque não emite volta como uma matriz vazia, que se lê como "sem dados" em vez de uma linha fabricada. Com ORBIT_STACK_URL vazia, query_range responde uma série vazia com a unidade correta, uma expressão ad hoc é recusada e /readyz não checa um engine que não está configurado.

De um jeito ou de outro, a metade do caminho que renderiza pixels é idêntica: JSON em um formato fixo na entrada, TimeChart / StatTile / BarRows na saída, com formatação de números por locale (CLAIMS.md → "Number formatting by locale") aplicada no momento da renderização, para que uma página pt-BR nunca imprima um numeral en-US.

Para onde ir em seguida