Visibility and documentation of ansible playbook.

Archives Ansible Project
1

Dear ansible users,

I am using ansible and must admit that I am quite happy with it. Challanges which I started to have are:

  1. Documentation from yaml files (roles / playbook / etc).
  2. Visibility what ansible will do.

A bit more about this:

1.

I started using sphinx-doc for documentation for some projects and must admit that is working very well and as expected. I know that ansible is written in python which support docstrings in code and sphinx-doc can read python modules and generate documentation (this is how ansible-doc is generated). However so far I didn’t find any way of generate documentation from yaml file. My google skills didn’t help me a lot in this area.

As I ansible user I would like to use docstrings in yaml file and quickly build documentation (the best for sphinx-doc if possible). Something like doxygen is doing for C++ code.

Do you know any already existed solutions or do I have to write my own parser / generator?
How do you documenting your playbook to quickly see what is happening?

I know that ansible has been designed to be easy to read and understand - and ansible developers meet this goal. However when code is growing up and more and more roles exists, is (for me) harder and harder remember how role has been designed and why this way :slight_smile:

#2.
Visibility - I am not speaking about --check --diff options. They do what must be done - and works well. More I am speaking about following scenario: T = Time (day / week / etc).
T1 = Some initial ansible code has been created and deployed on new VM (Works :))
T2 = Changes in ansible code to allow run some specific tasks at hock.
T3 = Adjust ansible to run some tasks on already configured hosts
T4 = New machine is setup - how to know what ansible will do exectly ???

I know that ansible has option --list tasks, --list-hosts, etc - but during development code changes quickly and ‘–list-tasks’ can show me clearly which tasks will run, but doesn’t show logic of operation (Which variables must be setup for playbook, how it will work, what is really installing) - for example for tasks with lists - no clear info what will be installed, etc.

IMHO, this is related with #1 (documentation).

How do you sort this challange - how do you know what ansible will do and whether nothing will be broken on already existing environments?
Real example:

  • I had to setup mysql server on 10 hosts (lucky for me not in production yet). (CentOS)
  • During development of ansible palybook we added uninstalling some old version of package (in thory not related with mysql)
  • Ansible work as expected - all taks has been done, but wait - from some reason uninstalling package - uninstalled mysql-server because of depenecies (yeap yum issue :()
  • Lucky for me I didn’t lost data - only binaries. So next quick task in ansible and install mysql-server sorted this quickly.

But this is what I am talking in terms of risk and visibility - what ansible will do.

Appologise for long email, hope that you have some experience, hints how to deal with these challanges.

Best regards,
Marcin Praczko

2

As I ansible user I would like to use docstrings in yaml file and quickly
build documentation (the best for sphinx-doc if possible). Something like
doxygen is doing for C++ code.

YAML documents support comments.

You could easily write a script to parse these out if you wanted, though
I'd prefer reading these inline with the task source 99.9999% of the time
(me personally).

The "name" field in Ansible is in fact a comment of sorts to encourage a
fair amount of readable output.

#2.
Visibility - I am not speaking about --check --diff options. They do what
must be done - and works well. More I am speaking about following scenario:
T = Time (day / week / etc).
T1 = Some initial ansible code has been created and deployed on new VM
(Works :))
T2 = Changes in ansible code to allow run some specific tasks at hock.
T3 = Adjust ansible to run some tasks on already configured hosts
T4 = New machine is setup - how to know what ansible will do exectly ???

Check mode lets you know if it would make a resource conform to a given
state.

You have to trust that the module does successfully make something move to
a given state.

Reporting on all the changes it made (after the fact), is a bit less in the
"halting problem" category but is ridiculously complex.

I know that ansible has option --list tasks, --list-hosts, etc - but
during development code changes quickly and '--list-tasks' can show me
clearly which tasks will run, but doesn't show logic of operation (Which
variables must be setup for playbook, how it will work, what is really
installing) - for example for tasks with lists - no clear info what will be
installed, etc.

So ansible has a parameter here, which is on by default, to fail if
variables are undefined.

Best practices should define defaults for everything, but if you require
parameters with "-e", perhaps you might want to consider using
"vars_prompt" instead to make sure they get values, or wrap things in a
simple script such that values to "-e" get sourced from -e "@filename.yml"
instead.

IMHO, this is related with #1 (documentation).

How do you sort this challange - how do you know what ansible will do and
whether nothing will be broken on already existing environments?

There's a pretty strong commitment towards not making backwards
incompatible changes (unless strictly neccessary) if you mean for the
project itself.

In production, we'd definitely recommend using staging and test
environments.

3

“As I ansible user I would like to use docstrings in yaml file and quickly build documentation (the best for sphinx-doc if possible). Something like doxygen is doing for C++ code.”

You could look at a new project ansible-docgen.