Upgrading
Before you start
- Read the release notes of every version between yours and the new one (Release notes).
The version-specific steps are also below. Your version: hover the GitHub icon at the bottom of the left
rail, or read the first log line of the pod (
"version":"…"). - Back up the volume (Backup and restore). It is the only way back to the
exact state before the upgrade. From 2.23.1 on, OpenConsole also copies the database to
/data/backups/app-<time>-pre-upgrade.dbbefore a new version changes it, but that copy is on the same volume. - Make sure the Deployment uses
strategy: Recreate(Install on Kubernetes). With the default rolling update the new pod opens the database while the old one still runs; on 2.23.0 that can lose writes until the next restart.
You can skip versions: going from 2.21.0 to 2.22.0 or from 2.16 to 2.22 is one step. Each release brings its database changes along and applies the missing ones on start.
Upgrade
Change the version in both places of your kustomization.yaml and apply it:
resources:
- https://github.com/vurulkan/kubernetes-openconsole//deploy?ref=v2.23.4 # was v2.23.3
images:
- name: ghcr.io/vurulkan/kubernetes-openconsole
newTag: "2.23.4" # was 2.23.3
kubectl diff -k . # the image tag, plus whatever the release changed in deploy/
kubectl apply -k .
kubectl -n kubernetes-openconsole rollout status deploy/kubernetes-openconsole --timeout=5m
kubectl -n kubernetes-openconsole logs deploy/kubernetes-openconsole | head -3 # "version":"2.23.4"
Sessions stay valid, so signed-in users carry on after a page reload. With Recreate the console is unavailable
for the few seconds the new pod needs to start.
If you run the manifests unpinned (:latest with imagePullPolicy: Always, as in deploy/), a
kubectl -n kubernetes-openconsole rollout restart deploy/kubernetes-openconsole pulls the newest release. The
manifests themselves (ClusterRole rules, new variables) are only updated when you apply the new deploy/ again.
The ClusterRole may gain rules in a release (e.g. nodes watch in 2.20). It comes with deploy/ in the
cluster OpenConsole runs in; on every other connected cluster apply the new rbac.yaml yourself
(Connect a cluster).
What happens to the database
- Migrations run automatically on the first start of the new version: they add tables and columns, and some releases rewrite existing rows once (2.17 gave old audit rows the new action / outcome fields). There is no step to run by hand.
- From 2.23.1 the migration runs in one transaction: if it fails (a full disk, a damaged file), the pod stops with the error in its log and the database stays as it was.
- There are no down-migrations. Going back to an older version is not supported. In practice the older version usually starts on the newer database because the changes only add (checked: 2.21.0 on a 2.22.0 database), but data the newer version wrote can be ignored or misread.
Going back
- Set the previous version in
kustomization.yamlandkubectl apply -k .. - If the older version misbehaves on the newer database, restore the backup you took before the upgrade. Everything since the backup (audit events, users, settings) is lost.
Version notes
Upgrading to 2.23.4
- Replace the image: no change to the API's paths, the database or the manifests. Rolling back to 2.23.3 works.
- Events follow the object live in the pod and workload drawers and behind a row's Events button, which now
shows the same list instead of raw JSON (Detail drawers).
/ws/eventsframes of Kubernetes events carrycount.
Upgrading to 2.23.3
- Replace the image: no change to the API, the database or the manifests. The Logs buttons have their own icon (a page of text) instead of the terminal that Shell uses.
Upgrading to 2.23.2
- Replace the image: no change to the API, the database or the manifests. Rolling back to 2.23.1 works.
- Dates are written the same way everywhere, whatever the browser's language and region:
2026-11-16 23:37:51(24 h) in the browser's time zone; audit log times keepTIMEZONE. - Audit, with
WS_ORIGIN_CHECK=enforce: a log socket from another site is no longer audited aspod.logssuccess; a shell from another site ispod.execdenied, reasonorigin_not_allowed, and leaves no recording. - Tables: the action buttons and the column picker stay at the right edge of a wide table.
Upgrading to 2.23.1
- Your own manifest: the image is now distroless, and
deploy/deployment.yamlsetsreadOnlyRootFilesystem: truewith anemptyDirat/tmp. If you copy those settings, add the/tmpvolume too: it is the only place besides/datawhere the server may write a temporary file. - No shell in the image:
kubectl execinto the OpenConsole pod no longer works; usekubectl debug -it <pod> --image=busybox:1.36 --target=dashboard. - Cross-site requests: the API no longer answers CORS for any origin; list other sites in
ALLOWED_ORIGINSif their pages call it. WebSockets from another site are logged asws.origin_mismatch(still allowed with the defaultWS_ORIGIN_CHECK=warn). - The YAML editor comes with the image; the browser no longer loads it from
cdn.jsdelivr.net. - Your own manifest: use
strategy: RecreateandterminationGracePeriodSeconds: 30, asdeploy/now does. On shutdown open shells close with code 1012 (server restarting) and their end and recording are audited. - Database: the first start copies it to
/data/backups/app-<time>-pre-upgrade.db. Group memberships and role permissions get foreign keys: rows left behind by users, groups and roles deleted earlier are dropped, and an id that doesn't exist is refused (400/404) instead of being stored. - Backups: a copy of the database every day, the newest 7 kept in
/data/backups(Admin → Backups). Check the free space on the volume: about 7 times the database size. LOG_RETENTION_DAYS=0now keeps audit events forever (it used to mean 30), and the purge also runs at start.- Audit Logs: a page has at most 500 rows; Export CSV now has every matching row up to 50 000 (it stopped at 1 000).
- API error answers: every error is now problem details (
application/problem+json):{"type", "title", "status", "error", "detail"}.erroris always a reason code; a message that used to be the wholeerror(for examplecluster "nope" is unknown or not yours to use) is now indetail, under a code such asinvalid_input.401and429have a body too (unauthorized,api_key_expired,api_key_revoked,rate_limitedwithRetry-After: 1), and the API key page of an account that must change its password answerspassword_change_required. A script that compareserrorwith an English sentence must switch to the code (Errors). - Unknown API paths: an unknown
/api/…or/ws/…path answers404not_found(it used to answer200with the web UI's page), a wrong method405withAllow.GET/POST/PUT /api/admin/clusterandPOST /api/admin/cluster/validateare removed: use/api/admin/clusters. - Audit volume: every admin change on users, groups, roles and the sign-in, session and logo settings is audited
for every answer, refusals and failures included, and every YAML view is a
<kind>.getread (Audit log). - Logs: WebSocket request lines say
status=101; with tracing on,tracing enabledfollowsLOG_FORMAT; a failed LDAP sign-in writesldap sign-in failedwith the directory's message (Logging). - Kubeconfig clusters: a kubeconfig that runs a program (
exec, e.g. kubelogin), uses anauth-provideror reads a file is refused (kubeconfig_unsupported), and a cluster saved with one no longer connects. Before upgrading, check Admin → Clusters and replace such a kubeconfig with a token or an inline one (Kubeconfig method). - Your own manifest: set
TRUSTED_PROXIESto the network of the proxies in front of the console (deploy/deployment.yamlsets the private ranges). Without it noX-Forwarded-Foris believed: the audit log, Admin → Sessions and the sign-in lock see the ingress pod's address instead of the user's (Install on Kubernetes). - LDAP: a local account (the built-in
adminincluded) whose password doesn't match is no longer tried against the directory. User base DNs takes one DN per line: a value that lists several DNs separated by commas is read as one DN, so put each on its own line. StartTLS checks the directory's certificate; paste your CA in CA certificate (PEM) (LDAP). - Session timeout: the minutes in Admin → Session are now the time without activity, and a session ends at the latest 12 hours after sign-in; review a long value that was meant as a fixed lifetime (Sessions).
openconsole_cluster_connectedis now0for a cluster whose credentials are refused or that can't be reached, so an alert on it may fire after the upgrade: fix that cluster's credentials (Metrics).- Logs over the API: when Kubernetes refuses OpenConsole's own account,
GET …/pods/{name}/logsanswers403cluster_forbidden(it was502forbidden). A change to the cluster refused because the request itself is wrong is audited asfailed, reasoninvalid. - Name: the product is now called OpenConsole for Kubernetes. The image, the repository, the namespace and the manifests keep their names.
- Optional: keep the encryption key in a Secret (Keep the encryption key out of the database).
Upgrading to 2.22
- Elastic: re-run
deploy/elk/install.shonce: it adds the mapping ofopenconsole.api_key.id/.name,openconsole.admin_scope,openconsole.expires_at,openconsole.api_access,openconsole.by_admin,openconsole.comment,openconsole.mode,openconsole.programandopenconsole.recording_id(the pipeline is unchanged). If you don't, nothing is lost: the fields are mapped dynamically, and get the right type from the next rollover after you run it. - Database: new tables and columns are added on the first start; nothing to do.
- Elasticsearch 8.7 (no
reroute, so noinstall.sh): seedeploy/elk/README.md→ Elasticsearch 8.7 and older for the same steps by hand, an ILM policy, and adding the new fields to the live index. - Logs:
http.requestlines now carryopenconsole.api_key.id/.namefor requests made with a key (also refused ones);openconsole.api_key.id : *separates API from web in the application log as in the audit log. - 403 bodies name the reason (
{"error": "forbidden"},api_key_not_allowed,admin_only,feature_disabled,api_access_policy,api_access_off) instead of a sentence or an empty body; the audit CSV gains a last columnapi_key_name. - API key policy: every existing role starts at Safe read-only API access, so keys made before the upgrade lose exec, edit, scale, restart, ConfigMaps and Secrets until an admin opens a role (Admin → Roles → API access). The keys themselves are not changed: they work as before once the policy allows it.
Upgrading from 2.16
Before 2.17 the outcome was part of the action (deployment.restart.success), reads were a bare verb (list with resource_type: deployments) and details sat in the resource name (boh (restartedAt=…)).
- Database: on the first start of 2.17 the existing audit rows get the new
action,verb,outcomeand a singularresource_type. Their resource names keep the old(k=v)suffix; with the default 30-day retention those rows age out on their own. - API:
?action=deployment.restart.successstill works; the outcome is split off. - Elastic: re-run
deploy/elk/install.sh. The new mapping applies from the next rollover oflogs-openconsole.audit-*(POST logs-openconsole.audit-default/_rolloverto apply it now). The pipeline gives 2.16 lines the 2.17 shape (action without the outcome,openconsole.verb,openconsole.outcome,event.type), so one query finds old and new events. Saved searches, visualizations and alerts that filter onevent.action : *.success/*.deniedmust be changed toevent.action+event.outcome(oropenconsole.outcome). - Console: the extra
deployment.action,workload.action,secret.action,yaml.apply,recording.action,pod.exec.start/pod.exec.end,*.logs.start,user.password_resetanduser.auto_provisionlines are gone, and so are thelevel=errorlinesdeployment.restart.failed,deployment.scale.failed,statefulset.scale.failedand<resource>.apply.failed; theauditline has all their fields. A failed action isevent.outcome : "failure"withevent.reasonanderror.message.level=erroris left for faults in OpenConsole itself (e.g.http.panic).
Upgrading from older versions
- Before 2.13: accounts created then show the source Local in Admin → Users. LDAP accounts switch to LDAP on their next directory sign-in; to fix the sources up front, follow the procedure in the 2.22.0 README.
- Before 2.3: session tokens issued by the old version are honoured until they expire, so an upgrade doesn't sign anyone out.