Provisioning Scripts

Provisioning scripts can be used to override some of Rancher Desktop’s internal processes. For example, scripts can be used to provide certain command line parameters to K3s, add additional mounts, increase ulimit value etc. This guide will explain how to set up your provisioning scripts for macOS, Linux, and Windows.

macOS & Linux

On macOS and Linux, you can use lima override.yaml to write provisioning scripts.

  • Run Rancher Desktop at least once to allow it to create the _config directory.

Provisioning Scripts - 图1note

Please note that the directory will be deleted during a factory-reset, so ensure a backup for your provisioning scripts in case you need them after a factory-reset.

  • Create override.yaml file at below path

  • macOS

  • Linux
  1. ~/Library/Application Support/rancher-desktop/lima/_config/override.yaml
  1. ~/.local/share/rancher-desktop/lima/_config/override.yaml
  • Write a provisioning script in the override.yaml file created in the previous step. For example, you can use the below script to increase ulimit for containers.
  1. provision:
  2. - mode: system
  3.   script: |
  4.     #!/bin/sh
  5.     cat <<'EOF' > /etc/security/limits.d/rancher-desktop.conf
  6.     * soft     nofile         82920
  7.     * hard     nofile         82920
  8.     EOF
  • You can also use override.yaml to override/modify a lima configuration setting, for example, to create additional mounts as shown below.
  1. mounts:
  2.   - location: /some/path 
  3.     writable: true
  • Another example uses the override.yaml file to allow users to implement custom settings for K3s environments using Rancher Desktop’s K3S_EXEC syntax (Similar to the K3s syntax INSTALL_K3S_EXEC). Please see the agent and server command line flags documentation for further installation options. Below is an example setting using the --tls-san value flag to add additional hostnames as Subject Alternative Names on the TLS certification:
  1. env:
  2.   K3S_EXEC: --tls-san value

Windows

Caution: You can only utilize these provisioning scripts for Rancher Desktop, version 1.1.0 or later, on Windows.

  • Run Rancher Desktop at least once to allow it to create the configuration provisioning directory.

Provisioning Scripts - 图2note

Please note that the directory will be deleted during a factory-reset, so ensure a backup for your provisioning scripts in case you need them after factory-reset.

  • Open the %AppData%\rancher-desktop\provisioning directory. An example of the full path: C:\Users\Joe\AppData\Roaming\rancher-desktop\provisioning.

  • Note that any files with a file extension of .start, such as k3s-overrides.start, can be executed when Rancher Desktop starts its Kubernetes backend (if enabled). Such files will run within the Rancher Desktop WSL context.

Example flow for .start files:

  • Rancher Desktop internal setup
  • Run provisioning scripts
  • Enable dockerd or containerd in the UI
  • Kubernetes (K3s)

As an example, using %AppData%\rancher-desktop\provisioning\insecure-registry.start will allow nerdctl to use insecure registries by default:

  1. #!/bin/sh
  3. mkdir -p /etc/nerdctl
  4. cat >  /etc/nerdctl/nerdctl.toml <<EOF
  5. insecure_registry = true
  6. EOF
  • Note that files with a file extension of .stop, such as wipe-data.stop, can be executed after Rancher Desktop shuts down its Kubernetes backend (if enabled). Such files will run within the same Rancher Desktop WSL context.

Example flow for .stop files:

  • Stop k3s, dockerd or containerd
  • Run deprovisioning scripts

Important to note: Scripts need to be saved with Unix line endings; line-ending conversion is not done; and files with DOS line endings may produce unexpected results. There are some limitations to the things you can change using provisioning scripts. For example, you cannot change the hard ulimits on WSL2 using provisioning scripts. Please use provisioning scripts with caution and feel free to reach out to the Rancher Desktop team on Slack/Github if you have a specific question about provisioning scripts.