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
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.
override.yamlfile at below path
- Write a provisioning script in the
override.yamlfile created in the previous step. For example, you can use the below script to increase ulimit for containers.
- mode: system
cat <<'EOF' > /etc/security/limits.d/rancher-desktop.conf
* soft nofile 82920
* hard nofile 82920
- You can also use
override.yamlto override/modify a lima configuration setting, for example, to create additional mounts as shown below.
- location: /some/path
- Another example uses the
override.yamlfile to allow users to implement custom settings for
K3senvironments using Rancher Desktop's
K3S_EXECsyntax (Similar to the
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 valueflag to add additional hostnames as Subject Alternative Names on the TLS certification:
K3S_EXEC: --tls-san value
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
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.
%AppData%\rancher-desktop\provisioningdirectory. An example of the full path:
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
- Rancher Desktop internal setup
- Run provisioning scripts
containerdin the UI
- Kubernetes (K3s)
As an example, using
%AppData%\rancher-desktop\provisioning\insecure-registry.start will allow
nerdctl to use insecure registries by default:
mkdir -p /etc/nerdctl
cat > /etc/nerdctl/nerdctl.toml <<EOF
insecure_registry = true
- 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
- 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.