Pular para o conteúdo

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áginaPara que serve
1architecture.mdOs 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.
2install/README.mdQual dos quatro caminhos de instalação usar, e por quê.
2ainstall/local-k3d.mdO loop no laptop: um cluster Kubernetes descartável em um comando. Comece aqui se você está experimentando.
2binstall/docker-compose.mdHost único, sem Kubernetes. O caminho mais rápido até a stack rodando.
2cinstall/helm.mdO caminho de produção, para qualquer cluster real.
2dinstall/kubectl.mdManifestos puros, para times que não podem ou não rodam Helm.
3configuration.mdCada variável de ambiente, seu default e o que ela significa, em uma tabela para os quatro componentes.
4security.mdO 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.
4aidentity.mdUsuá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.
4baudit.mdO que a trilha de auditoria registra, como consultá-la e exportá-la, a retenção dela e como o endereço do cliente é determinado.
5api.mdCada 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.
5aapm.mdComo 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.
5bdashboards.mdDashboards nativos e personalizados: o editor, as variáveis, o modelo JSON, a importação do Grafana e as permissões.
5clogs.mdComo pesquisar os logs que o engine armazena: como as linhas chegam, a linguagem de consulta, o histograma e as facetas, o modo ao vivo.
5dingestion.mdComo 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.
5esql.mdSQL 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.
5fdatabases.mdConsultar 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.
5gterminal.mdUm shell em um pod pelo Deck: como ligar, o que fica gravado e auditado, os limites e a reprodução de uma sessão.
5hfeatures.mdComo 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.
6operations.mdO 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.
6aalerts.mdAs seis regras de alerta derivadas, uma seção de runbook para cada uma, e como reconhecer e silenciar os alertas.
7troubleshooting.mdSintoma → causa → correção, incluindo os modos de falha em que já caímos.
8benchmark.mdA 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.
8aorbit-stack.mdO 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.
9changelog.mdO que mudou, versão de contrato por versão de contrato.
10status.mdUm retrato honesto, de agora, do que está implementado contra o que está apenas esboçado.

Se você é um agente instalando isto sem supervisão

  1. Leia architecture.md uma vez, por inteiro, antes de tocar em um terminal.
  2. Escolha um caminho em install/ com base no que já está disponível neste ambiente (install/README.md tem a tabela de decisão). Não misture caminhos.
  3. 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.
  4. 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, e identity.md → "O primeiro administrador" explica como o primeiro é criado no seu caminho.
  5. Se um comando falhar, vá para troubleshooting.md antes 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.
  6. 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_VERIFIER e os opcionais ORBIT_SESSION_SECRET e ORBIT_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 CHANGEME nã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 prefixos ORBIT_ / 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); o configuration.md e o orbit-stack.md listam 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, no benchmark.md e onde uma página remete a ele, do relatório em services/rust/orbit-stack/bench/runs/ que a frase nomeia, como o próprio CLAIMS.md permite. Nenhum outro número é impresso: nem um benchmark Go, nem uma execução do próprio builder. Toda razão carrega o escopo que o CLAIMS.md ou o relatório dela lhe dá.