Multi Server Upgrade
Warning
When running any upgrade please ensure there are no active Kasm Workspaces sessions running. On large deployments this will likely require a maintenance window.
Manually
Please read through the entire process before getting started.
Issues can be reported on the Kasm Workspaces Issues Page
Warning
The Kasm Workspaces 1.12.0 upgrade will install a new set of default desktop and application images. Please ensure 50GB of free space is available on the Kasm server ( or Agent role server for multi-server installations) prior to upgrading.
Stop all Kasm Services on all Servers
sudo /opt/kasm/bin/stop
Upgrade Database Server Role
Create a Database Backup
Ensure Kasm services are stopped on all hosts. Database corruption can occur if Kasm services are still connected to the database when it goes down.
Note
If your database is a standalone remote database refer here for backup instructions. Backing up the PostgreSQL Server.
sudo /opt/kasm/bin/stop
Execute the database backup utility
sudo mkdir -p /opt/kasm/backups/ sudo bash /opt/kasm/1.11.0/bin/utils/db_backup -f /opt/kasm/backups/kasm_db_backup.tar -p /opt/kasm/1.11.0/
Verify the presence and location of the database backup
sudo ls -al /opt/kasm/backups/kasm_db_backup.tar
Download and extract the new installation media
cd /tmp/ curl -O https://kasm-static-content.s3.amazonaws.com/kasm_release_1.12.0.d4fd8a.tar.gz tar -xf kasm_release_*.tar.gz
Note
If you are performing an offline upgrade please ensure that you have downloaded and installed versions of docker and docker compose that meet the updated system requirements see System Requirements for details.
Get the existing database password for use in the subsequent commands.
sudo grep " password" /opt/kasm/1.11.0/conf/app/api.app.config.yaml
Get the existing redis password for use in the subsequent commands.
sudo grep "redis_password" /opt/kasm/1.11.0/conf/app/api.app.config.yaml
Perform a clean install
Perform a clean install of the Database Role Services
Note
If your database is a standalone remote database refer here for clean install instructions. Initializing PostgreSQL Server.
Install kasm from the release media downloaded in the prior steps.
When performing an offline update add these flags
--offline-workspaces <KASM_WORKSPACE_IMAGES_TAR> --offline-service <KASM_SERVICE_IMAGES_TAR>
sudo bash kasm_release/install.sh -S db -D -Q <DATABASE_PASSWORD> -R <REDIS_PASSWORD>
Restore and upgrade the database
Restore and update the database from the prior version
Ensure all Kasm services are stopped on all hosts
Note
If your database is a standalone remote database refer here for restoration instructions. Restoring the PostgreSQL server from a backup.
sudo /opt/kasm/bin/stop
Execute the database restore command
sudo /opt/kasm/1.12.0/bin/utils/db_restore -f /opt/kasm/backups/kasm_db_backup.tar -p /opt/kasm/1.12.0/
Perform an upgrade of the database schema
Note
If your database is a standalone remote database refer here for upgrade instructions. Standalone Remote Database.
sudo /opt/kasm/1.12.0/bin/utils/db_upgrade -p /opt/kasm/1.12.0
Advanced: Review the contents of the existing configs to ensure any custom docker settings are migrated to the new configuration.
diff /opt/kasm/1.11.0/docker/docker-compose.yaml /opt/kasm/1.12.0/docker/docker-compose.yaml
Install The Kasm 1.12.0 Default Images for your platform
If doing an offline upgrade first extract the default image seed data from the workspace images tar
For x86 (amd64) platforms:
tar xf <KASM_WORKSPACE_IMAGES_TAR> --strip-components=1 -C /opt/kasm/1.12.0/conf/database/seed_data/ workspace_images/default_images_amd64.yaml
For ARM (arm64) platforms:
tar xf <KASM_WORKSPACE_IMAGES_TAR> --strip-components=1 -C /opt/kasm/1.12.0/conf/database/seed_data/ workspace_images/default_images_arm64.yaml
For x86 (amd64) platforms:
sudo /opt/kasm/1.12.0/bin/utils/db_init -s /opt/kasm/1.12.0/conf/database/seed_data/default_images_amd64.yaml
For ARM (arm64) platforms:
sudo /opt/kasm/1.12.0/bin/utils/db_init -s /opt/kasm/1.12.0/conf/database/seed_data/default_images_arm64.yaml
Start the Kasm services
sudo /opt/kasm/bin/start
Upgrade Web App Server Role
Stop existing Kasm Services
sudo /opt/kasm/bin/stop
Download and extract the new installation media
cd /tmp/
curl -O |release_url|
tar -xf kasm_release_*.tar.gz
Note
If you are performing an offline upgrade please ensure that you have downloaded and installed versions of docker and docker compose that meet the updated system requirements see System Requirements for details.
Install kasm from the release media downloaded in the prior steps.
When performing an offline update add this flag
--offline-service <KASM_SERVICE_IMAGES_TAR>
sudo bash kasm_release/install.sh -S app -D -q <DATABASE_HOSTNAME> -Q <DATABASE_PASSWORD> -R [REDIS_PASSWORD]
Copy manager_id and server_hostname from the old configuration into the new
grep manager_id /opt/kasm/1.11.0/conf/app/api.app.config.yaml grep server_hostname /opt/kasm/1.11.0/conf/app/api.app.config.yaml sudo vi /opt/kasm/1.12.0/conf/app/api.app.config.yaml
Advanced: Review the contents of the existing configs to ensure any custom docker settings are migrated to the new configuration.
diff /opt/kasm/1.11.0/docker/docker-compose.yaml /opt/kasm/1.12.0/docker/docker-compose.yaml
Start the Kasm services
sudo /opt/kasm/bin/start
Upgrade Agent Server Role
Ensure all Kasm services are stopped
sudo /opt/kasm/bin/stop
Download and extract the new installation media
cd /tmp/ curl -O https://kasm-static-content.s3.amazonaws.com/kasm_release_1.12.0.d4fd8a.tar.gz tar -xf kasm_release_*.tar.gz
Get the existing manager token for use in the subsequent commands.
sudo grep "token" /opt/kasm/1.11.0/conf/app/agent.app.config.yaml
Note
If you are performing an offline upgrade please ensure that you have downloaded and installed versions of docker and docker compose that meet the updated system requirements see System Requirements for details.
Install kasm from the release media downloaded in the prior steps.
When performing an offline update add these flags
--offline-workspaces <KASM_WORKSPACE_IMAGES_TAR> --offline-service <KASM_SERVICE_IMAGES_TAR>
sudo bash kasm_release/install.sh -S agent -D -p <AGENT_HOSTNAME> -m <MANAGER_HOSTNAME> -M <MANAGER_TOKEN>
Copy the server_id and the public_hostname properties from the old agent to the new
grep server_id /opt/kasm/1.11.0/conf/app/agent.app.config.yaml grep public_hostname /opt/kasm/1.11.0/conf/app/agent.app.config.yaml sudo vi /opt/kasm/1.12.0/conf/app/agent.app.config.yaml
Copy the auto-generated nginx configs for any sessions that may exists on the Agent
sudo cp /opt/kasm/1.11.0/conf/nginx/containers.d/* /opt/kasm/1.12.0/conf/nginx/containers.d/
Advanced: Review the contents of the existing configs to ensure any custom docker settings are migrated to the new configuration.
diff /opt/kasm/1.11.0/docker/docker-compose.yaml /opt/kasm/1.12.0/docker/docker-compose.yaml diff /opt/kasm/1.11.0/conf/app/agent.app.config.yaml /opt/kasm/1.12.0/conf/app/agent.app.config.yaml
Start the Kasm services
sudo /opt/kasm/bin/start
Verify the Agent Service is properly checking into the Manager Service. Log into the UI as an Administrator. Select Agents and verify the Agent is listed with a Last Reported time of less than 1 minute. If the agent has not checked in, it likely can’t resolve or connect to [AGENT_HOSTNAME]:443 . Inspect the logs for details.
sudo tail -f /opt/kasm/current/log/agent.log
(Optional) Install the Connection Proxy (Guac) Role
The Connection Proxy role is new in Workspaces 1.12.0. This service is used to connect to VM/Hardaward running RDP. If these capabilities are not needed, this role does not need to be installed.
Login to the Workspaces UI as an administrator. Retrieve the value of Component Registration Token from the Global Settings.
Download and extract the new installation media
cd /tmp/ curl -O https://kasm-static-content.s3.amazonaws.com/kasm_release_1.12.0.d4fd8a.tar.gz tar -xf kasm_release_*.tar.gz
Install the Connection Proxy role from the release media downloaded in the prior steps.
When performing an offline update add these flags
--offline-workspaces <KASM_WORKSPACE_IMAGES_TAR> --offline-service <KASM_SERVICE_IMAGES_TAR>
sudo bash kasm_release/install.sh --role guac --api-hostname [MANAGER_HOSTNAME] --public-hostname [CONNECTION_PROXY_HOSTNAME] --registration-token [SERVICE_REGISTRATION_TOKEN]
Update Custom Workspaces
Each release, the Kasm Technologies team updates the default workspaces with new features and security updates. The previous steps added the new default workspaces to the upgraded system. Old workspaces should be removed as they are not compatible with new Kasm features.
If you are running custom Docker images, rebuild each Docker image using the latest Docker image. (e.g : kasmweb/core-ubuntu-focal:1.12.0 ) , and create a new Workspace entry in the Kasm UI. Do not re-use existing Workspace entries for custom Docker images.
See Default and Custom Docker Images for details.
Upgrade Script
Since Kasm Workspaces version 1.11.0 an upgrade script is included with the installation package under kasm_release/upgrade.sh.
Note
Before starting the upgrade process please ensure that the Web App servers are stopped. If left running there is a chance for database corruption on your Webb App servers
sudo /opt/kasm/bin/stop
The upgrade script can be found in the installation package under kasm_release/upgrade.sh.
These instructions assume there are 3 servers with the app, db, and agent roles.
Login to your db server and execute:
cd /tmp curl -O https://kasm-static-content.s3.amazonaws.com/kasm_release_1.12.0.d4fd8a.tar.gz tar -xf kasm_release_1.12.0.d4fd8a.tar.gz sudo bash kasm_release/upgrade.sh --role db
cd /tmp curl -O https://kasm-static-content.s3.amazonaws.com/kasm_release_1.12.0.d4fd8a.tar.gz curl -O https://kasm-static-content.s3.amazonaws.com/kasm_release_service_images_amd64_1.12.0.d4fd8a.tar.gz curl -O https://kasm-static-content.s3.amazonaws.com/kasm_release_workspace_images_amd64_1.12.0.d4fd8a.tar.gz tar -xf kasm_release_1.12.0.d4fd8a.tar.gz sudo bash kasm_release/upgrade.sh --role db --offline-workspaces /tmp/kasm_release_workspace_images_amd64_1.12.0.d4fd8a.tar.gz --offline-service /tmp/kasm_release_service_images_amd64_1.12.0.d4fd8a.tar.gz
cd /tmp curl -O https://kasm-static-content.s3.amazonaws.com/kasm_release_1.12.0.d4fd8a.tar.gz curl -O https://kasm-static-content.s3.amazonaws.com/kasm_release_service_images_arm64_1.12.0.d4fd8a.tar.gz curl -O https://kasm-static-content.s3.amazonaws.com/kasm_release_workspace_images_arm64_1.12.0.d4fd8a.tar.gz tar -xf kasm_release_1.12.0.d4fd8a.tar.gz sudo bash kasm_release/upgrade.sh --role db --offline-workspaces /tmp/kasm_release_workspace_images_arm64_1.12.0.d4fd8a.tar.gz --offline-service /tmp/kasm_release_service_images_arm64_1.12.0.d4fd8a.tar.gz
Login to your agent server and execute:
cd /tmp curl -O https://kasm-static-content.s3.amazonaws.com/kasm_release_1.12.0.d4fd8a.tar.gz tar -xf kasm_release_1.12.0.d4fd8a.tar.gz sudo bash kasm_release/upgrade.sh --role agent
cd /tmp curl -O https://kasm-static-content.s3.amazonaws.com/kasm_release_1.12.0.d4fd8a.tar.gz curl -O https://kasm-static-content.s3.amazonaws.com/kasm_release_service_images_amd64_1.12.0.d4fd8a.tar.gz curl -O https://kasm-static-content.s3.amazonaws.com/kasm_release_workspace_images_amd64_1.12.0.d4fd8a.tar.gz tar -xf kasm_release_1.12.0.d4fd8a.tar.gz sudo bash kasm_release/upgrade.sh --role agent --offline-workspaces /tmp/kasm_release_workspace_images_amd64_1.12.0.d4fd8a.tar.gz --offline-service /tmp/kasm_release_service_images_amd64_1.12.0.d4fd8a.tar.gz
cd /tmp curl -O https://kasm-static-content.s3.amazonaws.com/kasm_release_1.12.0.d4fd8a.tar.gz curl -O https://kasm-static-content.s3.amazonaws.com/kasm_release_service_images_arm64_1.12.0.d4fd8a.tar.gz curl -O https://kasm-static-content.s3.amazonaws.com/kasm_release_workspace_images_arm64_1.12.0.d4fd8a.tar.gz tar -xf kasm_release_1.12.0.d4fd8a.tar.gz sudo bash kasm_release/upgrade.sh --role agent --offline-workspaces /tmp/kasm_release_workspace_images_arm64_1.12.0.d4fd8a.tar.gz --offline-service /tmp/kasm_release_service_images_arm64_1.12.0.d4fd8a.tar.gz
Login to your Web App server and execute:
cd /tmp curl -O https://kasm-static-content.s3.amazonaws.com/kasm_release_1.12.0.d4fd8a.tar.gz tar -xf kasm_release_1.12.0.d4fd8a.tar.gz sudo bash kasm_release/upgrade.sh --role app
cd /tmp curl -O https://kasm-static-content.s3.amazonaws.com/kasm_release_1.12.0.d4fd8a.tar.gz curl -O https://kasm-static-content.s3.amazonaws.com/kasm_release_service_images_amd64_1.12.0.d4fd8a.tar.gz tar -xf kasm_release_1.12.0.d4fd8a.tar.gz sudo bash kasm_release/upgrade.sh --role app --offline-service /tmp/kasm_release_service_images_amd64_1.12.0.d4fd8a.tar.gz
cd /tmp curl -O https://kasm-static-content.s3.amazonaws.com/kasm_release_1.12.0.d4fd8a.tar.gz curl -O https://kasm-static-content.s3.amazonaws.com/kasm_release_service_images_arm64_1.12.0.d4fd8a.tar.gz tar -xf kasm_release_1.12.0.d4fd8a.tar.gz sudo bash kasm_release/upgrade.sh --role app --offline-service /tmp/kasm_release_service_images_arm64_1.12.0.d4fd8a.tar.gz
You can also handle basic image management functions using the helper flags during the upgrade process:
Flag Description
---------------------------------------------------------------------------------------------------------------
| -h|--help | Display this help menu |
| -L|--proxy-port | Default Proxy Listening Port |
| -I|--no-images | Don't seed or pull default Workspaces Images |
| -U|--upgrade-images | Upgrade Images to current set purging previous images |
| -K|--add-images | Ingest the latest images keeping old images in place |
| -w|--offline-workspaces | Path to the tar.gz workspace images offline installer |
| -s|--offline-service | Path to the tar.gz service images offline installer |
| -S|--role | Role to Upgrade: [app|db|agent|remote_db|guac|proxy] |
| -g|--database-master-user | Database master username required for remote DB |
| -G|--database-master-password | Database master password required for remote DB |
| -q|--db-hostname | Database Hostname needed when upgrading agent and pulling images |
| -T|--db-port | Database port needed when upgrading agent and pulling images (default 5432) |
| -Q|--db-password | Database Password needed when upgrading agent and pulling images |
| -b|--no-check-disk | Do not check disk space |
| -n|--api-hostname | Set API server hostname |
| -A|--enable-lossless | Enable lossless streaming option (1.12 and above) |
| -O|--use-rolling-images | Use rolling Workspaces images |
---------------------------------------------------------------------------------------------------------------