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 systemsThe 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.