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.   "version": 10,
  3.   ...
  4.   "containerEngine": {
  5.     "allowedImages": {
  6.       "enabled": false,
  7.       "patterns": []
  8.     },
  9.     "name": "containerd"
  10.   },
  11.   ...
  12. }

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 privileged 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" /v version /t REG_DWORD -d 10
  2. reg add "HKCU\Software\Policies\Rancher Desktop\Defaults\containerEngine" /v name /t REG_SZ -d moby
  3. 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" /v version /t REG_DWORD -d 10
  2. reg add "HKCU\Software\Policies\Rancher Desktop\Locked\containerEngine\allowedImages" /v enabled /t REG_DWORD -d 1
  3. 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]
  6. "version"=dword:a
  8. [HKEY_CURRENT_USER\Software\Policies\Rancher Desktop\Defaults\containerEngine]
  9. "name"="moby"
  11. [HKEY_CURRENT_USER\Software\Policies\Rancher Desktop\Defaults\kubernetes]
  12. "enabled"=dword:00000000
  14. [HKEY_CURRENT_USER\Software\Policies\Rancher Desktop\Locked]
  15. "version"=dword:a
  17. [HKEY_CURRENT_USER\Software\Policies\Rancher Desktop\Locked\containerEngine]
  19. [HKEY_CURRENT_USER\Software\Policies\Rancher Desktop\Locked\containerEngine\allowedImages]
  20. "enabled"=dword:00000001
  21. "patterns"=hex(7):62,00,75,00,73,00,79,00,62,00,6f,00,78,00,00,00,6e,00,67,00,\
  22.   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 version -integer 10 "$DEFAULTS"
  6. plutil -insert containerEngine -dictionary "$DEFAULTS"
  7. plutil -insert containerEngine.name -string moby "$DEFAULTS"
  9. plutil -insert kubernetes -dictionary "$DEFAULTS"
  10. 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 version -integer 10 "$LOCKED"
  6. plutil -insert containerEngine -dictionary "$LOCKED"
  7. plutil -insert containerEngine.allowedImages -dictionary "$LOCKED"
  8. plutil -insert containerEngine.allowedImages.enabled -bool true "$LOCKED"
  10. plutil -insert containerEngine.allowedImages.patterns -array "$LOCKED"
  11. plutil -insert containerEngine.allowedImages.patterns -string busybox -append "$LOCKED"
  12. 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.     <key>version</key>
  16.     <integer>10</integer>
  17. </dict>
  18. </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.     <key>version</key>
  19.     <integer>10</integer>
  20. </dict>
  21. </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.   "version": 10,
  3.   "containerEngine": {
  4.     "name": "moby"
  5.   },
  6.   "kubernetes": {
  7.     "enabled": false
  8.   }
  9. }

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

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

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

version Field

Rancher Desktop version 1.12 introduces an explicit deployment profile version field in generated profiles using rdctl.

If you are using deployment profiles created in previous Rancher Desktop versions, please either regenerate the file with the latest installation, or explicitly add the version field to your existing file. See below for updating instructions for various operating systems:

Linux

User deployments are stored in:

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

If the XDG_CONFIG_HOME environment variable is set, the user deployments are stored there instead of in ~/.config/.....

System deployments are stored in:

  1. /etc/rancher-desktop/defaults.json
  2. /etc/rancher-desktop/locked.json

Then add "version": 10 at the very start of your JSON-formatted file immediately after the initial open brace (}).

macOS

User deployments are stored in:

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

System deployments are stored in:

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

Then add <key>version</key><integer>10</integer> after the initial <dict> tag into your respective .plist file.

Windows

The Windows deployments are stored in the registry. User deployments are stored at:

  1. HKEY_CURRENT_USER\SOFTWARE\Policies\Rancher Desktop\Defaults
  2. HKEY_CURRENT_USER\SOFTWARE\Policies\Rancher Desktop\Locked

And the system deployments are stored at:

  1. HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Rancher Desktop\Defaults
  2. HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Rancher Desktop\Locked

Then add a DWORD value named version, with value 10 (hexadecimal a) at the top level of each profile that needs updating:

  1. "version"=dword:a

Known Issues and Limitations

  • You can set default values for diagnostics.showMuted (and on Windows WSL.integrations) via deployment profile, but currently can’t lock them.