---
myst:
  html_meta:
    "description lang=en": "Kasm Workspaces Docker Plugin Management"
    "keywords": "Kasm, Plugins, Upgrade, Rollback, Install"
    "property=og:locale": "en_US"
---
```{title} Plugin Management
```

# Plugin Management

Kasm utitilzes Docker Engine Plugins to provide some of its capabilities. For example, the Kasm Network Plugin drives the sidecar network for {doc}`customized workspace egress <./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.
```