--- myst: html_meta: "description lang=en": "Support for 1 click installation of workspaces." "keywords": "Kasm, Workspace, App Store, Workspace Registry, Applications" "property=og:locale": "en_US" --- ```{title} Workspace Registry ``` # Workspace Registry ```{figure} /images/workspace_registry/registry_workspaces.webp :align: center **Installing workspaces in Kasm** ``` The Workspace Registry is a mechanism for allowing users to easily install workspaces. This can be from our own 1st party registry or from 3rd party registries. The intention was twofold. First to make it as simple as possible for users to add workspaces without needing to fill in lots of fields, and secondly to make it as simple as possible for anyone to create their own registries without us needing to be gatekeepers. ## Video Tutorial ```{raw} html ``` ## 1st Party Registry ```{figure} /images/workspace_registry/registry_1stparty.webp :align: center **1st Party Workspace Registry** ``` The 1st party registry comes pre-installed in Kasm Workspaces 1.13.0 or newer and makes it simple to install any of our workspaces that aren't already installed on your system. ```{note} If you remove the 1st party registry and want it back at any point, our registry store front is located at [https://registry.kasmweb.com/](https://registry.kasmweb.com/) ``` ## 3rd Party Registry ```{figure} /images/workspace_registry/registry_3rdparty.webp :align: center **3rd Party Workspace Registries** ``` 3rd Party repositories allow external developers to create their own workspaces that will work seamlessly with Kasm Workspaces. ```{warning} You should only install registries from 3rd parties that you trust, and even then before installing a workspace you should check to see what commands are being executed. There are a couple of ways this can be done: 1. Click on a workspace tile and instead of clicking install, click on edit. 1. From the Registry page where you got the Workspace Registry Link, clicking on one of the workspaces takes you to a page that displays all the JSON for that workspace (you can also get to this by clicking the registry logo in the list on registries at the top of the page). Either of these 2 options allows you to see everything that is being set. Pay particular attention to anything in the `Docker Run Config Override (JSON)` field (`run_config` in the workspace JSON) or the `Docker Exec Config (JSON)` field (`exec_config` in the workspace JSON) as these fields allow arbitrary commands to be run. If either of these fields are populated and you are unsure of what they are doing, ask the 3rd party to clarify before blindly installing. ``` ## Installing Workspaces To install a workspace, click on the workspace you want to install then click on the install button that appears. If you want to see exactly what is being installed you can click on the edit button instead. ```{figure} /images/workspace_registry/install_workspace.webp :align: center **Installing a workspace** ``` Once you click on the install button, the estimated required space will be added to the size widget located at the top of the screen next to the list of stores. As workspaces finish installing the sizes will recalculate based on the actual size taken. ```{figure} /images/workspace_registry/install_widget.webp :align: center **Estimating workspace requirements** ``` The estimated size is the uncompressed size, and so should be a worst case scenario as any duplicate layers will lower the amount of space used up. The space remaining is based on the remaining space on every agent combined, however by default workspaces are installed on all available agents so potentially it could take up more space then expected. ## Configuration Warnings If a workspace has a red border and a red exclamation triangle to the left of the name, this indicates that the workspace has been flagged as requiring review before installation. ```{figure} /images/workspace_registry/workspace-warning.webp :align: center **A workspace that requires review** ``` The reason for the workspace being flagged will be that it has defined a configuration that may provide elevated privileges or access. The warning doesn't mean that there is a problem with the workspace, just that you should review what it is doing prior to installation. For example, many of the linuxserver.io workspaces are flagged with a warning. By hovering over the exclamation you will receive a tooltip with more information. ```{figure} /images/workspace_registry/warning-tooltip.webp :align: center **A workspace that requires review** ``` This tells you that if you click on the edit button instead of install, you should head to the `Docker Run Config Override (JSON)` section and look at the value of the **security_opt** property as that is what triggered the warning. ```{figure} /images/workspace_registry/settings.webp :align: center **Settings that caused a flag** ``` In this case multiple properties are set. `user` is set, but it's set to 1000 so doesn't cause a flag. `entrypoint` is set but is on the list of ignored properties so also doesn't cause a flag. `security_opt` is not on the ignored list and so does cause a flag. We haven't included specific information for security_opt so it gets labeled with the generic `flag_property` identifier (that can be seen as the last item in the tooltip and is the link to this website so you can look up the meaning in the table below). In this specific case the workspace requires a minimum specific version of libseccomp to run, as a convenience the linuxserver.io workspaces are adding `"security_opt":["seccomp=unconfined"]` to ensure that users can just click install and get a functioning workspace. On the downside this does mean the workspace will run without the docker seccomp sandbox and will significantly reduce the amount of protection that Kasm Workspaces can provide. There may be multiple properties that caused a warning and they should all be listed in the tooltip. After the property that caused a flag there is a link to this website with a value to look up on the table below for more information. ```{eval-rst} +-----------------------+------------------------------------------------------------------------------------------------------+ | Property | Description | +=======================+======================================================================================================+ | user_error | A user has been defined and it's not set to 1000. This often means the user has been set to root. | | | Some workspaces may need to be run as root to function correctly so it's not necessarily a major | | | cause for concern, you should just be more cautious and understand that the workspace has elevated | | | privileges. | +-----------------------+------------------------------------------------------------------------------------------------------+ | privilege | This workspace is running in privileged mode which grants the workspace root capabilities to all | | | devices on the host | +-----------------------+------------------------------------------------------------------------------------------------------+ | flag_property | This is a generic flag. What this means is the property that was flagged is not in the list of | | | ignored or safe properties but we haven't added specific information on it yet. You should look up | | | what the property does and if it's a cause for concern manually. | +-----------------------+------------------------------------------------------------------------------------------------------+ ``` ## Updates Automatic updates are **on** by default with the official Kasm registry, and **off** for 3rd party registries. You can change this by clicking on the ellipsis button on a registry and ticking or unticking `Automatic Updates`. When automatic updates are on, the registry will be updated when you hit the registrly list page. Whether automatic updates are on or off there is a button to manually update the registry as well. Updating a registry will pull the latest available workspaces and any updated configuration but wont affect any currently installed workspaces. ```{figure} /images/workspace_registry/kasm-updates.gif :align: center **Update a registry** ``` ## Search and filter When on the registry page the same search and category options are available in the top right as when you are on the workspaces page. These allow you to search for specific workspaces or categories. ```{figure} /images/workspace_registry/search-cat.webp :align: center **Searching and selecting a category** ``` You can also click on the mini workspace icons under a registries name to just show that registries workspaces. Finally, once you are finished, you can click the **Clear Filters** button next to `Available Workspaces` to easily bring all the options back. ```{figure} /images/workspace_registry/registry-filter.webp :align: center **Searching and selecting a category** ``` ## Create your own workspace registry We have worked hard to try and make it as simple as possible for 3rd party developers to build and maintain their own Workspace Registries. With that goal in mind we have a [github template repository](https://github.com/kasmtech/workspaces_registry_template) which can be used as a basis for your own workspace registry. Full instructions on how to create a registry are included in the README there. ### Schema **Current version:** 1.0 ```{eval-rst} +-----------------------+----------+------------------------------------------------------------------------------------------------------+ | Property | Required | Description | +=======================+==========+======================================================================================================+ | friendly_name | True | The name to show | +-----------------------+----------+------------------------------------------------------------------------------------------------------+ | name | True | The docker image to use | +-----------------------+----------+------------------------------------------------------------------------------------------------------+ | description | True | A short description of the workspace | +-----------------------+----------+------------------------------------------------------------------------------------------------------+ | image_src | True | The name of the workspace icon used | +-----------------------+----------+------------------------------------------------------------------------------------------------------+ | architecture | True | Json list containing either "amd64", "arm64" or both | +-----------------------+----------+------------------------------------------------------------------------------------------------------+ | compatability | True | A list of Kasm versions the workspace should work with | +-----------------------+----------+------------------------------------------------------------------------------------------------------+ | uncompressed_size_mb | True | Integer of the approximate size of the workspace when it's uncompressed in MB. This doesn't take | | | | into account layers. For example if an image is 2.46GB you would enter 2460 | +-----------------------+----------+------------------------------------------------------------------------------------------------------+ | categories | False | Json list containing the categories the workspace belongs too. This should be limited to a max of 3. | +-----------------------+----------+------------------------------------------------------------------------------------------------------+ | docker_registry | False | Which docker registry to use | +-----------------------+----------+------------------------------------------------------------------------------------------------------+ | run_config | False | Any additional parameters to add to the run config | +-----------------------+----------+------------------------------------------------------------------------------------------------------+ | exec_config | False | Any additional parameters to add to the exec config | +-----------------------+----------+------------------------------------------------------------------------------------------------------+ | notes | False | Notes about running the workspace, such as if it requires libseccomp. | +-----------------------+----------+------------------------------------------------------------------------------------------------------+ | cores | False | Specify the amount of cores to use for this workspace | +-----------------------+----------+------------------------------------------------------------------------------------------------------+ | memory | False | Specify the amount of memory to use for this workspace | +-----------------------+----------+------------------------------------------------------------------------------------------------------+ | gpu_count | False | Specify the amount of GPUs to use for this workspace | +-----------------------+----------+------------------------------------------------------------------------------------------------------+ | cpu_allocation_method | False | What CPU allocation method to use for this workspace. Can be either "Inherit", "Quotas" or "Shares" | +-----------------------+----------+------------------------------------------------------------------------------------------------------+ ```
## Using workspace registries in Kasm The idea behind Workspace Registries was to try and make it as simple as possible to add and delete the registries. ```{figure} /images/workspace_registry/add-new-registry.webp :align: center **Adding a registry** ```
1. Find a workspace registry. 1. Click the "Workspace Registry Link" button. 1. In Kasm click on the "Workspaces" navigation link. 1. Click on the "Workspace Registry" button. 1. Click on the "Add new" link at the top, and paste into the text box, then click the "Add" button.