Upgrades

Before you upgradeCopy Anchor Link

• Read the release notes of every version between yours and the new one for values that changed.
• Check that the last nightly backup succeeded: hart admin doctor (check backups).
• Render your values against the new chart; the schema may have changed:

helm template harthelm oci://<your registry>/charts/harthelm --version <new version> \
  -n harthelm-system -f my-values.yaml > /dev/null

UpgradeCopy Anchor Link

helm upgrade harthelm oci://<your registry>/charts/harthelm --version <new version> \
  -n harthelm-system -f my-values.yaml

What happens, in order:

1. The preflight Job checks the cluster against the new values. A failure stops the upgrade before anything changes; its log lists what is missing.
2. The pre-migration dump writes platform/pre-migration-<stamp>.dump to the backup volume (the newest backup.preMigration.keep, 10 by default, are kept). A failed dump stops the upgrade, so no migration runs without a copy.
3. The new core starts, migrates the database and takes over. During a rolling update only the newest core changes workspace objects, so two versions never fight over them.

With core.updateStrategy RollingUpdate (the default) the API stays up; Recreate has a short outage.

Running workspacesCopy Anchor Link

workspaces.upgradePolicy decides:

The IDE's user settings are seeded once, when a workspace's IDE first starts, and then belong to the user. A release that changes the seed reaches new workspaces only.

hart warns its users when its version differs from the server's in major or minor version; they update it as in Install hart.

Roll backCopy Anchor Link

Database migrations only add in a release and remove in a later one, so the previous version runs on the newer schema. Roll back by upgrading to the previous version (or moving the Argo CD pin back):

helm upgrade harthelm oci://<your registry>/charts/harthelm --version <previous version> \
  -n harthelm-system -f my-values.yaml

Restore the pre-migration dump only if the database itself is damaged; see Backups and restore.

Upgrading from 1.4 to 1.5Copy Anchor Link

Nothing needs to be done before the upgrade, and no value changes: 1.5.0 adds no values key and no migration, and the API stays at 0.12. What rolls:

• Core and the router roll as with every release, because their image changes. Core now sends Strict-Transport-Security on the console and logs the installation id when no licence is in force; the router answers CORS for custom domains on public S3 hosts and logs its start-up reconnects at INFO.
• The backup jobs use the new image from their next run. Their dump lines carry tls_verify, and tls now tells the transport that was used (Backups and restore). A log alert or a dashboard that matches tls=false on a PostgreSQL dump line has to follow. The nightly run skips a managed service that has not reported where it listens yet, with the WARN line managed service not ready yet; skipped, instead of failing (A service that is still starting), so a service created just before the run no longer fails the night's Job. The doctor's managed-backups stays the check for an instance that is never dumped.
• The console gains Platform → Doctor for cluster admins (The Doctor page). Nothing to enable.
• Nothing else restarts. No RabbitMQ broker, S3 store, MariaDB, Valkey or PostgreSQL instance, and no workspace or service, is touched: the stores' start arguments are unchanged, and the CORS answer lives in the router.
• hart of 1.4 keeps working; update it from the release's archives to match.
• A site behind a policy of its own that matches response headers may see the new Strict-Transport-Security on the console host. Browsers apply it for a year to that host only.
• Where the release comes from is unchanged for a self-hosted installation: the same chart and images, by the same digests. From 1.5.0 a stable release is also copied, by digest, to the registry the hosted installations pull from; a hosted installation moves its chart pin to 1.5.0 there and changes nothing else.

The 1.4 core keeps working on the same database during the rolling update. See the 1.5.0 release notes.

Upgrading from 1.3 to 1.4Copy Anchor Link

Nothing needs to be done before the upgrade. What happens after it:

• Every RabbitMQ broker restarts once (about 10 to 30 seconds without AMQP; clients reconnect, no service rolls): its configuration gains the single sign-on of the browser hosts. Until a broker has restarted, Open management UI ends at RabbitMQ's login form with "Not_Authorized"; the broker's user and password work. To keep 1.3's behaviour, upgrade with marketplace.browserHosts.enabled: false.
• Every S3 store restarts once (about 20 to 35 seconds without S3) for its new startup probe. With in-cluster TLS on, its new certificate can restart it a second time; from then on the backups reach it over HTTPS on 8443.
• Nothing else restarts: workspaces, services, PostgreSQL, MariaDB and Valkey keep running.
• New values marketplace.browserHosts and marketplace.storageWriteProbe (both on by default). The 1.3 chart's schema rejects them: with your values in Git for Argo CD, move the pin to the 1.4 chart before or with a change of these values.
• API 0.12: a hart of 1.3 warns once a day; update it.
• S3 bucket names that S3 does not accept are refused with a 422 on the next create or update of such a store.
• The doctor has three more checks. managed-storage-write shows a result within a minute or two of the new core becoming the leader. managed-s3-backup-space and managed-s3-blob-gc say skip until the first managed backup run after the upgrade (the nightly one, or a dump on demand) has recorded the backup volume, and warn if none did within 48 hours.
• The restore runbooks come from the release's harthelm-restore-1.4.0.tar.gz from now on (Backups and restore); the S3 restore no longer needs a suspended backup CronJob.

The 1.3 core keeps working on the upgraded database during the rolling update; the migrations only add. See the 1.4.0 release notes.

Upgrading from 1.0 to 1.1Copy Anchor Link

Nothing needs to be done before the upgrade. Three things change at the first start of 1.1:

• A licence is required. An installation upgraded from 1.0 without one runs 30 days in its grace period from that start: nothing is paused, cluster admins see the grace banner and the doctor's license check says what to do. Install the licence within those 30 days, before or after the upgrade; see Licence. With license.existingSecret in the values, the preflight checks the licence already during the upgrade.
• Formats get new names. The availability values are always and on-demand (were always-on and off-when-unused; the console says "Always running" and "Sleeps when idle"), and provider definitions are harthelm/provider-v2 (Managed services). The upgrade renames the stored values and the published definitions; harthelm.yml files and marketplace.builtin.postgres.overrides with the old names keep working and show a note with the new name. Update them when convenient.
• The importer is gone. hart import and the import dialog of the harthelm.yml editor are removed. Files you converted with 1.0 stay as they are.

The 1.0 core keeps working on the upgraded database during the rolling update. See the 1.1.0 release notes.

Values that cannot change freelyCopy Anchor Link

• security.defaultUid cannot change while workspace volumes exist; helm upgrade refuses. See Storage.
• storage.class, storage.mode and the volume size apply to new workspaces only.
• masterKey.existingSecret must keep naming the same key: core refuses to start with a database set up under another one.
• platform.host is part of the OIDC redirect URI and the Git OAuth applications' redirect URIs: change those with it. Both hosts are in your DNS records and certificates.