Pular para o conteúdo

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ávelDefaultEscopoSignificado
NEXT_PUBLIC_DEMO_MODEtruebuild-timeServe 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.
PORT3000runtimePorta de escuta do servidor standalone do Next.js.
NODE_ENVproductionruntimeFlag padrão de modo do Node.js; a imagem entregue sempre roda em production.
HOSTNAME0.0.0.0runtimeEndereç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_MAX1 (definido na imagem)runtimeArenas 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)runtimeAlocaçõ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_URLhttp://orbit-api:8080 (compose) / gerado por template para o Service interno do cluster (Helm/kubectl)runtime, apenas no servidorURL base que o servidor Next.js usa para alcançar o orbit-api. Nunca chega ao navegador; veja architecture.md.
ORBIT_AUTH_TOKENvazioruntime, apenas no servidorO 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_MODEvazioruntimebasic 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_USERvazioruntime, apenas no servidorO ú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_VERIFIERvazioruntime, apenas no servidorUm 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_PROXYfalse; os manifestos puros definem true, e o chart o deriva de ingress.enabled quando vazioruntimetrue 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_URLvazio; o chart o define no web apenas a partir de publicUrlruntimeO 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_TOKENvazioruntime, 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_OPERATORvazioruntimeUm 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_WRITESvazioruntimesession: 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_IDvazioruntime, apenas no servidorSó 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ávelDefaultEscopoSignificado
ORBIT_ADDR:8080runtimeEndereço de escuta da API.
ORBIT_LOG_LEVELinforuntimedebug | info | warn | error.
ORBIT_LOG_PROBESfalseruntimeRegistra as requisições a /healthz, /readyz e /metrics em info; caso contrário, só em debug.
ORBIT_CORS_ORIGINShttp://localhost:3000runtimeOrigens 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_DATAtrueruntimetrue = 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_URLhttp://nocturne:8081runtimeURL base do reverse proxy interno para o nocturne.
ORBIT_NOCTURNE_TOKENna falta dela, NOCTURNE_AUTH_TOKENruntime, de um SecretO 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_TIMEOUT180sruntimeQuanto tempo um stream do nocturne pode durar no proxy. Mantenha acima de NOCTURNE_TIMEOUT mais 30s.
ORBIT_KUBECONFIGvazioruntimeCaminho 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_IDlocalruntimeO {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_NAMEORBIT_CLUSTER_IDruntimeNome de exibição desse cluster. Cosmético.
ORBIT_STACK_URLvazioruntimeURL 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_TOKENvazioruntime, de um SecretBearer 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_SOURCEautoruntimeDe 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_AGE90sruntimeQuanto 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_ENABLEDfalseruntimetrue 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_READfalseruntimetrue 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_NAMESPACEkarpenterruntimeOnde 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_USD0runtimeUSD 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_REFRESH5mruntimeDe 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_PROXIESvazioruntimeCIDRs (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_GRACE180sruntimeOrç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_MODEstaticruntimestatic | oidc | disabled. Veja "Modos de autenticação" abaixo.
ORBIT_AUTH_TOKENvazioruntime, de um SecretObrigatório, ≥32 bytes, quando o modo é static. Caso contrário, o serviço se recusa a iniciar.
ORBIT_OIDC_ISSUERvazioruntimeObrigatório quando o modo é oidc.
ORBIT_OIDC_AUDIENCEvazioruntimeObrigatório quando o modo é oidc.
ORBIT_METRICS_ADDR:9090runtimeListener separado para /metrics (Adendo v0.2). Nunca o listener da API; nunca roteado por um ingress.
ORBIT_CONTACT_WEBHOOK_URLvazioruntime, de um SecretOpcional. 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ávelDefaultEscopoSignificado
ORBIT_DATA_DIR/var/lib/sreorbitruntimeUsuá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_SECRETvazioruntime, de um SecretChave 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_USERvazioruntime, de um SecretO 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_VERIFIERvazioruntime, de um SecretA 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_RETENTION90druntimePor 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_RETENTION5druntimePor 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ávelDefaultEscopoSignificado
ORBIT_SSO_GOOGLE_CLIENT_IDvazioruntimeO 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_SECRETvazioruntime, de um SecretO client secret correspondente. Nunca vai para o log nem aparece numa leitura.
ORBIT_SSO_ALLOWED_DOMAINSvazioruntimeOs domínios do Workspace que o login com Google aceita, separados por vírgula; gmail.com é recusado.
ORBIT_SSO_DEFAULT_ROLEviewerruntimeO papel do primeiro login com Google: viewer ou editor.
ORBIT_SSO_OIDC_ISSUERvazioruntimeO 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_IDvazioruntimeO client ID nesse provedor.
ORBIT_SSO_OIDC_CLIENT_SECRETvazioruntime, de um SecretO client secret correspondente (secrets.ssoOidcClientSecret no chart). Nunca vai para o log nem aparece numa leitura.
ORBIT_SSO_OIDC_DISPLAY_NAMESSOruntimeO nome exibido em "Entrar com ..." no login e o nome do provedor na trilha de auditoria. No máximo 40 caracteres.
ORBIT_SSO_OIDC_SCOPESopenid email profileruntimeSeparados por espaço; precisa incluir openid.
ORBIT_SSO_OIDC_ALLOWED_DOMAINSvazioruntimeDomínios de e-mail aceitos, separados por vírgula. Vazio aceita qualquer endereço que o provedor garanta.
ORBIT_SSO_OIDC_EMAIL_CLAIMemailruntimeA claim de primeiro nível do ID token que traz o endereço.
ORBIT_SSO_OIDC_GROUPS_CLAIMgroupsruntimeA claim de primeiro nível do ID token que traz os grupos.
ORBIT_SSO_OIDC_GROUP_ROLESvazioruntimePares 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_ROLEviewerruntimeO papel de quem nenhum grupo mapeia: viewer, editor ou deny. deny exige ao menos um grupo mapeado.
SSL_CERT_FILEnão definidoruntimeUm 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ávelDefaultEscopoSignificado
NOCTURNE_ADDR:8081runtimeEndereço de escuta da API.
NOCTURNE_LOG_LEVELinforuntimeNível de log.
NOCTURNE_LOG_PROBESfalseruntimeRegistra as requisições de probe e de /metrics em info.
NOCTURNE_PROVIDERmockruntimemock | 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_URLvazioruntimeURL base compatível com OpenAI, por exemplo https://api.openai.com/v1. Obrigatória quando o provedor é openai ou openai-responses.
NOCTURNE_API_KEYvazioruntime, de um SecretCredencial do provedor. Nunca registrada em log. Vazia é válida quando o provedor é mock.
NOCTURNE_REASONING_MODELvazioruntimeId do modelo do tier reasoning (análise, causa raiz, planos de FinOps).
NOCTURNE_FAST_MODELvazioruntimeId do modelo do tier fast (ajuda sobre o produto, respostas curtas).
NOCTURNE_REASONING_EFFORTvazioruntimeEsforç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_EFFORTvazioruntimeO mesmo para o tier fast.
NOCTURNE_MAX_TOKENS2048runtimeTeto da resposta, tokens de raciocínio incluídos: aumente junto com um esforço alto.
NOCTURNE_TIMEOUT120sruntimeTimeout do provedor upstream. O prazo de escrita do stream é esse valor mais 30s, então deixe ORBIT_STREAM_TIMEOUT acima dos dois.
NOCTURNE_TRIAGE_URLvazioruntimeSistema 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_KEYvazioruntime, de um SecretA credencial dele. Obrigatória junto com a URL. Nunca registrada em log.
NOCTURNE_TRIAGE_MODELvazioruntimeO id do modelo dele, por exemplo uma versão fixada. Obrigatório junto com a URL.
NOCTURNE_ORBIT_URLvazioruntimeA URL base do orbit-api, que as ferramentas de cluster leem. Vazia, o assistente roda sem ferramentas.
NOCTURNE_ORBIT_TOKENna falta dela, ORBIT_AUTH_TOKENruntime, de um SecretO 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_TIMEOUT10sruntimeUma chamada de ferramenta, incluindo a ida ao orbit-api. Um valor maior que NOCTURNE_TIMEOUT impede a inicialização.
NOCTURNE_MAX_TOOL_STEPS6runtimeTurnos do modelo que podem chamar ferramentas numa mesma resposta, de 1 a 20.
NOCTURNE_TOOL_MAX_BYTES8000runtimeO máximo de um resultado de ferramenta que o modelo chega a ler, de 1.024 a 65.536 bytes.
NOCTURNE_TRUSTED_PROXIESvazioruntimeMesma 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_MODEstaticruntimeMesma 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_TOKENvazioruntime, de um SecretObrigatório, ≥32 bytes, quando o modo é static.
NOCTURNE_OIDC_ISSUERvazioruntimeObrigatório quando o modo é oidc.
NOCTURNE_OIDC_AUDIENCEvazioruntimeObrigatório quando o modo é oidc.
NOCTURNE_METRICS_ADDR:9090runtimeListener separado para /metrics (Adendo v0.2).
NOCTURNE_SHUTDOWN_GRACE180sruntimeOrç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_DATAtrueruntimeLida 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 flagDefaultSignificado
ORBIT_SHOP_OTLPvazio, obrigatóriaA URL base do engine, http://orbit-stack:8082; os spans vão para o /v1/traces dele.
ORBIT_SHOP_OTLP_TOKENvazioO bearer do engine, ORBIT_STACK_AUTH_TOKEN, quando a autenticação dele é static.
ORBIT_SHOP_URL_<SERVICE>vazioNo 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_NAMEo nome do serviço, shop, unknownO recurso do span, preenchido pela downward API.
PORT8080A porta de escuta no modo --service.
--all / --service NAMEnenhumTodos 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.
--rps5Requisiçõ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):

ModoQuando usarDo que precisa
static (default)Uma credencial compartilhada, o caso comum de uma instalação auto-hospedada.ORBIT_AUTH_TOKEN / NOCTURNE_AUTH_TOKEN, ≥32 bytes.
oidcVocê 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.
disabledApenas 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):

bash
openssl rand -hex 32

Rode-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=true significa que a UI do Orbit Deck lê os próprios dados sintéticos (apps/web/src/lib/demo-estate.ts) diretamente, sem nunca chamar o orbit-api.
  • ORBIT_DEMO_DATA=true significa que o próprio orbit-api serve 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. false seleciona a fonte ao vivo (services/rust/orbit-api/src/live.rs), que precisa de credenciais para pelo menos um cluster (veja ORBIT_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

ComponentePorta da APIPorta de métricasExposto pelo ingress padrão?
web3000nenhuma (o Next.js não serve /metrics)Sim, o único
orbit-api80809090Não (repassado pelo web)
nocturne80819090Não (repassado pelo orbit-api; não existe regra de ingress alguma para ele)
orbit-stack80829090Nã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.