Pular para o conteúdo

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:

IdNomeDesligada, o Deck escondeDesligada, o orbit-api recusa
nocturneNocturne AIO chat, os painéis laterais, "escrever com o Nocturne"/api/v1/nocturne/*, POST /api/v1/sql/generate
sqlOrbit SQLO editor SQL/api/v1/sql/query, /explain, /schema, /queries
databasesConexões de banco de dadosAdmin → Bancos de dados, o seletor de fonte do editor/api/v1/databases, database em uma consulta
terminalTerminal de podsAs 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_changesAlterações em workloadsEscalar, recursos, suspender, disparar e reiniciarEssas mesmas cinco escritas, e o GET .../rollout
rollbackReversão de DeploymentsA reversão e as revisõesPOST .../rollback, GET .../revisions
configVisualização de configuração e SecretsA aba ConfiguraçãoGET .../config, POST .../config/reveal, a ferramenta de ConfigMaps do Nocturne
logsLogs armazenadosO explorador de logs e os atalhos para logs armazenados/api/v1/logs/*, a tabela logs do Orbit SQL
apmAPM e tracesServiç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
ingestionControle de ingestãoAdmin → Controle de ingestão/api/v1/ingestion/*
finopsFinOpsA 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
dashboardsDashboards personalizadosOs 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:

yaml
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.

RecursoWorkloadEstacionado quando
nocturneO Deployment nocturnenocturne está desligado
apmO DaemonSet de autoinstrumentação: orbit-probe, ou o OBI com apm.autoInstrument.engine=obiapm está desligado
apm, logsO Deployment do coletor, otel-collectorapm 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çãoMuda
Somente leituraDesliga: workload_changes, rollback, terminal, config
Sem IADesliga: nocturne
Ligar tudoLiga: 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

RotaExigeCorpo e resposta
GET /api/v1/featuresQualquer sessão{features, readOnly, updatedAt, updatedBy}
PUT /api/v1/featuressettings.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 como true um id travado responde 403 com feature_locked.
  • Uma rota de um recurso desligado responde 403 com feature_disabled e 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-api como 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/schema a 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.