Upgrade to onedir#
Onedir is the Salt Project’s new packaging system. Beginning with the release of Salt 3006 (Sulfur), the Salt Project will only offer onedir packages.
What is onedir?#
Onedir stands for “one directory” because the goal is to provide a single directory containing all the executables that Salt needs. It includes the version of Python needed by Salt and its required dependencies.
Onedir packages simplify the installation process because they allow you to use Salt out of the box without installing Python or other dependencies first.
Onedir packages are self-contained binaries of Salt. Onedir packages include:
|What is installed||For more information|
|The version of Python needed by Salt||Support for Python versions|
|Salt’s required dependencies||Salt dependencies|
The dependencies included with onedir are required for Salt’s core functionality only. If you are using a Salt module that has an additional dependency, you will need to additionally install any dependencies required by that specific module. See the module documentation for that specific module for a list of required dependencies.
Timeline for upgrading to onedir packaging#
In order to avoid disruption of services and continue getting upgraded versions of Salt, begin planning how you will update your Salt infrastructure to onedir. See How to upgrade to onedir for more information.
|Salt version||Packaging changes|
|3006||The Salt Project will only support onedir packages going forward.|
How to upgrade to onedir#
To upgrade to onedir:
On your Salt infrastructure (masters, minions, etc.), update the repository path to point to the new onedir repository paths for your operating system. See Repository paths for more information.
Rather than manually updating the configuration files with the correct repository link, you can re-run the installation commands for your operating system. When you re-run the commands, make sure you select the instructions for the onedir version of the package. See Manual install directions by operating system for the specific commands.
After the repository file is updated, import the 3006.1 GPG key.
GPG key change
The GPG key for the 3006.1 release is now named: SALT-PROJECT-GPG-PUBKEY-2023. You must import the new GPG key before upgrading or your upgrade will fail.
Upgrade your Salt packages.
After upgrading your Salt packages, your Salt services should automatically restart. If you need to restart them manually for any reason, you can use these commands:
systemctl start salt-master systemctl start salt-minion
See Restart and upgrade minions used in state runs for additional considerations.
Use Salt to reinstall any existing third party Python packages. Reinstalling the packages ensures they are installed in the correct onedir path.
How do I know which packages need to be reinstalled?
You can use
salt-call pip.listto view existing modules that may need to be installed.
See also Salt dependencies for a list of the packages that are installed with onedir. Any package that is not on this list needs to be reinstalled.
You can use two possible methods to reinstall packages:
salt-pip install <package name>
- Use the
In order to install software such as Python libraries and Salt extensions, you’ll need to use
salt-pipto install packages into the onedir directory. For more information, see the pip.state module documentation.
After upgrading, you might need to update any state files that use
pip.installedif you need to install Python packages into the system Python environment. In the state file, provide the
bin_envto the pip state module.
lib-foo: pip.installed: - pip_bin: /usr/bin/pip3 lib-bar: pip.installed: - bin_env: /usr/bin/python3
After upgrading, you might also need to update any salt
gitfsformula branches if the formula has changed because of onedir-specific fixes.
After installing Salt using the onedir packages, do not add Salt to any
library search paths, such as
LD_LIBRARY_PATH on Linux. Onedir has
already been built in a way that allows it to find the executables it needs.
Adding Salt to the library search path could cause errors due to incompatible
versions of system packages.