Use Ansible's YAML callback plugin for a better CLI experience

Ansible is a great tool for automating IT workflows, and I use it to manage hundreds of servers and cloud services on a daily basis. One of my small annoyances with Ansible, though, is its default CLI output—whenever there's a command that fails, or a command or task that succeeds and dumps a bunch of output to the CLI, the default visible output is not very human-friendly.

For example, in a Django installation example from chapter 3 of my book Ansible for DevOps, there's an ad-hoc command to install Django on a number of CentOS app servers using Ansible's yum module. Here's how it looks in the terminal when you run that task the first time, using Ansible's default display options, and there's a failure:

Ansible 2.5 default callback plugin

...it's not quickly digestible—and this is one of the shorter error messages I've seen!

Ansible introduced callback plugins a while ago, but I just noticed there's a new YAML callback plugin introduced with Ansible 2.5—meaning any machine running Ansible 2.5.0 or later can automatically start using this wonderfully-optimized-for-humans format, without you needing to install a custom plugin on the machine, or include it with all your projects!

To use it, edit your ansible.cfg file (either global, in /etc/ansible/ansible.cfg, or a local one in your playbook/project), and add the following lines under the [defaults] section:

# Use the YAML callback plugin.
stdout_callback = yaml
# Use the stdout_callback when running ad-hoc commands.
bin_ansible_callbacks = True

Now, let's try the same Ansible command from earlier, this time using the YAML callback plugin:

Ansible 2.5 YAML callback plugin

Ah, much better! Now I can easily read through the error message, just as if it was streamed from the server into my terminal. And if you need to parse the data, it's valid YAML, so it's just as easy as the JSON you'd get previously. If you're looking for a usable CLI experience, there are a few other good built-in callback plugins you might want to try, too, like unixy, dense, or debug.

If you want to go even deeper, and maybe even write your own callback plugins, check out this presentation from AnsibleFest San Francisco 2017: The Power of Callback Plugins.

Further reading

ansible
callback
plugin
ux
cli
terminal
tutorial
how-to

Comments

Note that one casualty (currently) of switching from the default to yaml callback is any stdout printed as a result of command or shell module commands. I opened an issue in the Ansible issue queue requesting this functionality be added in (so I don't have to switch between two different plugins or write my own forked version to have this one simple feature back): YAML stdout callback plugin doesn't output stdout from command module.

That's awesome. Long awaited feature finally available in Ansible.

This is absolutely awesome!! Been waiting for this!! Thanks!

I am getting an Error! Invalid callback for stdout specified: yaml

Any clue what needs to be enabled for this to work?

Ah…really nice. Thanks for your post Jeff!
/thorsten

Also ANSIBLE_STDOUT_CALLBACK=debug is nice if you have -v

If I want to see the current facts, using "ansible all -m setup", I have to disable the callback plugin to get any output.

Thanks, Jeff for the posting. Seems these plugins should be default, which would rescue many Ansible novices like me.

I have been looking for something like for a couple days now. Thank you for showing how to do this so easily.

This was SO incredibly clear, easy and HELPFUL. Thank you for Sharing

Seems like yaml callback become broken, at least in
$ ansible --version
ansible 2.9.11
For any debug msg commands I'm getting:
```
[WARNING]: Failure using method (v2_runner_on_ok) in callback plugin (): value must be a string
```
Tried to google, but nothing on Github regarding that callback, is anyone knows better replacement?

ME TOO.

I'm not quite sure it is 2.9.11
I was running 2.8.5 until an hour ago, when i removed a whole bunch of spacewalk packages from my server, and then registered my ansible server with Suse Manager 4, which defaults to salt-minion clients instead of spacewalk-style clients.
And then suddenly i get this error.

So, i THEN updated ansible to ansible-2.9.10-1.el7, but it did not fix the issue.

This is really helpful! Thank you, Jeff Geerling.

You may come across the following error:
ERROR! Invalid callback for stdout specified: yaml
in which case you need to run the following command:
ansible-galaxy collection install community.general

Too bad it doesn't print colored command output.

Great article, thanks! If some annoying typos ("is it's" should be "is its") could be avoided, the lecture would be even better.