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
| Componente | Linguagem | Imagem | Porta(s) do contêiner | Finalidade |
|---|---|---|---|---|
web | TypeScript, Next.js 16 (standalone) | ghcr.io/sreorbit/web:0.1.0 | 3000 | Site institucional + UI do Orbit Deck. O único componente para o qual um ingress roteia. |
orbit-api | Rust | ghcr.io/sreorbit/orbit-api:0.1.0 | 8080 (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. |
nocturne | Rust | ghcr.io/sreorbit/nocturne:0.1.0 | 8081 (API), 9090 (métricas) | Assistente de IA. Agnóstico de provedor, transmite por SSE. Nunca alcançável de fora da rede do cluster. |
orbit-stack | Rust | ghcr.io/sreorbit/orbit-stack:0.1.0 | 8082 (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ê
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:
- O navegador nunca conversa diretamente com o
orbit-apiou com onocturne. Owebé o único componente comingress.enabled: trueno chart Helm, o único com um path emdeploy/kubectl/60-ingress.yamle o único que o docker-compose expõe para algo além de depuração local.NEXT_PUBLIC_API_URLnã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 dowebfaz proxy de/api/*para oorbit-apie anexa ele mesmo oORBIT_AUTH_TOKEN; o token nunca chega ao JavaScript do cliente. - O
nocturnenã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 doorbit-api. Oorbit-apiexpõePOST /api/v1/nocturne/chat,POST /api/v1/nocturne/analyzeeGET /api/v1/nocturne/modelscomo um reverse proxy com streaming para onocturne, anexando oNOCTURNE_AUTH_TOKENnesse salto interno. Um endpoint de LLM alcançável pela internet deixa qualquer um que encontre a URL inflar a sua fatura de modelo; vejasecurity.md. /metricsnã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; vejasecurity.mdeoperations.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 deAuthorization: Bearer <token>contraORBIT_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, conferindoexp/iss/aud, com um cache limitado de renovação de chaves.disabled: apenas para demonstrações locais. O serviço registra umWARNnomeando o risco a cada inicialização e se recusa a iniciar seORBIT_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 doorbit-apium token de sessão opaco e o guarda no cookieorbit_session, marcado comoHttpOnly. O JavaScript da página nunca o enxerga. - Em toda chamada que passa pelo proxy e em toda leitura feita no servidor, o
webcopia esse valor para oX-Orbit-Session, ao lado do bearer, e nunca repassa o headerCookiedo navegador. - O
orbit-apiconfere 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 aocontact. - Quando alguém faz uma pergunta ao Nocturne, a sessão dessa pessoa vai junto até o
nocturnee 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
webnão faz chamadas de saída: toda chamada de API que a UI faz é de mesma origem, para o próprioweb, que então repassa pelo servidor. - O
orbit-stacknão chama nada. Ele escuta remote-write e responde consultas; seus blocos ficam no volume que você deu a ele. - O
orbit-apichama onocturnee oorbit-stack(dentro do cluster) e, quandoORBIT_DEMO_DATA=false, a API do Kubernetes para a qual o seuORBIT_KUBECONFIGaponta. Ele não chama nada na internet pública, com uma única exceção, que só vale se você a ligar: definaORBIT_CONTACT_WEBHOOK_URLe ele faz um POST, para a URL que você indicou, de cada lead que o formulário de contato do site guarda. - O
nocturnechama um provedor de modelo apenas quandoNOCTURNE_PROVIDERéopenaiouanthropic, e apenas depois que você também tiver definidoallowInternetEgress: truepara ele. São duas opções separadas, e nenhuma aciona a outra. Com o defaultNOCTURNE_PROVIDER=mock, onocturnefaz 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 oorbit-apimascarou 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.mde 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.
criticalquando o control plane não responde ou a maioria dos nodes estáNotReady;degradedquando algum node estáNotReady, algum workload ficou abaixo do desejado por mais de 5 minutos ou algum pod está emCrashLoopBackOff;healthycaso 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:NodeNotReadyePodCrashLooping(critical),PodPendingacima de 5 minutos eDeploymentReplicasUnavailable(warning),KubeletVersionSkeweContainerWithoutLimits(info). Todo alerta derivado temstate: "firing"e não carregateam: uma regra derivada não tem label de roteamento, e inventar uma aciona as pessoas erradas. A regra em si sempre dizack: "open"; quem temworkloads.writepode reconhecer um alerta ou silenciá-lo por um tempo definido, e oorbit-apiguarda 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á emalerts.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, defaultkarpenter), 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 porORBIT_NODE_HOURLY_USD(default0). O gasto é rateado entre namespaces pelo request de CPU. A cobertura de spot é a parcela de nodes em spot, lida dos labelscapacityTypedo 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:karpenterquando todos os nodes foram precificados pelo Karpenter, senãolist-price, senãoflat. 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 sejaus-east-1. Não há mês anterior para comparar, entãodeltaPcté0eforecasté 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
lowporque o uso aqui é uma amostra demetrics.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ãohigh, porqueReleasedeAvailablesã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
- Instalação: escolha um caminho em
install/README.md. - Cada variável citada acima, em uma tabela:
configuration.md. - O modelo de ameaças contra o qual esta fronteira foi desenhada:
security.md. - Cada rota, formato e limite esboçados aqui, por inteiro:
api.md. - Usuários, papéis e sessões:
identity.md; traces e APM:apm.md.