Categories
Tech

vRA SaltStack Config – Configure git fileserver

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.

Install Dependencies

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.

Install git:

yum install git

Install GitPython:

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 (fileserver_backend and 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 gitfs.conf:

vi /etc/salt/master.d/gitfs.conf

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 sseapi, roots and of course gitfs;
  • gitfs_remote: this lets you specify Specify one or more git://, https://,  file:// or 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 pygit2 or 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_provider.

When configuring gitfs_remote you just provide a repo URL (with your State Files) using one of the supported protocols with the following syntax:

  • HTTP: https://github.com/username/repositoryname.git
  • GIT: git@github.com:username/repo.git
  • SSH: ssh://username@domain.tld/path/to/repo.git

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 .

Check

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:

salt-run fileserver.dir_list

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 base environment:

salt-run fileserver.envs

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.