Recursos
Chaves de recursos
Um administrador liga e desliga recursos inteiros de uma instalação, com um clique, pelo Deck. Um
recurso desligado some do Deck, e o orbit-api recusa as rotas dele, então nada o alcança por fora
da interface. O fornecedor também pode travar um recurso desligado para um cliente, por exemplo
aquele cujo plano não inclui IA. As rotas e os formatos estão no CONTRACT.md, Adendo v0.26.
As chaves
São doze, nesta ordem, cada uma com o que desligá-la tira do ar:
| Id | Nome | Desligada, o Deck esconde | Desligada, o orbit-api recusa |
|---|---|---|---|
nocturne | Nocturne AI | O chat, os painéis laterais, "escrever com o Nocturne" | /api/v1/nocturne/*, POST /api/v1/sql/generate |
sql | Orbit SQL | O editor SQL | /api/v1/sql/query, /explain, /schema, /queries |
databases | Conexões de banco de dados | Admin → Bancos de dados, o seletor de fonte do editor | /api/v1/databases, database em uma consulta |
terminal | Terminal de pods | As ações de Terminal, Admin → Terminal, as sessões gravadas | /api/v1/exec, abrir uma sessão; uma sessão já aberta termina em até um segundo |
workload_changes | Alterações em workloads | Escalar, recursos, suspender, disparar e reiniciar | Essas mesmas cinco escritas, e o GET .../rollout |
rollback | Reversão de Deployments | A reversão e as revisões | POST .../rollback, GET .../revisions |
config | Visualização de configuração e Secrets | A aba Configuração | GET .../config, POST .../config/reveal, a ferramenta de ConfigMaps do Nocturne |
logs | Logs armazenados | O explorador de logs e os atalhos para logs armazenados | /api/v1/logs/*, a tabela logs do Orbit SQL |
apm | APM e traces | Serviços, mapa de serviços, traces, a aba Releases de um Deployment | /api/v1/traces, /api/v1/apm/*, GET .../releases, as tabelas traces e spans do Orbit SQL |
ingestion | Controle de ingestão | Admin → Controle de ingestão | /api/v1/ingestion/* |
finops | FinOps | A página de FinOps e os valores de custo | .../finops, .../recommendations, as tabelas recommendations e namespace_costs do Orbit SQL, a ferramenta de rightsizing do Nocturne; as leituras de FinOps em segundo plano param |
dashboards | Dashboards personalizados | Os dashboards | /api/v1/dashboards |
databases depende de sql: com o Orbit SQL desligado, as conexões também ficam desligadas, não
importa o que diga a chave delas, e a página as mostra como "desligado junto com Orbit SQL". Religar
o Orbit SQL as traz de volta.
Sempre ligados, e nunca listados: o parque (clusters, nós, workloads, pods, eventos, alertas e o acompanhamento ao vivo dos logs de pods), o login, usuários, papéis, a trilha de auditoria, as configurações e as próprias chaves.
Duas camadas
A trava do fornecedor. A lista features.locked do chart gera ORBIT_FEATURES_LOCKED no
orbit-api, uma lista de ids separados por vírgula:
features:
locked: [nocturne]O orbit-api a valida na partida e se recusa a subir diante de um id desconhecido. Um recurso
travado fica desligado, não pode ser ligado pelo Deck, e a linha dele diz "Não incluído no plano".
A licença. No plano Free, depois do teste de 30 dias e sem uma chave utilizável, nocturne fica
desligado com switchedOffBy: "plan" e responde 403 plan_required; a linha dele diz "Precisa de
chave" e aponta para Admin > Licença. databases continua ligado: as conexões, o editor SQL e os
coletores do MySQL rodam em todos os planos, e só as telas de statements do MySQL precisam de chave. Uma
chave válida religa o Nocturne. Veja docs/licensing.md.
As chaves do administrador. Tudo vem ligado. Um administrador com settings.manage muda as
chaves em Admin → Recursos. O orbit-api as guarda no próprio armazenamento, então elas sobrevivem
a um reinício e não pedem deploy. Um documento de chaves que não pode ser lido (um arquivo do
armazenamento danificado à mão) conta como todos os recursos desligados, e não ligados, até que um
administrador salve as chaves de novo.
Os pods de um recurso
Três recursos rodam pods próprios. Desligue um e o orbit-api estaciona esses pods; religue e eles
voltam. As rotas respondem 403 na hora, e os pods acompanham em segundo plano, em segundos.
| Recurso | Workload | Estacionado quando |
|---|---|---|
nocturne | O Deployment nocturne | nocturne está desligado |
apm | O DaemonSet de autoinstrumentação: orbit-probe, ou o OBI com apm.autoInstrument.engine=obi | apm está desligado |
apm, logs | O Deployment do coletor, otel-collector | apm está desligado, e logs também quando telemetry.logs envia logs por ele |
logs não tem pod próprio. O orbit-node lê os logs e também serve as métricas dos nodes, então ele
fica. Com logs desligado e apm ligado, o coletor continua rodando para os traces, o
orbit-node continua enviando logs e o orbit-stack continua guardando: só o Deck e as rotas os
escondem. Com os dois desligados, o coletor estaciona e o orbit-node descarta o que lê, contado em
orbit_node_logs_records_dropped_total.
Os outros nove recursos não rodam pods, e mudar a chave de um deles não altera nada no cluster.
orbit-api, orbit-stack, web, orbit-agent, orbit-state e orbit-node nunca estacionam.
Estacionar. Um Deployment vai a 0 réplicas e guarda a contagem na anotação
sreorbit.io/parked-replicas. Um DaemonSet ganha o node selector sreorbit.io/parked: "true", um
label que nenhum node tem: os pods saem e o objeto fica. Voltar é um único patch que restaura a
contagem ou tira o seletor, sem helm upgrade. Com 0 réplicas, um HorizontalPodAutoscaler fica
parado e volta a escalar quando a contagem retorna.
Quando o orbit-api age. Na partida, a cada mudança de chave e a cada 30 segundos. Cada passada
lê os objetos que lhe cabem, no máximo três GETs e nenhum watch, e aplica patch só nos que saíram do
lugar; cada patch roda antes como dry run no servidor. Um helm upgrade mantém estacionado o que
está estacionado: o chart consulta o objeto vivo e o renderiza com 0 réplicas ou com o seletor de
estacionamento. Uma renderização que não enxerga o cluster (helm template | kubectl apply, Argo CD)
traz os pods de volta até a próxima passada do orbit-api, no máximo 30 segundos depois.
A trava do fornecedor. Um workload cujos recursos estão todos em features.locked já é
renderizado estacionado na primeira instalação, então um plano sem IA nunca sobe um pod do Nocturne.
Permissões. O chart define ORBIT_FEATURE_WORKLOADS no orbit-api quando ele lê o cluster
(components.orbit-api.rbac.enabled) e concede patch, e nada além disso, exatamente nesses
Deployments e DaemonSets, por nome, em um Role no próprio namespace de cada um: o da release, e
<release>-node para o DaemonSet. Nada vale para o cluster inteiro. Se o cluster recusar um patch,
os pods continuam rodando, a chave continua valendo e a página mostra a recusa ao lado do workload.
Admin → Recursos lista esses workloads sob o recurso deles, com o estado ao vivo: a contagem de pods, "estacionando…", "estacionado, sem pods", "subindo…" ou a recusa. A página relê o estado a cada 2 segundos enquanto algum se move, e para quando tudo assenta.
Admin → Recursos
/deck/admin/features é uma lista única em quatro grupos: IA, Dados, Operações, e Custo e
visualização. Cada linha dá o nome do recurso, diz o que desligá-lo esconde e bloqueia, e traz a
chave dele. Um clique vale na hora, sem salvar; se o orbit-api recusar, a chave volta e a página
diz por quê.
Três predefinições ficam acima da lista. Cada uma abre uma confirmação que lista exatamente o que vai mudar, e nada além disso:
| Predefinição | Muda |
|---|---|
| Somente leitura | Desliga: workload_changes, rollback, terminal, config |
| Sem IA | Desliga: nocturne |
| Ligar tudo | Liga: todo recurso que não está travado |
Enquanto workload_changes, rollback, terminal e config estiverem todos desligados, cada
página do Deck mostra uma faixa, "Instalação em modo somente leitura", com um atalho para Admin →
Recursos para quem administra.
A página de um recurso desligado diz "Este recurso está desligado nesta instalação" e o motivo: um administrador o desligou, o recurso do qual ele depende está desligado, ou o plano não o inclui. Um administrador recebe um atalho para religá-lo. Controles e seções de um recurso desligado nem chegam a ser renderizados.
Pela API
| Rota | Exige | Corpo e resposta |
|---|---|---|
GET /api/v1/features | Qualquer sessão | {features, readOnly, updatedAt, updatedBy} |
PUT /api/v1/features | settings.manage | {"enabled": {"<id>": true}}, um mapa parcial aplicado de uma vez; a resposta é a mesma do GET |
Cada item de features é {id, enabled, locked, dependsOn, switchedOffBy}; switchedOffBy vale
admin, parent, lock ou null. readOnly é true enquanto as quatro chaves de operações
estiverem todas desligadas. Em uma instalação com dados reais, um recurso que roda pods também traz
workloads, uma lista de {kind, namespace, name, features, state, pods, error}: features nomeia
todos os recursos que o workload atende, state vale running, starting, parking, parked,
failed ou missing, e error só aparece em failed.
- Um id desconhecido responde
400. Marcar comotrueum id travado responde403comfeature_locked. - Uma rota de um recurso desligado responde
403comfeature_disablede uma mensagem que nomeia o recurso. A verificação roda depois da checagem de permissão, então quem não tem a permissão ouve isso primeiro. - As ferramentas do Nocturne chamam o
orbit-apicomo o usuário, então são recusadas do mesmo jeito. - No Orbit SQL, uma tabela de um recurso desligado não existe, assim como uma tabela que o papel de quem
consulta não alcança: uma consulta que a cita falha com
not found, e o/api/v1/sql/schemaa omite.
Auditoria
Cada recurso que muda grava um evento, feature.enable ou feature.disable, com o tipo de alvo
feature, o id como alvo e os detalhes {"preset": "<name>"} ou {"preset": null}. O Deck envia
x-orbit-preset com read-only, no-ai ou all-on quando uma predefinição foi usada, para que a
trilha de auditoria diga qual.
Cada patch em um workload grava mais um evento, feature.park ou feature.unpark, com o tipo de
alvo workload, <Kind>/<namespace>/<name> como alvo e os detalhes {"features": [...]}. Um patch
recusado tem o resultado failure e acrescenta error. Depois de uma mudança de chave, o evento
traz o administrador que a fez; na partida e no timer, não traz ator.
A demonstração pública
Com dados de demonstração, todos os recursos ficam ligados. Lá a página é somente leitura e avisa
isso; o orbit-api recusa o PUT como escrita de demonstração.