Skip to content

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:

IdNameOff, the Deck hidesOff, orbit-api refuses
nocturneNocturne AIThe chat, the side docks, "write with Nocturne"/api/v1/nocturne/*, POST /api/v1/sql/generate
sqlOrbit SQLThe SQL editor/api/v1/sql/query, /explain, /schema, /queries
databasesDatabase connectionsAdmin → Databases, the editor's source picker/api/v1/databases, database in a query
terminalPod terminalThe Terminal actions, Admin → Terminal, the recorded sessions/api/v1/exec, opening a session; a session already open ends within a second
workload_changesWorkload changesScale, resources, suspend, trigger and restartThe same five writes, and GET .../rollout
rollbackDeployment rollbackThe rollback and its revisionsPOST .../rollback, GET .../revisions
configConfiguration and Secrets viewThe Configuration tabGET .../config, POST .../config/reveal, Nocturne's ConfigMaps tool
logsStored logsThe log explorer and stored-log links/api/v1/logs/*, the logs table in Orbit SQL
apmAPM and tracesServices, 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
ingestionIngestion controlAdmin → Ingestion control/api/v1/ingestion/*
finopsFinOpsThe 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
dashboardsCustom dashboardsDashboards/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:

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

FeatureWorkloadParked when
nocturneThe nocturne Deploymentnocturne is off
apmThe auto-instrumentation DaemonSet: orbit-probe, or OBI with apm.autoInstrument.engine=obiapm is off
apm, logsThe collector Deployment, otel-collectorapm 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:

PresetChanges
Read-onlyOff: workload_changes, rollback, terminal, config
No AIOff: nocturne
Turn everything onOn: 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

RouteNeedsBody and answer
GET /api/v1/featuresAny session{features, readOnly, updatedAt, updatedBy}
PUT /api/v1/featuressettings.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 to true answers 403 with feature_locked.
  • A route of a feature that is off answers 403 with feature_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-api as 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/schema leaves 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.