Skip to main content
Version: 1.19.0 (latest)

Upgrade Existing Helm Deployment

If you are using the kasm chart, follow the steps below to upgrade your Kasm Helm deployment.

warning

If you are currently on the legacy kasm-single-zone chart, you must first follow the steps in Upgrade Legacy Helm Deployment to upgrade to the kasm chart at version 1.1181.0 before proceeding with this guide.

Upgrade Paths​

This guide covers the following upgrade paths:

  1. Older version → 1.1181.0 — Follow the legacy upgrade guide to upgrade from the old kasm-single-zone chart to the kasm chart at version 1.1181.0.
  2. 1.1181.0 → 1.1190.0 — Follow the steps in this guide.
  3. develop branch → 1.1190.0 — If you installed the Helm chart from the develop branch (between the 1.18.1 and 1.19.0 releases), follow the same 1.1181.0 → 1.1190.0 steps in this guide.

Upgrade from 1.1181.0 to 1.1190.0​

At a Glance​

  1. Retrieve your current values
  2. Review field changes and migrate your values
  3. Run the Helm upgrade
  4. Upgrade standalone PostgreSQL (if applicable)
  5. Verify the upgrade
  6. Kasm log in

1. Retrieve Your Current Values​

Before upgrading, export your current Helm values so you can migrate them to the new chart format.

  • If you deployed using a custom my-values.yaml, retrieve it with:

    helm get values {RELEASE_NAME} -n {NAMESPACE}

    Replace the placeholders:

    • {RELEASE_NAME}: Your Kasm Helm release name. Run helm list -n {NAMESPACE} if you are unsure.
    • {NAMESPACE}: The namespace where your Kasm deployment is running.

  • If you edited values.yaml directly, you will need to diff your changes against the 1.1181.0 defaults to identify what you customised. Follow these steps:

    1. Download the 1.1181.0 default values:

      curl -o default-values.yaml https://raw.githubusercontent.com/kasmtech/kasm-helm/release/1.18.1/charts/kasm/values.yaml

    2. Export your currently deployed values:

      helm -n {NAMESPACE} get values {RELEASE_NAME} --all -o yaml > current-values.yaml

    3. Compare the two files to identify your customisations. The recommended tool is dyff:

      dyff between default-values.yaml current-values.yaml

    Apply the same customisations to the new 1.1190.0 values.yaml, taking into account the field changes described in Step 2.

2. Review Field Changes and Migrate Your Values​

Version 1.1190.0 introduces several renamed, removed, and restructured fields. Review the tables below and update your my-values.yaml accordingly before running the upgrade.

Fields Renamed​

Old field (1.1181.0)New field (1.1190.0)Notes
imagePullSecrets.server + imagePullSecrets.typeimagePullSecrets.registryBoth old fields are merged into a single registry field
kasmZones[].upstream_auth_addrkasmZones[].proxyAddressRenamed to better reflect its purpose
annotationsextraAnnotationsThe nested annotation sub-keys (configMap, cron, deployment, etc.) have moved under extraAnnotations; a new simple annotations: {} top-level key is now used for chart-wide annotations

Fields Removed​

Removed fieldAction required
imagePullSecrets.typeMerged into imagePullSecrets.registry — see above
imagePullSecrets.serverMerged into imagePullSecrets.registry — see above
dbManagement.upgrade.oldDbBackupPvcRemoved; no longer used. Remove from your values.
annotations.certSecret (previously extraAnnotations.certSecret)Use certificate.certManager.annotations instead
extraLabels.certSecretUse certificate.certManager.labels instead

Fields with Behaviour Changes​

FieldChange
database.hostnamePreviously used as the DB service name. Now empty by default and only used when database.standalone: true. Remove this value from your custom values if you are not using a standalone DB.
note

Many new fields and features have been added in 1.1190.0. Refer to the chart documentation for the full list of available configuration options.

Configure Values for the DB Upgrade​

The upgrade chart will automatically back up your existing database, apply the schema migration, and upgrade Kasm. To enable this, add the following to your my-values.yaml:

dbManagement:
  initialize: false
  upgrade:
    enable: true
    oldDbHostname: ""
    backupStorageClass: ""
    oldDbSecretsName: ""
    oldDbBackupFileName: kasm_dump.tar

Replace the placeholders:

  1. oldDbSecretsName: Leave empty ("") in nearly all cases — the chart will auto-resolve to {RELEASE_NAME}-secrets, which is the standard secret name created by 1.1181.0+ deployments. Only set this if you manually renamed the Kasm secrets object before upgrading; if so, the value MUST exactly match the in-cluster secret name. To check the current name, run:

    kubectl -n {NAMESPACE} get secret | grep secrets

  2. oldDbHostname: The database hostname from your previous Helm release. Only required if your old deployment used a non-default DB hostname (i.e. not database.hostname=kasm-db). Leave empty ("") if using a standalone DB, or if you did not change database.hostname from its default value of kasm-db in your previous deployment. If you are unsure, you can check your DB service name by running:

    kubectl -n {NAMESPACE} get service

  3. backupStorageClass: The storage class used to create the PersistentVolume for the backup PVC. Leave empty ("") to use the cluster default.

  4. oldDbBackupFileName: Leave as kasm_dump.tar.

3. Run the Helm Upgrade​

Once your my-values.yaml is ready, run the upgrade:

helm upgrade {RELEASE_NAME} oci://registry-1.docker.io/kasmweb/kasm-helm \
  --version 1.1190.0 --namespace {NAMESPACE} -f my-values.yaml

Classic Helm Repository​

helm repo add kasm https://helm.kasm.com
helm repo update
helm upgrade {RELEASE_NAME} kasm/kasm-helm --version 1.1190.0 --namespace {NAMESPACE} -f my-values.yaml
note

Make sure you are using the same {RELEASE_NAME} as your previous installation.

This will:

  1. Back up the existing database
  2. Apply the schema migration
  3. Upgrade the Kasm deployment

You can monitor the backup job with:

kubectl logs -n {NAMESPACE} -l app.kubernetes.io/component=pre-upgrade-backup

Expected backup job pod output when the backup completes successfully:

Starting backup to /data/kasm-db-dump/kasm_dump.tar
Backup complete

4. Upgrade Standalone PostgreSQL (if applicable)​

warning

Only follow this section if you are using a standalone PostgreSQL database. If you are using the included database, skip to Step 5.

warning

Do NOT upgrade your database until the backup job has finished.

  1. Run the Helm upgrade command from Step 4.
  2. Wait until the pre-upgrade-backup job completes and all new pods are in the Init state: 
    kubectl get pods -n {NAMESPACE}
  3. Once the backup is confirmed complete, upgrade your standalone PostgreSQL instance from version 14 to version 16.
  4. The db-upgrade job will wait for PostgreSQL 16 to be detected before proceeding. You can monitor this with: 
    kubectl -n {NAMESPACE} logs -l app.kubernetes.io/component=db-upgrade -c db-major-version-is-ready
    You will see output like the following while it waits, then a confirmation once the upgrade is detected: 
    PostgreSQL 14.x detected (need 16.x) ... waiting
    ...
    PostgreSQL 14.x detected (need 16.x) ... waiting
    DB not reachable yet... waiting
    ...
    DB not reachable yet... waiting
    PostgreSQL 16.x detected (server_version_num=160012)

5. Verify the Upgrade​

kubectl get pods -n {NAMESPACE}

Confirm all pods have a Running status (job pods should show Completed), then log in to the Kasm web interface to verify the upgrade completed successfully.

6. Kasm Log In​

  • Add your ingress address to your DNS

  • Access your Kasm environment using the publicAddr value you set.

  • For admin and user credentials, see the helm note via:

    helm get notes {RELEASE_NAME} -n {NAMESPACE}

Rollback and Troubleshooting​

Failure during backup​

If the upgrade fails during the backup stage, roll back and clean up the incomplete jobs before retrying:

helm rollback {RELEASE_NAME} -n {NAMESPACE}
kubectl -n {NAMESPACE} delete jobs {RELEASE_NAME}-db-upgrade {RELEASE_NAME}-pre-upgrade-backup

After resolving the underlying issue, re-run the upgrade from Step 3.

For additional troubleshooting assistance, see Kubernetes Troubleshooting.