Configuration schema versioning and details
Kasm Workspaces stores its configuration in a relational database with a defined schema. Import and export operations move that configuration between deployments. Schema versioning protects the integrity of those operations.
This page explains how schema versioning works, why version compatibility matters, and which values you can safely change. Understanding these concepts helps you avoid failed imports and accidental misconfiguration when you move settings between deployments.
For the procedures themselves, see Importing Configuration and Exporting Configuration Schema.
Alembic version
The default_properties.yaml file, along with schema and configuration exports, includes an alembic_version property. The value is a unique hash. It identifies the schema revision of the database, which in turn defines the format and properties of an import or export file.
This version typically changes with each build of the application.
The system only allows imports and seeding of files whose alembic_version matches its own internal value. As a result, you cannot export a configuration from an older build of Workspaces and import it into a newer build. Imports work only between like versions.
This restriction prevents a mismatched schema from corrupting a deployment. A configuration written for one schema revision may reference tables, columns, or properties that do not exist in another. Matching the alembic_version guarantees that the import file and the target database share the same structure.
All Users group ID
The All Users group has special significance within the application. It must be defined in the schema with the fixed group ID 68d557ac-4cac-42cc-a9f3-1c7c853de0f3.
This identifier is constant across deployments. Group settings that target the All Users group reference this exact value, so it must not be changed.
Default global settings
The default_properties.yaml file that ships with each build of Workspaces contains a list of Global Settings under the settings: key. You can adjust the default values to suit your deployment.
You should not add or remove settings. The system expects these exact settings to be defined. Removing an entry or adding an unexpected one can leave the deployment in an inconsistent state.
Example Global Settings
The example below shows a few global settings. The full configuration contains dozens. You can adjust the values, but you must not remove any entry or alter the other properties.
settings:
- category: logging
description: The logging protocol used, allowed values are internal, https, splunk, and elasticsearch
name: log_protocol
sanitize: false
services_restart: manager,api
title: Log Protocol
value: internal
value_type: string
- category: logging
description: The port to use for logging communication.
name: log_port
sanitize: false
services_restart: manager,api
title: Log Port
value: "443"
value_type: int
Default group settings
The default_properties.yaml file that ships with each build of Workspaces also contains a list of default Group Settings. The system defaults are the entries that have no group_id assigned. You should not add, remove, or adjust these defaults.
You can, however, assign additional group settings to existing groups, such as the All Users group. Assigning a setting to a group changes the default behavior for the users in that group.
Example Group Settings
Do not adjust the default group settings, which are the entries that have no group_id assigned.
#
# emphasize-lines: 3
group_settings:
- description: Allow audio streaming for a Kasm.
group_id: null
group_setting_id: "${uuid:group_setting_id:2}"
name: allow_kasm_audio
value: "False"
value_type: bool
group_settings:
- description: Allow audio streaming for a Kasm.
group_id: 68d557ac-4cac-42cc-a9f3-1c7c853de0f3
group_setting_id: "${uuid:group_setting_id:1001}"
name: allow_kasm_audio
value: "True"
value_type: bool