Skip to main content
Version: 1.9

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

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
{
  "containerEngine": {
    "name": "moby"
  },
  "kubernetes": {
    "enabled": false
  }
}

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

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

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.