ReturnCodes in Salt

Returners

Each command in Salt has a return value. The return values are always sent to the Master. However, we can specify what we want to do with the return data using Returners. We can send it to a custom database - such as MySQL, MongoDB, etc. We can also tell Salt to store the return values locally on the minion machine in a log file. 

Before we start using and writing returners, let us see what return values for commands look like. 

On your minion machine, execute the following command:

sudo salt-call --local --metadata test.version --out=pprint

The inner dictionary (the one with the keys fun,fun_args,etc.) is our return value.

Now, let's see how to use returners.

Using Returners

Salt provides many built-in Returners. They allow us to store return values in popular databases such as MongoDB, Redis, MySQL, etc. For simplicity, we won't be using an external database. We will use the rawfile_json returner that is built-in with Salt. It stores the return values in a local file on the minion machine. 

The location for this file is /var/log/salt/events

To use, we need to add the following line whenever we execute a salt command.

--return rawfile_json

Let's try with a ping command. The final command will be this.

sudo salt '*' test.ping --return rawfile_json

Let's go to the Minion machine and check if our log file has been created. 

To go to the correct directory, type the command:

cd /var/log/salt

Once there, check if the file exists. 

We see that the file exists and has the return data about our function.

Writing our own Returner

Sometimes, we may like to take customized actions with our return data. For this, we will need to write our own returner. 

Writing returners is very simple. We need to create a python file containing the returner function, taking a single argument. Salt will pass the argument to that function itself. The argument will contain the return value we saw above. 

That is it! In that function, we can implement whatever we want. It is up to us to do what we want with the return value. Let's take a basic example - once again, we will simply write the data to a file.

In your Master machine, go to the file_roots directory of the base environment. For us, this is /srv/salt/base. 

Create a new folder _returners. This name is fixed and can't be changed. Navigate to inside this folder. Create a file test_returner.py. Write this code in it:

import os
import shut ill
def returner (ret):
logFilePath ="/home/ubuntu/log.txt "
file = open(logFilePath, 'a')
file.write (str(ret))
file.close()

This code will open the file at /home/ubuntu/log.txt in append mode. In append mode, data is written to the end of the file. If this file doesn't exist, Python will create it for us. After that, the return value will be written to the file directly as a String.

Let's save the file. Now, we need to ensure this returner file is synced to the minion. To do that, run the following command.

sudo salt '*' saltutil.sync_returners

We receive a successful response. Let's run a command and see if a log file is generated. Run the following command.

sudo salt '*' test.ping --return test_returner

Let's go to the minion machine and check. 

We see that a log file is generated with the correct data.

Frequently Asked Questions

What code can I write in returners?

Anything that you can imagine can be written in returners. It is up to us. Salt will pass us the return value, and we can use it however we wish.

If I use returners, are the return values sent to Master still?

Master always receives return values. Using returners makes returners also get those values. It does not stop the master from receiving them.

Can I use multiple returners on a single command?

Yes, you can. You can write multiple returner names separated by commas. For e.g. - salt '*' test.ping --return returner1,returner2 

Conclusion

In this blog, we have seen how Salt uses the concept of Return Codes. We have seen the meaning of return codes in Salt. Returners help us to consolidate information about the various tasks we do use Salt on a single database. We can then use this for data analysis and changing policies.

We hope you leave this article with a broader knowledge of Salt,return codes, and configuration management. You should read our other articles about these topics as well, such as

• Salt System Architecture.
   
• Salt File Server
   
• Salt Install Guide
   

You can practice questions on various problems on Coding Ninjas Studio, and attempt mock tests. You can also go through interview experiences, interview bundle, go along guided paths for preparations, and a lot more!

Keep coding, and keep reading Ninjas.