Referência
Configuração
Cada variável de ambiente que este produto lê, seu default e o que ela significa. Esta é
a lista completa: um nome que não está nela não faz parte do contrato, não importa
onde você o tenha visto. Fonte: CONTRACT.md e seus adendos, e os
pacotes de configuração de cada serviço (internal/config), que se recusam a iniciar
diante de um valor que não conseguem interpretar, em vez de cair num default.
Três escopos importam, e as tabelas abaixo nomeiam um por linha:
- build-time: gravado na imagem no momento do
docker build. Mudá-lo em um contêiner em execução não faz nada; é preciso reconstruir. - runtime: lido do ambiente do processo na inicialização (ou, para alguns valores dos serviços de backend, mantido em cache com renovação limitada). Mudá-lo significa reiniciar o contêiner/pod, não reconstruir.
- runtime, apenas no servidor: runtime e nunca enviado a um navegador. Este
escopo só existe no
web; o proxy do Adendo v0.2 existe para mantê-lo lá.
web
| Variável | Default | Escopo | Significado |
|---|---|---|---|
NEXT_PUBLIC_DEMO_MODE | true | build-time | Serve os dados de demonstração embutidos; o Orbit Deck não precisa de backend algum. O next build o embute no bundle do navegador: defina com --build-arg, nunca no docker run/na criação do pod. |
PORT | 3000 | runtime | Porta de escuta do servidor standalone do Next.js. |
NODE_ENV | production | runtime | Flag padrão de modo do Node.js; a imagem entregue sempre roda em production. |
HOSTNAME | 0.0.0.0 | runtime | Endereço de bind do servidor standalone: 0.0.0.0, para que seja alcançável de fora do namespace de rede do próprio contêiner/pod. |
MALLOC_ARENA_MAX | 1 (definido na imagem) | runtime | Arenas do malloc da glibc para o servidor Next.js. Uma por thread retinha dezenas de MiB depois de um pico de tráfego, e um pod limitado a um núcleo não tem contenção a evitar. |
MALLOC_MMAP_THRESHOLD_ | 65536 (definido na imagem) | runtime | Alocações de pelo menos esse número de bytes vão direto para mmap, de modo que liberar uma devolve a memória ao nó. Defini-lo também impede a glibc de elevar esse limite depois da primeira liberação grande. |
ORBIT_API_URL | http://orbit-api:8080 (compose) / gerado por template para o Service interno do cluster (Helm/kubectl) | runtime, apenas no servidor | URL base que o servidor Next.js usa para alcançar o orbit-api. Nunca chega ao navegador; veja architecture.md. |
ORBIT_AUTH_TOKEN | vazio | runtime, apenas no servidor | O bearer que o servidor do web anexa a cada chamada /api/* repassada. Lido de um Secret; deve bater com o ORBIT_AUTH_TOKEN do próprio orbit-api. |
WEB_AUTH_MODE | vazio | runtime | basic liga a autenticação HTTP Basic própria do web na frente de toda rota; vazio ou disabled a deixa desligada; qualquer outro valor falha fechado. Veja security.md. |
WEB_AUTH_USER | vazio | runtime, apenas no servidor | O único nome de usuário que a autenticação Basic do web aceita; sem dois-pontos. Obrigatório quando WEB_AUTH_MODE=basic. |
WEB_AUTH_VERIFIER | vazio | runtime, apenas no servidor | Um verificador PBKDF2 da senha (nunca a senha em si), gerado por node apps/web/scripts/hash-password.mjs. Obrigatório quando WEB_AUTH_MODE=basic; veja security.md. |
WEB_TRUST_PROXY | false; os manifestos puros definem true, e o chart o deriva de ingress.enabled quando vazio | runtime | true diz que um proxy de borda na frente do web escreve o X-Forwarded-For, e só então o web repassa esse cabeçalho ao orbit-api, que tira dele o endereço do cliente registrado na trilha de auditoria e o usa como chave dos seus limites por cliente. true sem nada na frente do web deixa um navegador escolher o endereço sob o qual é registrado. Veja audit.md → "Como o IP do cliente é determinado". |
ORBIT_PUBLIC_URL | vazio; o chart o define no web apenas a partir de publicUrl | runtime | O endereço em que as pessoas abrem o Deck. Quando é https://..., o web considera que o navegador está em https, não importa o que diga o X-Forwarded-Proto: cookies __Host- com Secure, e https:// no snippet do MCP e nos redirect URIs de SSO, cujo host continua vindo da requisição. Serve para uma borda que reescreve esse header, como um ingress sem TLS atrás de uma CDN. Vazio, http://... ou ilegível, quem decide é o header. Uma instalação que vinha lendo http faz todo mundo entrar mais uma vez quando isto é ligado, e um navegador que chega ao Deck por http puro, fora de localhost, não consegue guardar o cookie. Não criptografa nada: veja audit.md → "Atrás de um load balancer de nuvem ou de uma CDN". |
ORBIT_DECK_WRITE_TOKEN | vazio | runtime, apenas no servidor, de um Secret (chave DECK_WRITE_TOKEN) | O token de operador que uma pessoa digita no Deck antes de uma escrita de scale ou de resources (Adendo v0.4), comparado no salto do web e nunca encaminhado. Vazio recusa toda escrita em workload com 403 writes_disabled. |
ORBIT_DECK_OPERATOR | vazio | runtime | Um label, não uma credencial: o nome de console sob o qual uma escrita em workload é registrada, ao lado do usuário logado (console na linha de log e no evento de auditoria). |
ORBIT_DECK_WRITES | vazio | runtime | session: sem ORBIT_DECK_WRITE_TOKEN, o workloads.write do usuário logado (editor, admin) substitui o token de operador nas duas escritas em workload; a prova de mesma origem, o dry-run com o diff e a trilha de auditoria continuam. O orbit-api ainda precisa de ORBIT_WRITE_ENABLED e rbac.write.enabled. Vazio mantém o token como o único caminho. |
ORBIT_CLUSTER_ID | vazio | runtime, apenas no servidor | Só no modo ao vivo: o cluster que o Deck abre quando a URL não indica nenhum. Vazio escolhe o primeiro cluster que o orbit-api listar. |
NEXT_PUBLIC_API_URL não existe neste contrato. Foi removida no Adendo v0.2: uma URL
de API definida em build e embutida no navegador era ao mesmo tempo um parâmetro de ajuste enganoso
(uma imagem por URL de API) e um caminho documentado para contornar o proxy server-side.
Se você a vir em um fork antigo ou em uma instalação desatualizada, essa instalação é
anterior ao adendo.
orbit-api
| Variável | Default | Escopo | Significado |
|---|---|---|---|
ORBIT_ADDR | :8080 | runtime | Endereço de escuta da API. |
ORBIT_LOG_LEVEL | info | runtime | debug | info | warn | error. |
ORBIT_LOG_PROBES | false | runtime | Registra as requisições a /healthz, /readyz e /metrics em info; caso contrário, só em debug. |
ORBIT_CORS_ORIGINS | http://localhost:3000 | runtime | Origens permitidas, separadas por vírgula. No chart Helm, um valor vazio é derivado de ingress.host + ingress.tls.enabled (https://sreorbit.example.com, nunca um esquema que o ingress não sirva); defina um valor literal apenas para acrescentar origens extras. |
ORBIT_DEMO_DATA | true | runtime | true = parque de demonstração determinístico, sem necessidade de acesso a cluster, e, numa primeira inicialização sem nenhum usuário e sem par de administrador, as três contas de demonstração (identity.md). false = a fonte Kubernetes ao vivo, lendo clusters reais via ORBIT_KUBECONFIG ou credenciais dentro do cluster. ORBIT_AUTH_MODE=disabled é recusado neste modo (abaixo): uma porta sem autenticação apontada para um cluster real não é uma demonstração local. |
ORBIT_NOCTURNE_URL | http://nocturne:8081 | runtime | URL base do reverse proxy interno para o nocturne. |
ORBIT_NOCTURNE_TOKEN | na falta dela, NOCTURNE_AUTH_TOKEN | runtime, de um Secret | O bearer que o proxy anexa no salto até o nocturne. Qualquer um dos dois nomes funciona, então os dois manifestos não têm como divergir. |
ORBIT_STREAM_TIMEOUT | 180s | runtime | Quanto tempo um stream do nocturne pode durar no proxy. Mantenha acima de NOCTURNE_TIMEOUT mais 30s. |
ORBIT_KUBECONFIG | vazio | runtime | Caminho para um kubeconfig, lido apenas quando ORBIT_DEMO_DATA=false. Vazio significa credenciais dentro do cluster, o que exige o token projetado da ServiceAccount do pod e um role vinculado a ele: components.orbit-api.rbac.enabled no chart, deploy/kubectl/15-rbac-orbit-api.yaml nos manifestos puros. Quando um caminho é informado, cada contexto do arquivo vira um cluster e o {id} em /api/v1/clusters/{id} é o nome daquele contexto em minúsculas com todo caractere fora de [a-z0-9-] substituído por - (um ARN de EKS vira arn-aws-eks-us-east-1-...). Dois contextos que sanitizam para o mesmo id são uma falha de inicialização. Monte o arquivo como volume; nunca cole um dentro de uma variável de ambiente ou de um manifesto. |
ORBIT_CLUSTER_ID | local | runtime | O {id} do cluster dentro do qual o orbit-api está rodando, usado apenas quando ORBIT_KUBECONFIG está vazia, porque um pod dentro do cluster não tem nome de contexto do qual derivá-lo. Deve casar com [a-z0-9-]{1,128}; qualquer outra coisa impede a inicialização. |
ORBIT_CLUSTER_NAME | ORBIT_CLUSTER_ID | runtime | Nome de exibição desse cluster. Cosmético. |
ORBIT_STACK_URL | vazio | runtime | URL base de uma API HTTP compatível com Prometheus (orbit-stack) por trás de GET /api/v1/query_range, das leituras de labels e de séries dos dashboards e de toda rota de APM. Vazia: query_range responde uma série vazia com a unidade correta, uma expressão PromQL ad hoc (todo painel de dashboard é uma) é recusada com invalid_request, as rotas de APM e de metadados respondem 503 not_ready, e /readyz não a verifica. Definida: o PromQL ad hoc roda no engine também com dados de demonstração, e /readyz também checa o /healthz dela, então o orbit-api fica NotReady até o engine responder. No chart Helm, um valor vazio é derivado para http://<fullname>-orbit-stack.<namespace>.svc.cluster.local:8082, do mesmo jeito que ORBIT_NOCTURNE_URL. |
ORBIT_STACK_TOKEN | vazio | runtime, de um Secret | Bearer anexado a cada chamada para ORBIT_STACK_URL. Opcional: o engine pode não precisar de nenhum. Defini-lo com ORBIT_STACK_URL vazia impede a inicialização, porque nada o carregaria. Ocultado em toda linha de log. |
ORBIT_USAGE_SOURCE | auto | runtime | De onde vem o uso de CPU e memória ao vivo. auto: metrics.k8s.io enquanto o cluster o servir, e o engine quando não servir. orbit-stack: sempre o engine, o que exige ORBIT_STACK_URL. |
ORBIT_CACHE_MAX_AGE | 90s | runtime | Quanto tempo o cache de informers da fonte ao vivo pode passar sem que os watches dele avancem antes que o /readyz o declare desatualizado nas linhas de cache. Um cache já preenchido continua servindo, e o pod continua pronto, enquanto está desatualizado; só um cache que ainda não foi preenchido, ou um servidor de API que não responde, faz o /readyz responder 503. Aumente o valor para um servidor de API lento ou sobrecarregado. |
ORBIT_WRITE_ENABLED | false | runtime | true permite que as rotas de scale e de resources alterem o cluster (Adendo v0.4), junto com a ClusterRole de escrita que o chart só renderiza com components.orbit-api.rbac.write.enabled. Qualquer valor diferente de true responde 403 writes_disabled. |
ORBIT_SECRETS_READ | false | runtime | true permite que a visão de configuração leia os Secrets que o template de um workload referencia, com o get em secrets (nunca list nem watch) que o chart só concede com components.orbit-api.rbac.secrets.enabled (Adendo v0.11). Desligado, uma referência a Secret aparece como not-read e o valor dela não pode ser revelado. O chart define a variável a partir desse mesmo valor, no pod; components.orbit-api.env a recusa. |
ORBIT_KARPENTER_NAMESPACE | karpenter | runtime | Onde o Karpenter roda. O FinOps precifica cada node pelas estimativas da AWS do Karpenter (on-demand e spot, por zona), lidas a cada 10 minutos na porta http-metrics dos pods dele; a NetworkPolicy do chart abre só essa porta, e só quando o namespace existe. none não lê nada: só os preços da tabela embutida. |
ORBIT_NODE_HOURLY_USD | 0 | runtime | USD por hora para um node cujo tipo de instância não está na tabela embutida de preços on-demand do orbit-api (veja architecture.md → modo ao vivo). Qualquer node fora do EC2, k3s incluso, cai aqui. 0 conta esse node como gratuito, o que aparece como uma fatura implausivelmente pequena em vez de uma fatura inventada. Deve ser um número não negativo. |
ORBIT_RECOMMENDATIONS_REFRESH | 5m | runtime | De quanto em quanto tempo as recomendações do Deck são recalculadas em segundo plano, por cluster; as requisições recebem o último resultado, então uma recomendação tem no máximo um intervalo de idade. Uma execução que falhou não é servida: a próxima requisição calcula de novo. 0 calcula a cada requisição, como fazia o original em Go (tag go-oracle). Qualquer valor que não seja 0 ou uma duração no formato Go de 1s ou mais impede a inicialização. |
ORBIT_TRUSTED_PROXIES | vazio | runtime | CIDRs (ou endereços isolados), separados por vírgula, dos proxies entre o web e o orbit-api cujo X-Forwarded-For é tido como confiável: um sidecar de mesh, um gateway interno. Não o próprio web: uma requisição que carrega o bearer do próprio orbit-api vem do web, e o X-Forwarded-For dela já é tido como confiável (Adendo v0.5). O endereço do cliente, para a trilha de auditoria e para todo limite por cliente, é o salto mais próximo nesse cabeçalho que não esteja nesta lista. Vazio é o valor certo para todo caminho de instalação entregue; um CIDR de pods aqui também faria pular o endereço do próprio ingress. Uma entrada que não seja um endereço impede a inicialização. |
ORBIT_SHUTDOWN_GRACE | 180s | runtime | Orçamento de desligamento gracioso, alinhado ao do nocturne para que uma resposta repassada (até 150s de streaming) consiga terminar; qualquer stream repassado ainda aberto 5s antes do fim do orçamento é fechado com um frame event: done carregando finishReason: "shutdown". Precisa ficar abaixo do período de graça de terminação do próprio pod/contêiner (200s em todos os manifestos entregues) ou o SIGKILL vence a corrida; veja operations.md. (A tabela base do CONTRACT.md diz 15s; o adendo e os defaults entregues a substituem.) |
ORBIT_AUTH_MODE | static | runtime | static | oidc | disabled. Veja "Modos de autenticação" abaixo. |
ORBIT_AUTH_TOKEN | vazio | runtime, de um Secret | Obrigatório, ≥32 bytes, quando o modo é static. Caso contrário, o serviço se recusa a iniciar. |
ORBIT_OIDC_ISSUER | vazio | runtime | Obrigatório quando o modo é oidc. |
ORBIT_OIDC_AUDIENCE | vazio | runtime | Obrigatório quando o modo é oidc. |
ORBIT_METRICS_ADDR | :9090 | runtime | Listener separado para /metrics (Adendo v0.2). Nunca o listener da API; nunca roteado por um ingress. |
ORBIT_CONTACT_WEBHOOK_URL | vazio | runtime, de um Secret | Opcional. Todo lead que o formulário de contato do site grava (em ORBIT_DATA_DIR/leads, listado em /deck/admin/leads) também é enviado por POST para cá, como JSON, com três novas tentativas em segundo plano; uma falha fica registrada em log e não perde nada. Uma URL de webhook costuma carregar o próprio token: nunca registrada em log, nunca num arquivo versionado. Com NetworkPolicy ligada, o orbit-api também precisa de components.orbit-api.networkPolicy.allowInternetEgress. |
Identidade (Adendo v0.5)
| Variável | Default | Escopo | Significado |
|---|---|---|---|
ORBIT_DATA_DIR | /var/lib/sreorbit | runtime | Usuários, papéis, sessões, dashboards, reconhecimentos de alertas, leads e a trilha de auditoria, em arquivos. Precisa ser gravável, ou o orbit-api se recusa a iniciar. Um único escritor: rode uma réplica. No chart, um PVC com components.orbit-api.persistence.enabled (mantenha mountPath igual a este valor), e um emptyDir caso contrário; no compose, o volume nomeado orbit-api-data. Veja identity.md → "Onde o estado fica". |
ORBIT_SESSION_SECRET | vazio | runtime, de um Secret | Chave HMAC que assina os tokens de sessão, com 32 bytes ou mais (openssl rand -base64 48); uma mais curta impede a inicialização. Vazia: uma chave de 32 bytes é gerada uma única vez em ORBIT_DATA_DIR/session.key. Trocá-la encerra todas as sessões. Defina-a quando os backups do diretório de dados não puderem levar junto a chave de assinatura. |
ORBIT_ADMIN_USER | vazio | runtime, de um Secret | O nome de usuário do primeiro administrador, criado na inicialização só quando não existe nenhum usuário; ignorado dali em diante. Convertido para minúsculas e, depois, validado contra [a-z0-9][a-z0-9._-]{0,31}. Defina junto com a próxima, ou nenhuma das duas: só uma delas impede a inicialização. |
ORBIT_ADMIN_PASSWORD_VERIFIER | vazio | runtime, de um Secret | A senha desse administrador como um verificador PBKDF2 (node apps/web/scripts/hash-password.mjs < admin-password), nunca a senha em si. Um verificador malformado impede a inicialização. |
ORBIT_AUDIT_RETENTION | 90d | runtime | Por quanto tempo a trilha de auditoria guarda um dia: em dias (90d, 365d) ou uma duração Go de 24h ou mais. Veja audit.md. |
ORBIT_CHAT_RETENTION | 5d | runtime | Por quanto tempo uma conversa com o Nocturne é guardada depois da última mensagem: em dias (5d) ou uma duração Go de 1h a 90d. Uma varredura de hora em hora apaga do disco as expiradas, inclusive as de usuários que nunca mais entram. |
Sementes de single sign-on (Adendos v0.8 e v0.19)
Os dois provedores normalmente são configurados no console, em Admin > Integrations. Estas
variáveis semeiam um deles apenas enquanto o armazenamento não tem documento de
configuração para ele; a partir do primeiro salvamento no console, vale o que está no
console. Sem elas, o provedor fica desligado. Veja identity.md → "Single sign-on".
| Variável | Default | Escopo | Significado |
|---|---|---|---|
ORBIT_SSO_GOOGLE_CLIENT_ID | vazio | runtime | O client ID da aplicação Web no Google, <digits>-<id>.apps.googleusercontent.com. Defina junto com as duas seguintes, ou nenhuma das três: qualquer combinação intermediária impede a inicialização. |
ORBIT_SSO_GOOGLE_CLIENT_SECRET | vazio | runtime, de um Secret | O client secret correspondente. Nunca vai para o log nem aparece numa leitura. |
ORBIT_SSO_ALLOWED_DOMAINS | vazio | runtime | Os domínios do Workspace que o login com Google aceita, separados por vírgula; gmail.com é recusado. |
ORBIT_SSO_DEFAULT_ROLE | viewer | runtime | O papel do primeiro login com Google: viewer ou editor. |
ORBIT_SSO_OIDC_ISSUER | vazio | runtime | O emissor (issuer) do provedor OpenID Connect, em https, exatamente como o documento de discovery dele o nomeia. Defina junto com as duas seguintes, ou nenhuma das três: qualquer combinação intermediária impede a inicialização, assim como qualquer outra ORBIT_SSO_OIDC_* sem elas. |
ORBIT_SSO_OIDC_CLIENT_ID | vazio | runtime | O client ID nesse provedor. |
ORBIT_SSO_OIDC_CLIENT_SECRET | vazio | runtime, de um Secret | O client secret correspondente (secrets.ssoOidcClientSecret no chart). Nunca vai para o log nem aparece numa leitura. |
ORBIT_SSO_OIDC_DISPLAY_NAME | SSO | runtime | O nome exibido em "Entrar com ..." no login e o nome do provedor na trilha de auditoria. No máximo 40 caracteres. |
ORBIT_SSO_OIDC_SCOPES | openid email profile | runtime | Separados por espaço; precisa incluir openid. |
ORBIT_SSO_OIDC_ALLOWED_DOMAINS | vazio | runtime | Domínios de e-mail aceitos, separados por vírgula. Vazio aceita qualquer endereço que o provedor garanta. |
ORBIT_SSO_OIDC_EMAIL_CLAIM | email | runtime | A claim de primeiro nível do ID token que traz o endereço. |
ORBIT_SSO_OIDC_GROUPS_CLAIM | groups | runtime | A claim de primeiro nível do ID token que traz os grupos. |
ORBIT_SSO_OIDC_GROUP_ROLES | vazio | runtime | Pares group=role separados por ; ou por quebras de linha, em ordem, e a primeira correspondência vence; cada par é dividido no último =, então um DN de LDAP funciona como grupo. Um papel inexistente recusa o login da pessoa (role_missing). |
ORBIT_SSO_OIDC_DEFAULT_ROLE | viewer | runtime | O papel de quem nenhum grupo mapeia: viewer, editor ou deny. deny exige ao menos um grupo mapeado. |
SSL_CERT_FILE | não definido | runtime | Um pacote PEM em que o orbit-api confia no lugar das raízes da imagem, para um provedor atrás de uma CA privada. Inclua nele as raízes públicas quando o Google ou um provedor hospedado ainda precisarem ser verificados. |
nocturne
| Variável | Default | Escopo | Significado |
|---|---|---|---|
NOCTURNE_ADDR | :8081 | runtime | Endereço de escuta da API. |
NOCTURNE_LOG_LEVEL | info | runtime | Nível de log. |
NOCTURNE_LOG_PROBES | false | runtime | Registra as requisições de probe e de /metrics em info. |
NOCTURNE_PROVIDER | mock | runtime | mock | openai | openai-responses | anthropic. mock não precisa de credencial e não faz chamada de saída, então a demonstração roda a seco. openai-responses é a Responses API da OpenAI: esforço de raciocínio até max, o raciocínio do modelo preservado entre os turnos de ferramenta, store=false. anthropic é a Messages API (ex.: claude-sonnet-5-5): um esforço definido liga o pensamento adaptativo, os blocos de pensamento voltam com a assinatura entre os turnos de ferramenta, ferramentas e prompt de sistema ficam em cache entre conversas e o fim da conversa entre os passos de ferramenta, e na Claude API uma recusa é refeita no modelo de fallback padrão da Anthropic (beta server-side-fallback-2026-07-01). Uma recusa encerra a resposta com finish refusal. |
NOCTURNE_BASE_URL | vazio | runtime | URL base compatível com OpenAI, por exemplo https://api.openai.com/v1. Obrigatória quando o provedor é openai ou openai-responses. |
NOCTURNE_API_KEY | vazio | runtime, de um Secret | Credencial do provedor. Nunca registrada em log. Vazia é válida quando o provedor é mock. |
NOCTURNE_REASONING_MODEL | vazio | runtime | Id do modelo do tier reasoning (análise, causa raiz, planos de FinOps). |
NOCTURNE_FAST_MODEL | vazio | runtime | Id do modelo do tier fast (ajuda sobre o produto, respostas curtas). |
NOCTURNE_REASONING_EFFORT | vazio | runtime | Esforço de raciocínio do tier reasoning: none | minimal | low | medium | high | xhigh | max. Vazio não envia nenhum. Quais valores um modelo aceita é o provedor quem diz (chat completions para em xhigh). Com anthropic, none e minimal enviam low. |
NOCTURNE_FAST_EFFORT | vazio | runtime | O mesmo para o tier fast. |
NOCTURNE_MAX_TOKENS | 2048 | runtime | Teto da resposta, tokens de raciocínio incluídos: aumente junto com um esforço alto. |
NOCTURNE_TIMEOUT | 120s | runtime | Timeout do provedor upstream. O prazo de escrita do stream é esse valor mais 30s, então deixe ORBIT_STREAM_TIMEOUT acima dos dois. |
NOCTURNE_TRIAGE_URL | vazio | runtime | Sistema 1: um classificador tipado (POST /v1/systemone, a API do Jev da TypeSafe) que roteia as perguntas que as palavras-chave não pegam e ranqueia a varredura de saúde com que uma pergunta de queda começa. Vazio desliga. |
NOCTURNE_TRIAGE_API_KEY | vazio | runtime, de um Secret | A credencial dele. Obrigatória junto com a URL. Nunca registrada em log. |
NOCTURNE_TRIAGE_MODEL | vazio | runtime | O id do modelo dele, por exemplo uma versão fixada. Obrigatório junto com a URL. |
NOCTURNE_ORBIT_URL | vazio | runtime | A URL base do orbit-api, que as ferramentas de cluster leem. Vazia, o assistente roda sem ferramentas. |
NOCTURNE_ORBIT_TOKEN | na falta dela, ORBIT_AUTH_TOKEN | runtime, de um Secret | O bearer que as ferramentas apresentam ao orbit-api, ao lado da sessão do usuário que fez a pergunta. Nunca registrado em log. |
NOCTURNE_TOOL_TIMEOUT | 10s | runtime | Uma chamada de ferramenta, incluindo a ida ao orbit-api. Um valor maior que NOCTURNE_TIMEOUT impede a inicialização. |
NOCTURNE_MAX_TOOL_STEPS | 6 | runtime | Turnos do modelo que podem chamar ferramentas numa mesma resposta, de 1 a 20. |
NOCTURNE_TOOL_MAX_BYTES | 8000 | runtime | O máximo de um resultado de ferramenta que o modelo chega a ler, de 1.024 a 65.536 bytes. |
NOCTURNE_TRUSTED_PROXIES | vazio | runtime | Mesma semântica de ORBIT_TRUSTED_PROXIES. O orbit-api é o único peer do nocturne e repassa a cadeia que enxergou, então nomeie o mesmo CIDR aqui. |
NOCTURNE_AUTH_MODE | static | runtime | Mesma semântica de ORBIT_AUTH_MODE. O nocturne só é alcançável pelo orbit-api na rede, mas "inalcançável" é um controle de rede, não de autenticação, e é o componente que carrega o gasto com modelos. |
NOCTURNE_AUTH_TOKEN | vazio | runtime, de um Secret | Obrigatório, ≥32 bytes, quando o modo é static. |
NOCTURNE_OIDC_ISSUER | vazio | runtime | Obrigatório quando o modo é oidc. |
NOCTURNE_OIDC_AUDIENCE | vazio | runtime | Obrigatório quando o modo é oidc. |
NOCTURNE_METRICS_ADDR | :9090 | runtime | Listener separado para /metrics (Adendo v0.2). |
NOCTURNE_SHUTDOWN_GRACE | 180s | runtime | Orçamento de desligamento gracioso, igual ao do orbit-api, para que um stream SSE em andamento tenha tempo de drenar. Um drain que estoura registra shutdown incomplete e sai com código 0; isso nunca é reportado como falha de inicialização. |
ORBIT_DEMO_DATA | true | runtime | Lida também pelo nocturne, com o mesmo significado que tem no orbit-api: false recusa NOCTURNE_AUTH_MODE=disabled. |
orbit-stack
O chart Helm define ORBIT_STACK_QUERY_RPM como 60000 e ORBIT_STACK_QUERY_BURST como 3000:
todo usuário do Deck lê pelo orbit-api, um só endereço de cliente, e uma página de traces de
30 dias faz cerca de cem leituras.
Cada variável do engine de telemetria, com seu default e significado, está em
orbit-stack.md, para que a página do engine se mantenha
autocontida: ORBIT_STACK_ADDR (:8082), ORBIT_STACK_METRICS_ADDR (:9090),
ORBIT_STACK_LOG_LEVEL, ORBIT_STACK_LOG_PROBES, ORBIT_STACK_DATA_DIR (/data, um
volume), ORBIT_STACK_RETENTION (15d), ORBIT_STACK_BLOCK_DURATION (2h),
ORBIT_STACK_COMPRESSION (better), ORBIT_STACK_BLOCK_CACHE_BYTES,
ORBIT_STACK_HEAD_CHUNK_SAMPLES (120), ORBIT_STACK_MAX_SERIES (0),
ORBIT_STACK_MAX_LABELS_PER_SERIES (64), ORBIT_STACK_MAX_LABEL_NAME_LEN (256),
ORBIT_STACK_MAX_LABEL_VALUE_LEN (4096), ORBIT_STACK_MAX_INDEX_BYTES,
ORBIT_STACK_QUERY_TIMEOUT (30s), ORBIT_STACK_QUERY_MAX_SAMPLES, ORBIT_STACK_QUERY_TURNS (0),
ORBIT_STACK_QUERY_RPM (3000), ORBIT_STACK_QUERY_BURST (300),
ORBIT_STACK_MAX_BODY_BYTES, ORBIT_STACK_AUTH_MODE (static),
ORBIT_STACK_AUTH_TOKEN (de um Secret, ≥ 32 bytes), ORBIT_STACK_TRUSTED_PROXIES,
ORBIT_STACK_SHUTDOWN_GRACE (30s) e, para traces, ORBIT_STACK_TRACE_RETENTION (7d),
ORBIT_STACK_TRACE_HEAD_BYTES (64MiB), ORBIT_STACK_TRACE_MAX_BYTES (5MiB, um trace;
os spans que passam disso são recusados) e ORBIT_STACK_TRACE_GRAPH_PENDING (100000, spans
do service graph à espera de par), que o apm.md explica. O
orbit-api o alcança com ORBIT_STACK_URL e ORBIT_STACK_TOKEN (a mesma chave do
Secret, ORBIT_STACK_AUTH_TOKEN, lida sob um segundo nome, como acontece com
ORBIT_NOCTURNE_TOKEN).
orbit-shop, a loja de demonstração
Os serviços sintéticos que dão traces reais ao APM (apm.md → "A loja de
demonstração"), entregues na imagem do orbit-stack como /orbit-shop. Não fazem parte
de uma instalação de produção.
| Variável ou flag | Default | Significado |
|---|---|---|
ORBIT_SHOP_OTLP | vazio, obrigatória | A URL base do engine, http://orbit-stack:8082; os spans vão para o /v1/traces dele. |
ORBIT_SHOP_OTLP_TOKEN | vazio | O bearer do engine, ORBIT_STACK_AUTH_TOKEN, quando a autenticação dele é static. |
ORBIT_SHOP_URL_<SERVICE> | vazio | No modo --service, onde cada um dos outros serviços responde: ORBIT_SHOP_URL_API_GATEWAY, ORBIT_SHOP_URL_CATALOG e assim por diante, com o nome em maiúsculas e - trocado por _. |
POD_NAME, POD_NAMESPACE, NODE_NAME | o nome do serviço, shop, unknown | O recurso do span, preenchido pela downward API. |
PORT | 8080 | A porta de escuta no modo --service. |
--all / --service NAME | nenhum | Todos os serviços num só processo em 127.0.0.1, a partir de --port-base (padrão 18110), ou um único serviço (loadgen só para a carga). Exatamente um dos dois. |
--rps | 5 | Requisições por segundo que o gerador de carga envia, de 0 a 1.000. O compose lê o valor de ORBIT_SHOP_RPS, e o chart, de demo.shop.rps. |
Modos de autenticação
Definidos por ORBIT_AUTH_MODE / NOCTURNE_AUTH_MODE, independentemente por serviço (na
prática, rode os dois do mesmo jeito):
| Modo | Quando usar | Do que precisa |
|---|---|---|
static (default) | Uma credencial compartilhada, o caso comum de uma instalação auto-hospedada. | ORBIT_AUTH_TOKEN / NOCTURNE_AUTH_TOKEN, ≥32 bytes. |
oidc | Você já opera um provedor de identidade e quer identidade por chamador em vez de um segredo compartilhado. | <PREFIX>_OIDC_ISSUER e <PREFIX>_OIDC_AUDIENCE; o JWKS do emissor precisa ser alcançável a partir do pod. |
disabled | Apenas uma demonstração em laptop. | Nada, e precisa continuar assim. Recusado de imediato quando ORBIT_DEMO_DATA=false, para que não fique ligado por acidente contra um cluster real. |
Gerando um token estático
ORBIT_AUTH_TOKEN e NOCTURNE_AUTH_TOKEN são bearers compartilhados que você gera;
nada neste repositório entrega um pronto. A exigência é "≥32 bytes"; o comando abaixo
produz uma string hexadecimal de 64 caracteres (32 bytes de entropia real, codificados em
hexadecimal para que nunca precisem de aspas no shell):
openssl rand -hex 32Rode-o três vezes: orbit-api, nocturne e orbit-stack precisam cada um do seu
próprio token, e o web precisa de uma cópia do token do orbit-api (é o bearer que o
servidor do web anexa quando faz proxy de /api/*). Onde cada um entra depende do
caminho de instalação; veja a seção "Secrets" de
install/docker-compose.md,
install/helm.md ou install/kubectl.md.
Dois segredos opcionais pertencem à identidade, não a um salto entre serviços:
ORBIT_SESSION_SECRET (openssl rand -base64 48) e o verificador do primeiro
administrador, que a seção identity.md → "O primeiro administrador"
ensina a gerar.
Nunca versione um token gerado. Nunca coloque um em um arquivo de values, em um ConfigMap
ou em um default do Chart.yaml. CONTRACT.md: "Secrets are referenced, never embedded in a chart default" (Secrets são
referenciados, nunca embutidos em um default de chart).
demo contra live: duas flags diferentes
NEXT_PUBLIC_DEMO_MODE (no web, build-time) e ORBIT_DEMO_DATA (no orbit-api,
runtime) parecem a mesma flag e não são:
NEXT_PUBLIC_DEMO_MODE=truesignifica que a UI do Orbit Deck lê os próprios dados sintéticos (apps/web/src/lib/demo-estate.ts) diretamente, sem nunca chamar oorbit-api.ORBIT_DEMO_DATA=truesignifica que o próprioorbit-apiserve um parque de demonstração determinístico em vez de consultar um cluster ao vivo, independentemente de alguém estar chamando-o, e cria as três contas de demonstração numa primeira inicialização sem nenhum usuário.falseseleciona a fonte ao vivo (services/rust/orbit-api/src/live.rs), que precisa de credenciais para pelo menos um cluster (vejaORBIT_KUBECONFIG) e se recusa a iniciar sem elas.
Definir uma sem a outra é uma configuração válida, porém confusa (o web nunca chama o
orbit-api, não importa o que o orbit-api teria devolvido). Defina as duas juntas. Veja
architecture.md → "O caminho do dado de uma métrica, do ingest ao pixel" para saber
exatamente o que cada combinação faz.
Portas, os quatro componentes, uma tabela
| Componente | Porta da API | Porta de métricas | Exposto pelo ingress padrão? |
|---|---|---|---|
web | 3000 | nenhuma (o Next.js não serve /metrics) | Sim, o único |
orbit-api | 8080 | 9090 | Não (repassado pelo web) |
nocturne | 8081 | 9090 | Não (repassado pelo orbit-api; não existe regra de ingress alguma para ele) |
orbit-stack | 8082 | 9090 | Não (consultado pelo orbit-api; escrito pelos agentes dentro do cluster; nenhuma regra de ingress) |
Para onde ir em seguida
- Como é, na prática, o modo de falha de cada modo de autenticação, e o modelo de ameaças
por trás destes defaults:
security.md. - A sequência exata de comandos que consome estas variáveis no seu caminho de instalação:
install/README.md.