Skip to main content
Version: 1.16

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
{
  "version": 10,
  ...
  "containerEngine": {
    "allowedImages": {
      "enabled": false,
      "patterns": []
    },
    "name": "containerd"
  },
  ...
}

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

Profile Format and Location​

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

On Linux the deployment profiles are stored in JSON format.

The locations for the profiles are:

/etc/rancher-desktop/defaults.json
/etc/rancher-desktop/locked.json
~/.config/rancher-desktop.defaults.json
~/.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.

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

By default use the "moby" container engine and disable Kubernetes​

~/.config/rancher-desktop.defaults.json
{
  "version": 10,
  "containerEngine": {
    "name": "moby"
  },
  "kubernetes": {
    "enabled": false
  }
}

Lock allowed images list to only allow "busybox" and "nginx"​

~/.config/rancher-desktop.locked.json
{
  "version": 10,
  "containerEngine": {
    "allowedImages": {
      "enabled": true,
      "patterns": ["busybox","nginx"]
    }
  }
}

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:

~/.config/rancher-desktop.defaults.json
~/.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:

/etc/rancher-desktop/defaults.json
/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:

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

System deployments are stored in:

/Library/Preferences/io.rancherdesktop.profile.defaults.plist
/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:

HKEY_CURRENT_USER\SOFTWARE\Policies\Rancher Desktop\Defaults
HKEY_CURRENT_USER\SOFTWARE\Policies\Rancher Desktop\Locked

And the system deployments are stored at:

HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Rancher Desktop\Defaults
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:

"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.