Features
Pod terminal
A user whose role holds pods.exec opens an interactive shell in a pod from the Deck. Everything
typed and everything shown is recorded, each command line goes to the audit trail, and nothing
opens without a recording. The routes and shapes are CONTRACT.md Addendum v0.24.
Turning it on
The terminal is off by default. Two things turn it on, and they move together:
helm upgrade sreorbit deploy/helm/sreorbit --reuse-values \ --set components.orbit-api.rbac.exec.enabled=trueThat renders a ClusterRole and a ClusterRoleBinding for orbit-api with exactly pods/exec, verbs
create and get, and sets ORBIT_EXEC_ENABLED to true in its ConfigMap. The switch never
renders without the permission, nor the permission without the switch. It needs rbac.enabled,
as the workload writes do, and the chart refuses to render otherwise.
Then:
components.orbit-api.exec.namespaces(ORBIT_EXEC_NAMESPACES) lists the namespaces a terminal may open in. Empty means every namespace exceptkube-system. It is the default: an admin changes it in the Deck under Admin → Terminal, and that choice wins at once, with no deploy. Each change is audited asexec.settings.update, with the list before and after.orbit-api's own namespace is always refused, listed or not: its pods hold the seal key and every bearer.- Only the built-in
adminrole holdspods.exec. Give it to a custom role in Admin → Roles.
Opening a terminal
The Terminal action sits on a pod's page and on each row wherever the Deck lists pods, and shows
only when your role holds pods.exec, the terminal is on, and the pod's namespace is allowed. It
opens xterm.js on the pod:
- the first container by default, with a picker when the pod has more than one;
bashwhen the image has it,shotherwise;- a banner saying the session is recorded and audited;
- the terminal follows the panel's size, and a dropped connection reconnects and shows the last 64 KiB of output again;
- "End session", or leaving the page, closes the shell;
- below it, the pod's logs and traces in the window you came with, each opening a new tab so the shell stays open.
Typing stays ahead of the network. A key leaves at once, and keys typed while its request is out leave together as the next one, up to the first Enter, so a slow link costs one round trip a batch and never a growing queue. The header shows the echo time, the median of your last keys from the press to the echo reaching the terminal, and "no echo" when a key got no answer for 2 seconds.
Predictive echo shows what you type before the pod answers, dimmed and underlined until the echo confirms it, as mosh does. It is a layer over the terminal, so a prediction never enters the terminal's buffer, the request or the recording. It shows only after a key has echoed where it was typed and past 30 ms of round trip, and output that moves the cursor ends that, so a new prompt starts dark. It never shows at a secret prompt, in a full-screen program, over text to the right of the cursor, or after an echo that differs or does not come. Only plain characters are predicted. Enter, Tab, an arrow or any other control key leaves what is drawn in place until its echo, and the next keys wait for theirs; Backspace also takes back the last key not yet confirmed. A program that turns echo off without printing anything can still show your keys until the missing echo lapses, 2 seconds. Turn it off in the header; the browser remembers.
Ctrl+Shift+F finds in the scrollback: Enter goes to an older match, Shift+Enter to a newer one, Esc closes. Ctrl+C copies when text is selected and is the interrupt otherwise; on a Mac, Cmd+C copies and Ctrl+C is always the interrupt. Ctrl+Shift+V pastes, and so does Ctrl+V on a shell line; a full-screen program such as vim gets Ctrl+V, and on a Mac Cmd+V pastes. A web address in the output opens on click, after showing it to you.
A refusal says why: the terminal is off, the namespace is not allowed, you already have 4 open
sessions, orbit-api has 16, or this is the public demo. Each refusal is audited too.
Limits
| Limit | Default | Setting |
|---|---|---|
| Idle, no input | 15 minutes | ORBIT_EXEC_IDLE_TIMEOUT_S |
| Longest session | 2 hours | ORBIT_EXEC_MAX_DURATION_S |
| Output recorded per session | 64 MiB | fixed |
| Recordings kept | 90 days | ORBIT_EXEC_RETENTION_DAYS |
| Recordings in all | 512 MiB | ORBIT_EXEC_RECORDINGS_MAX_BYTES |
| Open sessions | 4 per user, 16 in all | fixed |
A session past a limit ends with the reason idle, max_duration or recording_limit. Turning
the terminal off under Admin → Features ends every open session within a second, with the reason
feature_disabled. The
oldest recordings are pruned first, when a session starts and once an hour. No route deletes a
recording.
When typing feels slow
A key goes from your browser through any CDN and the ingress to web, orbit-api and the pod, and
its echo comes back the same way. web and orbit-api take a few milliseconds of that. The rest is
your link and the cluster's own path to the pod, through the API server and the kubelet.
To read the split on your install, open the browser's developer tools, pick an input call in the
Network tab and open Timing. web under Server Timing is how long web waited for orbit-api to
take the key; orbit-api answers once the key is queued, so it does not cover the pod or the echo.
The total minus it is your link, any CDN, the ingress and a few milliseconds of web's own. pod
is the trip of the first key after a pause from orbit-api to the pod and back, through the API server
and the kubelet, so a burst of typing keeps that reading.
Any output counts as the answer: it reads low while a program prints without stopping, and up to 2
seconds high after a key the program does not echo. pod is missing past 2 seconds, so typing with
no pod means no echo or a cluster that slow.
Keys reach a program that floods the terminal at once, so Ctrl-C stops it, and a long paste goes through too. The screen takes longer: up to 8 MiB of output already on its way to the browser, plus what the sockets along the way hold, still arrives after the Ctrl-C. A browser further behind than that is dropped and reconnects to the last 64 KiB.
What is recorded
Each session is an asciicast v2 file in orbit-api's data directory, exec/<id>.cast: a header
with the size, the start and the title (user, namespace, pod and container), then every output
chunk, every keystroke and every resize, with its time. The header is written before the first
byte reaches the browser; if it cannot be written, the session is refused. Events are flushed at
least every second, and a write that fails ends the session with recording_failed: nothing runs
unrecorded.
The audit trail gets three kinds of event, with the user as the actor and the target
pod <namespace>/<pod>:
| Action | When | Details |
|---|---|---|
pod.exec.start | A session opens or is refused | cluster, container, session, the reason and the client address |
pod.exec.command | Each command line, at most 1,000 per session | line (its first 1 KiB), t and approximate |
pod.exec.end | A session ends | durationMs, exitCode, reason, inputBytes, outputBytes and commands |
Command lines are read from the keystrokes by a small line editor: typing adds, Backspace erases, Ctrl-U clears the line, Ctrl-C drops it and Enter ends it. A line edited with the arrows, the history or Tab is marked approximate, because the shell may have run something else. The recording, not the line list, is the source of truth.
Two things stay out of both. When the pod's output ends in a prompt for a password, passphrase,
PIN, secret or token ([sudo] password for dev:, Enter passphrase for key), the keystrokes up to
the next Enter are recorded as one * each; the shell does not echo them, so the output holds
nothing either. A command line's credential shapes (--password=x, --token x, password=x,
PGPASSWORD=x, mysql -px, sshpass -p x, curl -u user:x, redis-cli -a x, Bearer x,
user:pass@ in a URL, private keys, cloud and GitHub keys) read [redacted] in
pod.exec.command, in the session's command list and in the start command that pod.exec.start
and the session list show, older sessions included; the pod still runs the command as sent. orbit-api stars them in the recording too,
one * per character, in the keystrokes and in the shell's echo: it holds a line and its output in
memory until a second passes after its Enter, then writes both. It also rebuilds each output line
as the terminal draws it and stars the same shapes there, so a credential typed in an earlier
session and shown again in this one (history, the Up arrow, Ctrl-R, env, ps) reaches the
recording as stars. A credential of 4 characters or more stays starred in later output of the same
session. GET /api/v1/exec/sessions/{id}/cast stars a recording an earlier release wrote the same
way before it serves it. Three limits remain. orbit-api pairs each echoed character with the key
that typed it, in order, so output a program prints while you type can throw a pair off and leave
part of an echo readable. A line still open after 30 seconds or 256 KiB reaches the recording
starred only where it already shows a credential shape. When the pod sends a line in two reads, a
credential known only by what follows it (user:pass@, Bearer x) keeps the part the first read
held. Type secrets at a prompt, or read them from a file.
Reviewing a session
Admin → Audit trail → Terminal sessions (/deck/admin/audit/sessions, behind audit.read) lists
every session, newest first, filtered by user, namespace and pod. A session's page shows who opened
it, from where, when, for how long and how it ended, and plays the recording with its own timing.
The recording streams in, so the controls work at once on what has arrived, whatever its size, and
the screen opens on the session's last one as soon as the browser has read it.
- Play and seek. Play and pause, 1× to 8×, and a slider. A seek writes the nearest keyframe and what follows it, never the recording from zero, so it costs the same at any point of a recording, however long. Scrolling up after a seek shows what came just before it, not the whole session.
- Timeline. A mark per command line and a band per long silence; a click on a mark goes there.
- Silences. "Skip silences", on by default, plays any silence for 2 seconds at most. The clock still shows real time.
- Search. What the session printed, without its colours, wherever the output was cut: each match says when it appeared, and a click goes to that moment, scrolled to the match and lit. Keys typed are not searched, only what the screen showed. Masked credentials are not in the recording, so neither a search nor a seek can bring them back.
- A link to a moment. "Copy link to this moment" gives the page's address with
#t=<seconds>. It opens on that moment for anyone holdingaudit.read, through sign-in if they need it. Where the browser refuses the clipboard, the button says the link is in the address bar. A search never goes in the link. - Keys. Space or K play and pause, ← → move 5 s (30 s with Shift), Home and End, N and P the next and previous command, < and > the speed, I the silences, / the search. They answer while focus is in the player, where the page puts it on opening; with focus elsewhere, those keys belong to the page.
Its command lines are listed with their times; a click plays the recording from that line.
"Download recording" saves the .cast file, which any asciicast player also plays.
Over the API
| Route | Needs | Body and answer |
|---|---|---|
GET /api/v1/exec/status | pods.exec | {enabled, namespaces, idleTimeoutS, maxDurationS, reason} |
POST /api/v1/clusters/{id}/pods/{namespace}/{pod}/exec | pods.exec | {container, command, cols, rows} → 201 with the session |
GET /api/v1/exec/{id}/stream | The session's own user | Server-sent events |
POST /api/v1/exec/{id}/input | The same | {data}, base64, at most 64 KiB → 204 |
POST /api/v1/exec/{id}/resize | The same | {cols, rows} → 204 |
DELETE /api/v1/exec/{id} | The same | 204, ends the session |
GET /api/v1/exec/sessions | audit.read | {sessions, next}, newest first |
GET /api/v1/exec/sessions/{id} | audit.read | The session and its lines |
GET /api/v1/exec/sessions/{id}/cast | audit.read | The recording, application/x-asciicast |
The stream sends output events (base64 of the raw bytes), one exit event with the code and
the reason, and a : ping comment every 15 s. A second read of the stream replaces the first and
starts with the last 64 KiB of output. Anyone other than the session's own user gets 404.
The web server passes the input, resize and end calls, and the start, on the signed-in user's session only, never on an operator token, and only from the console's own pages.