TIPHYS by Intelligant AI
Docs menu: Upgrading

Upgrading

How to move an install to a newer release of the chart, check it, and go back if you need to. The commands assume the release is named tiphys in the namespace tiphys; change both if yours differ.

Before 1.0, a minor release (0.7 to 0.8) can change behavior or settings, so read What changes in each version for every version you move past. A patch release (0.8.0 to 0.8.1) only fixes bugs.

Before you start

Find the version you run, and the latest:

helm list -n tiphys                       # CHART shows tiphys-<the version you run>
helm show chart oci://ghcr.io/intelligant-ai/charts/tiphys | grep '^version:'

Which jumps work. From 0.4.0 or later you can upgrade in place, straight to the latest: every version only adds to the stored state, so you don't need to stop at each minor on the way. Read the notes for each version you skip. From 0.3.x or earlier, the chart's name changed, so it isn't an upgrade: uninstall and install fresh (reports, approvals and the audit history don't carry over).

Keep your settings in a file. Upgrade with -f values.yaml, not with --reuse-values alone. --reuse-values keeps the previous chart's defaults too, so a setting a new version adds, or a default it changes, never reaches your install. If you installed with --set flags and kept no file, write one from the release:

helm get values tiphys -n tiphys -o yaml > values.yaml

Read it through: it's what you set, and only that.

1. Take a snapshot of the state

Conversations and the audit trail can't be rebuilt, so copy them out first. With persistence.mode: sqlite (the default), back up the database while Tiphys runs and copy the file to your machine:

SNAPSHOT=tiphys-state-$(date +%F).db
kubectl -n tiphys exec tiphys-0 -c backend -- python -c \
  "import sqlite3; s = sqlite3.connect('/var/lib/tiphys/state.db'); d = sqlite3.connect('/tmp/state-backup.db'); s.backup(d); d.close(); s.close()"
kubectl -n tiphys cp -c backend tiphys-0:/tmp/state-backup.db "./$SNAPSHOT"

With persistence.mode: configmap, the state is ConfigMaps:

kubectl -n tiphys get configmap -o yaml > tiphys-state-$(date +%F).yaml

If your cluster takes volume snapshots, a snapshot of the state-tiphys-0 claim works too (Backup and Restore has the steps).

2. Upgrade

helm upgrade tiphys oci://ghcr.io/intelligant-ai/charts/tiphys -n tiphys \
  --version 0.8.0 -f values.yaml

Always name the version. Without --version, Helm takes the newest chart there is, which may be a newer minor than the one whose notes you read.

The pod restarts once. The app shows "Reconnecting to Tiphys..." for the few seconds the new pod takes to mount the volume.

3. Check it

kubectl -n tiphys rollout status statefulset/tiphys --timeout=5m
kubectl -n tiphys get pod tiphys-0 \
  -o jsonpath='{.spec.initContainers[*].image} {.spec.containers[*].image}{"\n"}'

Both images should carry the new version. (The backend runs as a sidecar, so it's listed with the init containers.) Then open Tiphys, sign in, and check that your reports, conversations and the Audit page are there.

Going back

Helm keeps each release's revisions. Find the one before the upgrade and roll back to it:

helm history tiphys -n tiphys
helm rollback tiphys <revision> -n tiphys
kubectl -n tiphys rollout status statefulset/tiphys --timeout=5m

This puts back the earlier chart, images and settings.

An older version reads newer state. Nothing is migrated in a way that can't be read back: an older version creates the tables it knows, leaves the others alone, and reads the fields it knows from each record. What it doesn't know is kept on disk. Two things to expect:

  • A record the older version changes (a conversation you continue, an approval you decide) is saved without the fields only the newer version knew.
  • From 0.8.0 back to 0.7.0: 0.7.0 shows its own audit log, as it was at the upgrade, not the audit trail. The trail's events stay in the file and show again when you upgrade. What 0.7.0 records meanwhile isn't copied into the trail.

If the rollback doesn't come back clean, restore the snapshot from step 1 into the running pod, then restart it:

SNAPSHOT=tiphys-state-<date>.db           # the file from step 1
kubectl -n tiphys cp -c backend "./$SNAPSHOT" tiphys-0:/tmp/state-restore.db
kubectl -n tiphys exec tiphys-0 -c backend -- python -c \
  "import sqlite3; s = sqlite3.connect('/tmp/state-restore.db'); d = sqlite3.connect('/var/lib/tiphys/state.db'); s.backup(d); d.close(); s.close()"
kubectl -n tiphys delete pod tiphys-0

In ConfigMap mode, kubectl apply -f the file you saved, then delete the pod.

Changing the state volume

A StatefulSet's volume template can't be changed in place, so an upgrade that changes persistence.size or persistence.storageClass fails. The error names spec.volumeClaimTemplates and says field is immutable (older clusters say spec: Forbidden: updates to statefulset spec for fields other than ...). Nothing in the cluster changes when it fails; Helm only records a failed revision. Do one of these instead.

Making the volume bigger

The claim's StorageClass must allow it: kubectl get storageclass shows ALLOWVOLUMEEXPANSION true. Volumes can only grow.

  1. Grow the claim itself:

    kubectl -n tiphys patch pvc state-tiphys-0 \
  -p '{"spec":{"resources":{"requests":{"storage":"10Gi"}}}}'

  2. Remove the StatefulSet but keep its pod and volume running:

    kubectl -n tiphys delete statefulset tiphys --cascade=orphan

  3. Set persistence.size: 10Gi in values.yaml and upgrade at the version you run. Helm makes the StatefulSet again, and it takes the running pod back:

    VERSION=$(helm get metadata tiphys -n tiphys | awk '/^VERSION:/ {print $2}')
helm upgrade tiphys oci://ghcr.io/intelligant-ai/charts/tiphys -n tiphys \
  --version "$VERSION" -f values.yaml

  4. kubectl -n tiphys get pvc state-tiphys-0 shows the new capacity. If it still shows the old one and the claim's conditions say FileSystemResizePending, restart the pod (kubectl -n tiphys delete pod tiphys-0) to finish.

Moving to another StorageClass

A claim can't change its class, so the state moves to a new volume:

  1. Take the snapshot in step 1 above.

  2. Remove the StatefulSet and its claim. This deletes the state on the volume, so check the snapshot file is there first:

    kubectl -n tiphys delete statefulset tiphys
kubectl -n tiphys delete pvc state-tiphys-0

  3. Set persistence.storageClass in values.yaml and upgrade at the version you run, as in step 3 of the section above. Tiphys starts on an empty volume of the new class.

  4. Restore the snapshot into it, as in Going back. The empty volume made a new initial admin password; once the snapshot is back, sign in with the password you had before.

Switching persistence.mode

Switching between sqlite and configmap starts Tiphys with empty state. Nothing is moved from one to the other: reports, approvals, the audit trail and conversations stay where the old mode kept them.

  • From sqlite to configmap, the chart replaces the StatefulSet with a Deployment. The state-tiphys-0 claim is left behind, untouched, and auth.builtin.existingSecret is required.
  • From configmap back to sqlite, the StatefulSet picks up that claim again if it's still there, and what was recorded in ConfigMap mode stays in its ConfigMaps.

Pick the mode at install time, and change it only when you can start over.

What changes in each version

Only what matters when you upgrade: settings, defaults, and behavior you might notice. Each version is a fresh read of the chart's defaults, so a new setting below takes its default unless your values.yaml sets it.

0.8.0

  • Signing out after inactivity. With the built-in sign-in, a sign-in nobody uses for 15 minutes ends. Set auth.builtin.sessionIdleMinutes (0 turns it off). A sign-in from before the upgrade counts from when it began, so one older than that ends when 0.8.0 starts; sign in again.
  • The audit trail replaces the audit log. The earlier log is copied in once, on the first start, and left in place, read only. New settings: audit.retentionDays (365; -1 keeps everything) and audit.adminGroups (proxy mode: the groups that see everyone's events). In ConfigMap mode the trail keeps its newest 800 events.
  • Only X-Tiphys-Csrf counts as the CSRF header. A script that sends the previous header gets a 403 on every write until it sends this one.
  • Tiphys's own namespace is detected from the pod, and stays protected wherever it runs. The protected list no longer names the install namespace of the product's earlier releases.
  • Server-side apply uses the field manager tiphys. Fields an earlier version applied stay owned by the earlier manager.
  • New: agent.logLevel (info).

0.7.0

  • Investigations have a time budget: llm.investigationMinutes, 10 by default. Tiphys wraps up at 80% and pauses at 100%, and you can go on. 0 turns it off.
  • llm.provider takes anthropic, vertex and azure too.

0.6.0

  • Costs are list-price estimates. Cost Explorer is off by default, since AWS bills each request; turn it on with modules.cloud.billedCosts.enabled.
  • Tiphys no longer writes infrastructure code or changes the platform under your workloads. It hands those over as a platform request.

0.5.x

  • 0.5.0: the built-in sign-in is the default. auth.mode was proxy. If you sign in through an SSO ingress and never set auth.mode, set auth.mode: proxy in values.yaml before upgrading, or people's identities stop reaching the audit trail.
  • 0.5.3: state lives under /var/lib/tiphys. The chart mounts the same volume at the new path, so nothing moves. Browser preferences reset once.
  • 0.5.5: controlPlane (off by default).
PreviousUI access (ingress, auth)NextWrite operations