Getting Started#
Prerequisites#
Python 3.7+
git (if installing from source, or contributing to the project)
Installation#
Note
If wanting to contribute to the project, and setup your local development
environment, see the CONTRIBUTING.rst
document in the source repository
for this project.
If wanting to use heist-salt
, you can do so by either
installing from PyPI or from source.
Install from PyPI#
To install the latest version from PyPI:
# Requires Python 3.7+
pip install heist-salt
Install from PyPi when using Salt’s onedir packages#
salt-pip install heist-salt
Note
Due to this issue: https://github.com/saltstack/salt/issues/64192 you cannot run Heist-Salt alongside Salt’s 3006.0 onedir packages. This was resolved in Salt’s 3006.1 onedir packages.
After heist-salt is installed into the Salt’s onedir packages, you
need to ensure you add the Heist binary to your path. If you installed
the linux 3006.1 Salt onedir packages, by default this path would be
/opt/saltstack/salt/extras-3.10/bin/
. This is where the heist binary
is installed when running salt-pip install heist-salt
. You could
also directly call the full binary path instead of adding it to your path.
For example:
# /opt/saltstack/salt/extras-3.10/bin/heist salt.minion -R /etc/heist/roster
Install from source#
heist-salt
can also be installed from source:
# Requires git and Python 3.6+
git clone https://gitlab.com/saltstack/pop/heist-salt.git
cd heist-salt
pip install -e .
Setting up a Salt master#
Don’t worry, this is a snap! Once Heist is installed you will need a
Salt master to connect to if you are using the salt.minion
manager.
If you have an existing Salt master running or you are using a different
manager such as salt.master
you can skip this section,
just run heist
on your Salt master.
Using onedir binary#
Download the all-in-one Salt binary for Linux x86_64.
wget https://repo.saltproject.io/salt/py3/onedir/latest/salt-3006.1-onedir-linux-x86_64.tar.xz
This is to install the 3006.1 version of Salt. You can view the directory listing here: https://repo.saltproject.io/salt/py3/onedir/ to see all of the Salt versions available for download.
Extract the tarball:
tar -xvf salt-3006.1-onedir-linux-x86_64.tar.xz
This will extract a single file named salt. You can now use this single binary to run the Salt master.
./salt/salt-master
Now you have a running Salt master to control your minions!
Using onedir system packages#
You can also install the onedir system packages. Please see the Salt install guide for instructions on how to install and run the Salt master.
Pip install Salt#
If you want to pip install Salt you only need to run:
pip install salt
Now you can run the salt-master in the background:
salt-master -d
Making your roster#
A Roster is a file used by Heist to map login information to the
systems in your environment. This file can be very simple and just
needs to tell Heist where your systems are and how to log into them
via ssh. Open a file called roster.cfg
and add the data needed to connect
to a remote system via ssh:
192.168.4.4:
username: fred
password: freds_password
The roster files typically all live inside of a roster directory. But to get
started will execute a single roster file with heist
:
heist <heist-manager> -R roster.cfg
Please see heist’s roster documentation for more information on rosters.
To use the salt.minion
manager to deploy and manage a Salt Minion artifact,
run the following:
heist salt.minion -R roster.cfg
To use the salt.master
manager to deploy and manage a Salt Master artifact,
run the following:
heist salt.master -R roster.cfg
Assuming your roster is correct, heist will now connect to the remote system, deploy a Salt minion, and connect it to your running master! Now you can use the same binary that you started the master with to accept your new minion’s keys:
./salt/salt-key -A
Then give your minion a few seconds to authenticate and then run your first
salt
command on the newly set up minion:
./salt/salt \* test.version
That’s it! Now that the minion is up you can run salt
commands on it at breakneck
speed, the full power of Salt is at your fingertips!!