Visão geral
Documentação
Esta documentação foi escrita para que um agente de IA consiga instalar o SRE Orbit a partir dela sem nenhum humano no meio: cada valor, cada porta e cada pré-requisito está escrito. Se você encontrar um comando que não funciona como está impresso, ou um valor que não está escrito, isso é um defeito desta documentação, e não se espera que você preencha a lacuna.
Público. Dois leitores, um só conjunto de documentos: uma pessoa de engenharia de plataforma que já opera Kubernetes e um agente autônomo de código com acesso ao shell e nenhum contexto prévio deste repositório. Todo comando é copiável e colável. Todo placeholder diz, na mesma frase, exatamente como obter o valor real.
Fonte de verdade. Esta documentação descreve o produto conforme especificado em
CONTRACT.md (incluindo o Adendo v0.2: autenticação
obrigatória, uma porta de métricas isolada e um único componente exposto ao navegador; e o
Adendo v0.5: usuários, papéis, a trilha de auditoria, dashboards e APM),
CLAIMS.md (todos os números) e DESIGN.md (o
frontend). Onde esta documentação e esses arquivos divergirem, os arquivos da raiz
vencem; abra uma issue.
Leia nesta ordem
| # | Página | Para que serve |
|---|---|---|
| 1 | architecture.md | Os quatro componentes, o que conversa com o quê, a fronteira de autenticação e o que sai da sua conta (nada). Leia primeiro: todas as outras páginas pressupõem isso. |
| 2 | install/README.md | Qual dos quatro caminhos de instalação usar, e por quê. |
| 2a | install/local-k3d.md | O loop no laptop: um cluster Kubernetes descartável em um comando. Comece aqui se você está experimentando. |
| 2b | install/docker-compose.md | Host único, sem Kubernetes. O caminho mais rápido até a stack rodando. |
| 2c | install/helm.md | O caminho de produção, para qualquer cluster real. |
| 2d | install/kubectl.md | Manifestos puros, para times que não podem ou não rodam Helm. |
| 3 | configuration.md | Cada variável de ambiente, seu default e o que ela significa, em uma tabela para os quatro componentes. |
| 4 | security.md | O modelo de ameaças, o que o middleware de autenticação faz, o que as NetworkPolicies impõem e o que não impõem, e as perguntas que uma revisão de segurança vai fazer. |
| 4a | identity.md | Usuários, sessões e papéis: o primeiro administrador, como entrar pelo navegador e pelo shell, a lista fechada de permissões e onde o estado fica. |
| 4b | audit.md | O que a trilha de auditoria registra, como consultá-la e exportá-la, a retenção dela e como o endereço do cliente é determinado. |
| 5 | api.md | Cada rota, cada formato de requisição e resposta, o conjunto fechado de códigos de erro, os tipos de frame SSE e todos os limites rígidos. |
| 5a | apm.md | Como enviar traces do OpenTelemetry, as séries que o engine deriva com os nomes do Tempo, as páginas de APM e a loja de demonstração. |
| 5b | dashboards.md | Dashboards nativos e personalizados: o editor, as variáveis, o modelo JSON, a importação do Grafana e as permissões. |
| 5c | logs.md | Como pesquisar os logs que o engine armazena: como as linhas chegam, a linguagem de consulta, o histograma e as facetas, o modo ao vivo. |
| 5d | ingestion.md | Como decidir o que o engine armazena de traces e logs: taxas de amostragem, filtros de exclusão, a prévia de impacto e o salvamento conferido e auditado. |
| 5e | sql.md | SQL somente leitura sobre o parque, os custos, a trilha de auditoria, os logs, os traces e as métricas: a linguagem, cada tabela e coluna, as funções, os limites e os exemplos. |
| 5f | databases.md | Consultar os seus próprios bancos PostgreSQL e MySQL pelo editor SQL, somente leitura em três camadas: ORBIT_SEAL_KEY, o usuário somente leitura a criar, os security groups do RDS e o egress do chart. |
| 5g | terminal.md | Um shell em um pod pelo Deck: como ligar, o que fica gravado e auditado, os limites e a reprodução de uma sessão. |
| 5h | features.md | Como desligar recursos inteiros de uma instalação: as doze chaves, a trava do fornecedor, as predefinições, o que o orbit-api recusa e a auditoria. |
| 6 | operations.md | O que observar depois que estiver rodando: sinais de saturação, formato de log, semântica das probes, backup dos dados do orbit-api e retenção da auditoria. |
| 6a | alerts.md | As seis regras de alerta derivadas, uma seção de runbook para cada uma, e como reconhecer e silenciar os alertas. |
| 7 | troubleshooting.md | Sintoma → causa → correção, incluindo os modos de falha em que já caímos. |
| 8 | benchmark.md | A comparação de disco, ingest, RAM e latência de consulta contra o Prometheus e o VictoriaMetrics: os métodos como foram executados, os scripts que os reproduzem e os números medidos, com as derrotas. |
| 8a | orbit-stack.md | O engine de telemetria: o que ele armazena e como, a compactação, cada endpoint, o PromQL que ele responde, sua configuração e como apontar um agente para ele. |
| 9 | changelog.md | O que mudou, versão de contrato por versão de contrato. |
| 10 | status.md | Um retrato honesto, de agora, do que está implementado contra o que está apenas esboçado. |
Se você é um agente instalando isto sem supervisão
- Leia
architecture.mduma vez, por inteiro, antes de tocar em um terminal. - Escolha um caminho em
install/com base no que já está disponível neste ambiente (install/README.mdtem a tabela de decisão). Não misture caminhos. - Siga a sequência de comandos daquela página exatamente, na ordem. Todo comando é copiável e colável de forma independente; nenhum depende de estado de shell vindo de fora da página.
- Use a seção "Verifique" da própria página para confirmar a saúde antes de declarar
sucesso. Um contêiner que inicia ainda não é um contêiner que está
pronto: os dois têm endpoints HTTP diferentes e esta documentação nunca confunde os
dois. Depois, faça login: toda página do Deck e toda rota do
orbit-api, exceto umas poucas, precisam de um usuário, eidentity.md→ "O primeiro administrador" explica como o primeiro é criado no seu caminho. - Se um comando falhar, vá para
troubleshooting.mdantes de mudar qualquer coisa que a página mandou rodar literalmente. A maioria das falhas de primeira execução é uma das quatro entradas no topo daquela página. - Gere os segredos você mesmo. Nada neste repositório entrega uma credencial pronta, e
toda página que precisa de uma (
ORBIT_AUTH_TOKEN,NOCTURNE_AUTH_TOKEN,NOCTURNE_API_KEY,ORBIT_STACK_AUTH_TOKEN,WEB_AUTH_VERIFIERe os opcionaisORBIT_SESSION_SECRETeORBIT_ADMIN_PASSWORD_VERIFIER) diz exatamente qual comando a produz.
O que é este produto, em um parágrafo
SRE Orbit são quatro contêineres que você roda na sua própria conta: web (o site
institucional e o console Orbit Deck), orbit-api (o backend do Deck: clusters,
workloads, telemetria, FinOps, e os usuários, papéis, dashboards e a trilha de auditoria que
ele guarda), nocturne (o assistente de IA, agnóstico de provedor, transmitindo por SSE) e
orbit-stack (o engine de telemetria: remote-write e traces do OpenTelemetry na entrada,
PromQL e APM na saída). Não mantemos nenhum backend hospedado, e nada no produto precisa de um.
architecture.md desenha o quadro inteiro, incluindo a única decisão de arquitetura da
qual todas as outras páginas dependem: o navegador conversa com o web, e somente com
o web.
Convenções usadas em toda a documentação
- Os comandos são mostrados exatamente como digitados, com
$implícito e nunca impresso literalmente. Copie a linha a partir do fim de qualquer comentário. - Marcadores
CHANGEMEnão aparecem aqui sem definição. Todo valor de que um comando precisa é dado de forma explícita ou gerado pelo comando imediatamente anterior. - Os nomes das variáveis de ambiente batem byte a byte com o
CONTRACT.md, incluindo os prefixosORBIT_/NOCTURNE_/WEB_. Um nome sem um desses prefixos não é uma variável real que este produto lê, exceto as da própria plataforma (PORT,NODE_ENV,HOSTNAME) e os nomes da downward API que a loja de demonstração lê (POD_NAME,POD_NAMESPACE,NODE_NAME); oconfiguration.mde oorbit-stack.mdlistam todos eles. - Os números que descrevem o desempenho do produto (disco, ingest, RAM, latência) vêm do
CLAIMS.md, que cita a execução de benchmark por trás de cada um, ou, nobenchmark.mde onde uma página remete a ele, do relatório emservices/rust/orbit-stack/bench/runs/que a frase nomeia, como o próprioCLAIMS.mdpermite. Nenhum outro número é impresso: nem um benchmark Go, nem uma execução do próprio builder. Toda razão carrega o escopo que oCLAIMS.mdou o relatório dela lhe dá.