Salt relies on files (e.g. State files, Reactor config files, Pillars, etc.), for this reason it comes with a simple file server suitable for distributing files to the Salt Minions. The file server is a stateless ZeroMQ server that comes with the Salt Master. The main goal of the Salt file server is to present files for use in the Salt state system.
Salt Master supports different file server backends. File server backends allow the Salt file server to act as a transparent bridge to external resources. A good example of this is the
git backend, which allows Salt to serve files sourced from one or more git repositories, but there are several others as well. Here you can access the full list of Salt’s file server backends.
In this post we will configure Salt Master to integrate with git backend, specifically I tested this procedure with GitHub, but it is applicable to any git. Before jumping into the process it is good to mention that the git file server backend is named
gitfs and it can be enabled by adding
gitfs to the
fileserver_backend list and configuring one or more repositories in the
gitfs_remotes parameter in a Salt Master configuration file. Branches and tags become Salt fileserver environments. A more experienced Salt user suggested me to start with a simple repository without branches and use different repos for prod and dev Salt instances. I am transferring this piece of wisdom to you even though I not really following it in my lab.
Here we assume you have a working instance of Salt Master and thus you have Python and Pip on your system, so just make sure they are updated. The procedure in this post is tested for vRA SaltStack Config 8.4 (installed via vRLCM) running on PhotonOS 3.0.
Both pygit2 and GitPython are supported Python interfaces to git. If compatible versions of both are installed, pygit2 is preferred. In this scenario, GitPython can be forced using the
gitfs_provider parameter in the master config file (we cover this later in the “Configure the git backend” section). A longtime Salt user suggested me to use GitPython and I am following his advice here.
GitPython requires the
git CLI utility to work. If GitPython is installed from a system package, then git should already be installed, but if installed via Pip then it may still be necessary to install git separately.
yum install git
pip3 install gitpython
If you have any issue related to GitPython you can refer to this walkthrough.
Configure the git backend
The very minimum configuration to start using git backend requires two parameters (
gitfs_remotes) to be set in a master configuration file. Rather than adding these parameters in the
/etc/salt/master.d/raas.conf file that comes with the vRLCM installation, it is a good idea to create a new configuration file dedicated to the
gitfs backend, we just need to make sure the new file name comes before “raas.conf” in the alphabetical order. This ensures that git backend configurations are picked from our new configuration file and any other git backend configuration specified in other file(s) (having a name that comes after in the alphabetical order ) is ignored.
Create a new configuration file, in my case I named it
Add the following configurations:
fileserver_backend: - sseapi - roots - gitfs gitfs_provider: gitpython gitfs_interval: 60 gitfs_base: main gitfs_root: / gitfs_mountpoint: / gitfs_remotes: - <your git repo URL>
Here is the documentation for all the supported
gitfs parameters, in this post I’ll just focus on the two mandatory parameters and the gitfs_provider:
fileserver_backend: this let you list all the supported backend in your Salt Master, in my case I am using
rootsand of course
gitfs_remote: this lets you specify Specify one or more
ssh://URLs to configure which repositories to cache and search for requested files. The user running the Salt Master will need read access to the repo. The repos will be searched in order to find the file requested by a client and the first repo to have the file will return it;
- gitfs_provider: this is an optional parameter used to specify the provider to be used for gitfs. It must be either
gitpython. If unset, then each will be tried in that same order, and the first one with a compatible version installed will be the provider that is used. I strongly recommend to configure
gitfs_remote you just provide a repo URL (with your State Files) using one of the supported protocols with the following syntax:
Restart the Salt Master:
systemctl restart salt-master
Keep in mind that if your repository is not public, then there are some other authentication pieces that need to be in place as well. Here you can access configuration parameters documentation for the various supported authentication options, while here you can access the authentication section of an excellent
gitfs walkthrough .
On your Salt Master you can list directories available in all your backend servers and make sure the folders of your git repository (assuming you have folders in you repo) are there:
List environments in all your backend servers and make sure envs match with you repository branches (there might be more envs defined in other backends). Please, note that by default the
main/master branch of a repository is mapped on the Salt
base env. You can use the
gitfs_base parameter in the master configuration file to defines which branch/tag should be used as the
List files, in my case I am listing files in the
dev environment that is the
dev branch of my repository:
salt-run fileserver.file_list saltenv=dev
Finally apply a State File, in my case I am using the
test=True option just to make sure I do not screw up things:
salt saltmaster state.apply reactor/master/master test=True
That’s it! Now you can work with Salt using git. Since you are here, I also suggest to use VS code to edit your Salt Files, there is a nice SaltStack extension that adds language colorization support for the SaltStack template language and supports yaml with Jinja2 templating.