Skip to content

2.22.0: API keys, admin policy, API for agents

Choose a tag to compare

@vurulkan vurulkan released this 13 Nov 11:52
· 6 commits to main since this release
9e9df7e

What's new

API keys (account menu → API keys, ⌘K → Go to API keys)

  • Keys (oc_…) for Claude Code, Cursor or your own scripts, calling the API in your name. Scope: all clusters or one, all your namespaces (including later ones) or a selection, and a permission matrix with templates (Read-only (safe), Read-only (all), All my permissions, Custom). A key never does more than its owner holds at the time of the call.
  • Expiry 7 / 30 / 60 / 90 days, a date or none; edit, regenerate (new secret and expiry), revoke, delete. The key is shown once and stored as a SHA-256 hash.
  • X-OpenConsole-Cluster: <name or id> picks the cluster per request; WebSockets take a single-use ticket from POST /api/ws-ticket. 10 requests / s per key (burst 30), then 429.
  • A key can never manage keys, change the password, switch your cluster or save views (403 api_key_not_allowed). Admin endpoints need an admin's key with the Admin API box.

Admin policy

  • Per role, how much of it a key may get: Off, Safe read-only (default, also for existing roles) or All of the role's permissions. With several roles each goes through its own mode, then they add up (exec in ns1, read only in ns2).
  • Per user override (By roles / Off / Safe read-only / All of their permissions, never more than the web), with a preview of what the user's keys may reach and Revoke all their keys.
  • The policy never changes a key: a blocked cell stops working and works again when allowed (403 api_access_policy; api_access_off when nothing is left).
  • Expiry policy (Admin → Session): longest lifetime, keys without expiry allowed or not; existing keys are left alone and listed as Outside the expiry policy.
  • Admin → API keys: every user's keys, filters (owner, status, includes exec, Admin API, outside policy), revoke with a reason, CSV.

API for agents

  • OpenAPI 3.1 at GET /api/openapi.json (no sign-in, nothing secret in it); a test fails the build when a route is missing from it.
  • API keys → Documentation: quick start, a text to hand your agent (the key stays in OPENCONSOLE_API_KEY), every endpoint a key can call by tag with its permission, parameters, a curl example and example responses, greyed out where your keys can't reach it (You do not have it, Policy does not allow, Switched off), and the errors.
  • POST /api/namespaces/{ns}/pods/{name}/exec: one command (argv, never a shell), no stdin, 1 MiB per stream, 1–120 s; {stdout, stderr, exitCode, truncated, durationMs}. Same pods:exec, feature flag, shell limit and recorder as the shell; recorded with a command badge; the audit log keeps only the program (command[0]), never the command line.
  • GET /api/namespaces/{ns}/pods/{name}/logs: a pod's log as text/plain (tailLines up to 10 000, sinceSeconds, previous, timestamps; 5 MiB, X-OpenConsole-Truncated).

Audit and logs

  • Every action and resource read made with a key carries api_key_id / api_key_name (Audit Logs: Source = Web / API key, key name; the CSV has api_key_name). Successful reads with a key are kept API_KEY_READ_RETENTION_DAYS (7). A shell or command run with a key is always recorded, even with recording off.
  • http.request log lines also carry the key (openconsole.api_key.* in ECS), refused requests and non-audited calls (/api/auth/me, /api/ws-ticket) included, so openconsole.api_key.id : * separates API from web in Kibana.
  • 403 bodies name the reason: forbidden, api_access_policy, api_access_off, api_key_not_allowed, feature_disabled, admin_only.

Also in this release (2.21.1, not released on its own)

  • Any 401 to a signed-in user returns to the sign-in page with "your session ended"; an idle screen does too when the token expires. 401 now only means that: a wrong current password is 400, a user who must change the password gets 403.

Upgrading

  • Database: tables and columns are added on the first start. Rolling back to 2.21 works: the old image opens the new schema (keys simply don't exist there). Back up /data/app.db first anyway.
  • API key policy: every existing role starts at Safe read-only. Open a role (Admin → Roles → API access) for keys to exec, edit, scale, restart or read ConfigMaps / Secrets.
  • Elastic: re-run deploy/elk/install.sh once (ten new mapped fields; the pipeline is unchanged). On Elasticsearch 8.7 follow deploy/elk/README.md → Elasticsearch 8.7 and older (by hand, an ILM policy, PUT <ds>/_mapping for the live index).
  • Scripts that read error texts: 403 bodies are now reason codes; the audit CSV has one more (last) column.
  • ClusterRole: unchanged (exec and logs were already granted).

Tested on a nonprod AKS cluster (dev images): role modes and every override value, the expiry policy, admin revoke and CSV, one-command exec (output, exit codes, timeout, 1 MiB, limits, recording, no command text in the audit log, the console log or Elasticsearch), REST log limits and previous, WebSocket tickets, a key shell recorded with recording off, 401 / 403 / 429, the Documentation tab as a user and as an admin, and the key on audit events and request lines in Kibana.

Image

ghcr.io/vurulkan/kubernetes-openconsole:2.22.0 (= :latest, same digest sha256:f4d193cf…; amd64 + arm64), with signed provenance and SBOM:
gh attestation verify oci://ghcr.io/vurulkan/kubernetes-openconsole:2.22.0 --repo vurulkan/kubernetes-openconsole

🤖 Generated with Claude Code