Deployment Profiles

Deployment profiles provide 2 features:

  • “Defaults” provide preference values that are applied on first run (or after a factory reset).
  • “Locked” settings allow an administrator to pin preference values.

They can be specified both by an “admin” or by the “user”. If either the “defaults” or the “locked” settings exists in the “admin” context, then the “user” profile is ignored.

Preferences Values at Startup

Rancher Desktop settings are determined as follows:

  • Load “admin” deployment profile (both “defaults” and “locked”)
  • If neither of them exist then load “user” deployment profile (again both “defaults” and “locked”)
  • Load saved preferences from settings.json file
  • If there are no saved settings, use the “defaults” profile loaded earlier instead
  • Copy values from command-line arguments used to launch the app into settings
  • If the settings are still completely empty, show the first-run dialog
  • Fill any missing values from the builtin application defaults
  • Copy values from the “locked” profile over the current settings

The user cannot modify any settings (via GUI or CLI) that have been locked by the profile.

Rancher Desktop will refuse to load the application if a profile exists, but cannot be parsed correctly.

Deployment profiles will not be modified or removed by Rancher Desktop. They will not be affected by a factory reset or uninstall.

The structure of the profile data matches the application settings:

rdctl list-settings

  1. {
  2.   ...
  3.   "containerEngine": {
  4.     "allowedImages": {
  5.       "enabled": false,
  6.       "patterns": []
  7.     },
  8.     "name": "containerd"
  9.   },
  10.   ...
  11. }

The platform-specific documentation below will show how to create a deployment profile that changes the default container engine to moby, disables Kubernetes, and locks down the list of allowed images to just busybox and nginx.

Locked Preference Fields

For versions 1.9 and later of Rancher Desktop, all preferences values can be locked when configuring a deployment profile. Depending on the directory or registry used for the lock file creation, users may need to have super user permissions for MacOS/Linux or execute from an admin shell for Windows in order to access priviliged paths. Once pinned, the various locked values will not be accessible from the application as seen in the UI examples below:

Locked Fields UI Examples

  • Windows
  • macOS
  • Linux

Deployment Profiles - 图1

Deployment Profiles - 图2

Deployment Profiles - 图3

Deployment Profiles - 图4

Deployment Profiles - 图5

Deployment Profiles - 图6

Profile Format and Location

Deployment profiles are stored in a platform-specific format and location.

  • Windows
  • macOS
  • Linux

On Windows the deployment profiles are stored in the registry and can be distributed via group policy.

The locations for the profiles are:

  1. HKEY_LOCAL_MACHINE\Software\Policies\Rancher Desktop\Defaults
  2. HKEY_LOCAL_MACHINE\Software\Policies\Rancher Desktop\Locked
  3. HKEY_CURRENT_USER\Software\Policies\Rancher Desktop\Defaults
  4. HKEY_CURRENT_USER\Software\Policies\Rancher Desktop\Locked

The reg tool can be used to create a profile manually. To create an “admin” profile it will have to be executed from an elevated shell.

Boolean values are stored in REG_DWORD format, and lists in REG_MULTI_SZ.

Delete existing profiles

  1. reg delete "HKCU\Software\Policies\Rancher Desktop" /f

By default use the “moby” container engine and disable Kubernetes

  1. reg add "HKCU\Software\Policies\Rancher Desktop\Defaults\containerEngine" /v name /t REG_SZ -d moby
  2. reg add "HKCU\Software\Policies\Rancher Desktop\Defaults\kubernetes" /v enabled /t REG_DWORD -d 0

Lock allowed images list to only allow “busybox” and “nginx”

  1. reg add "HKCU\Software\Policies\Rancher Desktop\Locked\containerEngine\allowedImages" /v enabled /t REG_DWORD -d 1
  2. reg add "HKCU\Software\Policies\Rancher Desktop\Locked\containerEngine\allowedImages" /v patterns /t REG_MULTI_SZ -d busybox\0nginx

Verify registry settings

The profile can be exported into a *.reg file

  1. C:\>reg export "HKCU\Software\Policies\Rancher Desktop" rd.reg
  2. The operation completed successfully.

This file can be used to distribute the profile to other machines. Note that the REG_MULTI_SZ values are encoded in UTF16LE, so are not easily readable:

HKCU\Software\Policies\Rancher Desktop

  1. Windows Registry Editor Version 5.00
  3. [HKEY_CURRENT_USER\Software\Policies\Rancher Desktop]
  5. [HKEY_CURRENT_USER\Software\Policies\Rancher Desktop\Defaults]
  7. [HKEY_CURRENT_USER\Software\Policies\Rancher Desktop\Defaults\containerEngine]
  8. "name"="moby"
  10. [HKEY_CURRENT_USER\Software\Policies\Rancher Desktop\Defaults\kubernetes]
  11. "enabled"=dword:00000000
  13. [HKEY_CURRENT_USER\Software\Policies\Rancher Desktop\Locked]
  15. [HKEY_CURRENT_USER\Software\Policies\Rancher Desktop\Locked\containerEngine]
  17. [HKEY_CURRENT_USER\Software\Policies\Rancher Desktop\Locked\containerEngine\allowedImages]
  18. "enabled"=dword:00000001
  19. "patterns"=hex(7):62,00,75,00,73,00,79,00,62,00,6f,00,78,00,00,00,6e,00,67,00,\
  20.   69,00,6e,00,78,00,00,00,00,00

On macOS the deployment profiles are stored as plist files.

The locations for the profiles are:

  1. /Library/Preferences/io.rancherdesktop.profile.defaults.plist
  2. /Library/Preferences/io.rancherdesktop.profile.locked.plist
  3. ~/Library/Preferences/io.rancherdesktop.profile.defaults.plist
  4. ~/Library/Preferences/io.rancherdesktop.profile.locked.plist

Convert all current settings into a deployment profile

A simple way to turn existing settings into a deployment profile is by converting them from JSON into the plist XML format, and then manually trimming it down in an editor.

  1. rdctl list-settings | plutil -convert xml1 - -o ~/Library/Preferences/io.rancherdesktop.profile.defaults.plist

Alternatively the profile can be created manually, either with an editor, or with the plutil tool. The defaults utility doesn’t work because it cannot create nested keys.

By default use the “moby” container engine and disable Kubernetes

  1. DEFAULTS=~/Library/Preferences/io.rancherdesktop.profile.defaults.plist
  2. plutil -create xml1 "$DEFAULTS"
  4. plutil -insert containerEngine -dictionary "$DEFAULTS"
  5. plutil -insert containerEngine.name -string moby "$DEFAULTS"
  7. plutil -insert kubernetes -dictionary "$DEFAULTS"
  8. plutil -insert kubernetes.enabled -bool false "$DEFAULTS"

Lock allowed images list to only allow “busybox” and “nginx”

  1. LOCKED=~/Library/Preferences/io.rancherdesktop.profile.locked.plist
  2. plutil -create xml1 "$LOCKED"
  4. plutil -insert containerEngine -dictionary "$LOCKED"
  5. plutil -insert containerEngine.allowedImages -dictionary "$LOCKED"
  6. plutil -insert containerEngine.allowedImages.enabled -bool true "$LOCKED"
  8. plutil -insert containerEngine.allowedImages.patterns -array "$LOCKED"
  9. plutil -insert containerEngine.allowedImages.patterns -string busybox -append "$LOCKED"
  10. plutil -insert containerEngine.allowedImages.patterns -string nginx -append "$LOCKED"

Verify the plist files

~/Library/Preferences/io.rancherdesktop.profile.defaults.plist

  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
  3. <plist version="1.0">
  4. <dict>
  5.     <key>containerEngine</key>
  6.     <dict>
  7.         <key>name</key>
  8.         <string>moby</string>
  9.     </dict>
  10.     <key>kubernetes</key>
  11.     <dict>
  12.         <key>enabled</key>
  13.         <false/>
  14.     </dict>
  15. </dict>
  16. </plist>

~/Library/Preferences/io.rancherdesktop.profile.locked.plist

  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
  3. <plist version="1.0">
  4. <dict>
  5.     <key>containerEngine</key>
  6.     <dict>
  7.         <key>allowedImages</key>
  8.         <dict>
  9.             <key>enabled</key>
  10.             <true/>
  11.             <key>patterns</key>
  12.             <array>
  13.                 <string>busybox</string>
  14.                 <string>nginx</string>
  15.             </array>
  16.         </dict>
  17.     </dict>
  18. </dict>
  19. </plist>

On Linux the deployment profiles are stored in JSON format.

The locations for the profiles are:

  1. /etc/rancher-desktop/defaults.json
  2. /etc/rancher-desktop/locked.json
  3. ~/.config/rancher-desktop.defaults.json
  4. ~/.config/rancher-desktop.locked.json

Convert all current settings into a deployment profile

Since deployment profiles are stored in JSON format, the simplest way to create them is by saving the current application settings to the profile location, and then fine-tuning the profile with a text editor.

  1. rdctl list-settings > ~/.config/rancher-desktop.defaults.json

By default use the “moby” container engine and disable Kubernetes

~/.config/rancher-desktop.defaults.json

  1. {
  2.   "containerEngine": {
  3.     "name": "moby"
  4.   },
  5.   "kubernetes": {
  6.     "enabled": false
  7.   }
  8. }

Lock allowed images list to only allow “busybox” and “nginx”

~/.config/rancher-desktop.locked.json

  1. {
  2.   "containerEngine": {
  3.     "allowedImages": {
  4.       "enabled": true,
  5.       "patterns": ["busybox","nginx"]
  6.     }
  7.   }
  8. }

Known Issues and Limitations

  • On macOS incorrectly formatted profiles are ignored instead of preventing the app from loading.
  • There is no way to set diagnostics.showMuted (and on Windows WSL.integrations) via deployment profile.
  • On macOS and Linux an abbreviated first-run dialog is still shown if the “defaults” profile does not provide a value for application.pathManagementStrategy.