Plugin Management

Kasm utitilzes Docker Engine Plugins to provide some of its capabilities. For example, the Kasm Network Plugin drives the sidecar network for customized workspace egress. Although they are hosted on the same registries as container images, plugins are treated differently by Docker and have different workflows for maintenance. Notably, the system can’t simply pull a plugin to update it.

Automated Updates

Kasm automatically attempts to upgrade Kasm Docker plugins with rolling identifiers in their names (see the “Determining Alias” section below). This will happen every time the /opt/kasm/bin/start command is run, along with the pull for rolling service images. The script will only update a given plugin if there are no other active system components using it, such as containers or docker networks.

A ledger file is maintained for each plugin modified by this script. The file records information about each installed version.

Rollback

If a plugin upgrade needs to be rolled back, it can be accomplished through one of Kasm’s provided scripts. The snippet below will reinstall the most recent previous version of the plugin; if you upgraded from version A to version B, rollback would target version A.

Warning

Rolling back a plugin will pin the plugin to the rollback version. This removes the rolling tag from the plugin; it will no longer be automatically updated by the /opt/kasm/bin/start script.

sudo /opt/kasm/bin/stop
# Determine the name of the plugin, as seen in the output of 
# sudo docker plugin ls
plugin_name=
sudo /opt/kasm/bin/utils/upgrade_plugins --rollback --name "$plugin_name"

If the last stable version cannot be determined, the script will not modify the plugin. In that event, you should browse the plugin’s repository and determine which version you would like to install. Use that tag as the --version in the “Reinstallation” section below.

Reinstallation

Kasm provides a script that will install an arbitrary version of a Kasm Docker plugin present on the system.

Determining Name

Use sudo docker plugin ls to determine the names of Kasm Docker plugins.

Determining Version (Tag)

Plugin tags can be viewed on the source registry. Alternatively, you can use the following script to query for the lastest patch-level tag found on the registry. In the snippet, we query for the plugin used by the sidecar network, for the latest x86_64 version of the 1.2 plugin release.

sudo /opt/kasm/bin/utils/plugin_helper 'kasmweb/kasm-network-plugin:amd64-1.2' --latest

Use arm64 for ARM architecture systems
The tag must provide the architecture, but can specify Major.Minor versions (e.g. 1.2), just Major version (e.g. 1), or omit the version entirely

Determining Alias

Alias is optional. Provide a plugin alias if you want the installed plugin to use a Name different than the registry reference. The plugin used by the egress feature has an alias of kasmweb/sidecar:{tag}

Warning

Providing an alias that matches /-rolling.*$/ will tell kasm to automate updates to this plugin, even if the registry reference isn’t a rolling tag. Don’t mix and match “rolling”!

Script Execution

Basic usage:

sudo /opt/kasm/bin/stop
# Determine the name of the plugin, as seen in the output of 
# sudo docker plugin ls
plugin_name=
sudo /opt/kasm/bin/utils/upgrade_plugins --reinstall --name "$plugin_name" --version "$plugin_version" --alias "$plugin_alias"

Force Upgrade

To force upgrade a Kasm Docker plugin to the latest version, use the following script.

sudo /opt/kasm/bin/stop
# Determine the name of the plugin, as seen in the output of 
# sudo docker plugin ls
plugin_name=
sudo /opt/kasm/bin/utils/upgrade_plugins --name "$plugin_name"

Note

This always pulls down the latest image from the registry, even if it is the same as the currently installed version.