Features
Feature switches
An admin turns whole features on and off for one installation, in one click, from the Deck. A
feature that is off disappears from the Deck, and orbit-api refuses its routes, so nothing
reaches it around the interface. The vendor can also lock a feature off for a customer, for
example one whose plan does not include AI. The routes and shapes are CONTRACT.md Addendum v0.26.
The switches
There are twelve, in this order, each with what turning it off takes away:
| Id | Name | Off, the Deck hides | Off, orbit-api refuses |
|---|---|---|---|
nocturne | Nocturne AI | The chat, the side docks, "write with Nocturne" | /api/v1/nocturne/*, POST /api/v1/sql/generate |
sql | Orbit SQL | The SQL editor | /api/v1/sql/query, /explain, /schema, /queries |
databases | Database connections | Admin → Databases, the editor's source picker | /api/v1/databases, database in a query |
terminal | Pod terminal | The Terminal actions, Admin → Terminal, the recorded sessions | /api/v1/exec, opening a session; a session already open ends within a second |
workload_changes | Workload changes | Scale, resources, suspend, trigger and restart | The same five writes, and GET .../rollout |
rollback | Deployment rollback | The rollback and its revisions | POST .../rollback, GET .../revisions |
config | Configuration and Secrets view | The Configuration tab | GET .../config, POST .../config/reveal, Nocturne's ConfigMaps tool |
logs | Stored logs | The log explorer and stored-log links | /api/v1/logs/*, the logs table in Orbit SQL |
apm | APM and traces | Services, the service map, traces, a Deployment's Releases tab | /api/v1/traces, /api/v1/apm/*, GET .../releases, the traces and spans tables in Orbit SQL |
ingestion | Ingestion control | Admin → Ingestion control | /api/v1/ingestion/* |
finops | FinOps | The FinOps page and the cost figures | .../finops, .../recommendations, the recommendations and namespace_costs tables in Orbit SQL, Nocturne's rightsizing tool; the background FinOps reads pause |
dashboards | Custom dashboards | Dashboards | /api/v1/dashboards |
databases depends on sql: with Orbit SQL off, the connections are off too, whatever their own
switch says, and the page shows them as "off together with Orbit SQL". Turning Orbit SQL back on
brings them back.
Always on, and never listed: the estate (clusters, nodes, workloads, pods, events, alerts and the live pod-log tail), sign-in, users, roles, the audit trail, settings and the switches themselves.
Two layers
The vendor lock. The chart's features.locked list renders ORBIT_FEATURES_LOCKED on
orbit-api, a comma-separated list of ids:
features:
locked: [nocturne]orbit-api validates it at start and refuses to start on an unknown id. A locked feature is off,
cannot be turned on from the Deck, and its row says "Not included in the plan".
The license. On the Free plan, after the 30-day trial and without a usable key, nocturne is off
with switchedOffBy: "plan" and answers 403 plan_required; its row says "Needs a key" and points to
Admin > License. databases stays on: connections, the SQL editor and the MySQL collectors run on every
plan, and only the MySQL statement views need a key. A valid key turns Nocturne back on. See
docs/licensing.md.
The admin's switches. Everything is on by default. An admin with settings.manage changes them
under Admin → Features. orbit-api keeps them in its own store, so they survive a restart and
need no deploy. A switches document that cannot be read (a store file damaged by hand) counts as
every feature off, not on, until an admin saves the switches again.
The pods a feature runs
Three features run pods of their own. Switch one off and orbit-api parks those pods; switch it
back on and they return. The routes answer 403 at once, and the pods follow in the background,
in seconds.
| Feature | Workload | Parked when |
|---|---|---|
nocturne | The nocturne Deployment | nocturne is off |
apm | The auto-instrumentation DaemonSet: orbit-probe, or OBI with apm.autoInstrument.engine=obi | apm is off |
apm, logs | The collector Deployment, otel-collector | apm is off, and logs too when telemetry.logs ships logs through it |
logs has no pod of its own. orbit-node tails the logs and also serves the node metrics, so it
stays. With logs off and apm on, the collector keeps running for traces, orbit-node keeps
shipping logs and orbit-stack keeps storing them: only the Deck and the routes hide them. With
both off, the collector parks and orbit-node drops what it reads, counted in
orbit_node_logs_records_dropped_total.
The other nine features run no pod, and switching one changes nothing in the cluster. orbit-api,
orbit-stack, web, orbit-agent, orbit-state and orbit-node never park.
Parking. A Deployment goes to 0 replicas and keeps its count in the annotation
sreorbit.io/parked-replicas. A DaemonSet gets the node selector sreorbit.io/parked: "true", a
label no node carries: its pods go and the object stays. Coming back is one patch that restores the
count or drops the selector, with no helm upgrade. At 0 replicas a HorizontalPodAutoscaler stands
still, and it scales again once the count returns.
When orbit-api acts. At start, on every switch, and every 30 seconds. Each pass reads the
objects it owns, three GETs at most and no watch, and patches only the ones that drifted; each
patch runs as a server-side dry run first. A helm upgrade keeps a parked workload parked: the chart looks
up the live object and renders it at 0 replicas or with the parked selector. A render that never
sees the cluster (helm template | kubectl apply, Argo CD) brings the pods back until orbit-api's
next pass, at most 30 seconds later.
The vendor lock. A workload whose features are all in features.locked renders parked from the
first install, so a plan without AI never starts a Nocturne pod.
Permissions. The chart sets ORBIT_FEATURE_WORKLOADS on orbit-api when it reads the cluster
(components.orbit-api.rbac.enabled), and grants patch, and nothing else, on exactly those
Deployments and DaemonSets by name, in a Role in their own namespace: the release's, and
<release>-node for the DaemonSet. Nothing is cluster-wide. If the cluster refuses a patch, the
pods keep running, the switch still holds, and the page shows the refusal next to the workload.
Admin → Features lists these workloads under their feature with the live state: the pod count, "parking…", "parked, no pods", "starting…", or the refusal. The page reads them again every 2 seconds while one moves, and stops when they settle.
Admin → Features
/deck/admin/features is one list in four groups: AI, Data, Operations, and Cost and visualization.
Each row names the feature, says what turning it off hides and blocks, and carries its switch. A
click applies at once, with no save button; if orbit-api refuses, the switch goes back and the
page says why.
Three presets sit above the list. Each one opens a confirmation that lists exactly what will change, and nothing else:
| Preset | Changes |
|---|---|
| Read-only | Off: workload_changes, rollback, terminal, config |
| No AI | Off: nocturne |
| Turn everything on | On: every feature that is not locked |
While workload_changes, rollback, terminal and config are all off, every Deck page carries
a banner, "Installation in read-only mode", with a link to Admin → Features for admins.
A page of a feature that is off says "This feature is turned off on this installation" and why: an admin turned it off, its parent is off, or the plan does not include it. An admin gets a link to turn it on. Buttons and sections of a feature that is off are not rendered at all.
Over the API
| Route | Needs | Body and answer |
|---|---|---|
GET /api/v1/features | Any session | {features, readOnly, updatedAt, updatedBy} |
PUT /api/v1/features | settings.manage | {"enabled": {"<id>": true}}, a partial map applied at once; the answer is the GET's |
Each entry of features is {id, enabled, locked, dependsOn, switchedOffBy}; switchedOffBy is
admin, parent, lock or null. readOnly is true while the four operations switches are
all off. On a live install, a feature that runs pods also carries workloads, a list of
{kind, namespace, name, features, state, pods, error}: features names every feature the
workload serves, state is running, starting, parking, parked, failed or missing, and
error appears only on failed.
- An unknown id answers
400. Setting a locked id totrueanswers403withfeature_locked. - A route of a feature that is off answers
403withfeature_disabled, and a message naming the feature. The check runs after the permission check, so a caller who lacks the permission is told that first. - Nocturne's tools call
orbit-apias the user, so they are refused the same way. - In Orbit SQL a table of a feature that is off does not exist, as a table the caller's role does not
reach: a query that names it fails with
not found, and/api/v1/sql/schemaleaves it out.
Audit
Each feature that changes writes one event, feature.enable or feature.disable, with the target
type feature, the id as the target, and the details {"preset": "<name>"} or
{"preset": null}. The Deck sends x-orbit-preset with read-only, no-ai or all-on when a
preset was used, so the audit trail can say which one.
Each patch to a workload writes one more event, feature.park or feature.unpark, with the target
type workload, <Kind>/<namespace>/<name> as the target, and the details {"features": [...]}.
A refused patch has the outcome failure and adds error. After a switch, the event carries the
admin who switched; at start and on the timer it carries no actor.
The public demo
On demo data every feature is on. The page is read-only there and says so; orbit-api refuses
the PUT as a demo write.