Analysis of Ansible roles
Summary
This tool is intended to analyse Ansible roles and report on things like variables that you have used but failed to document, files that you have stored which aren't referenced, report on tags that aren't present, and operations that might be dangerous. It does a reasonable job some of the time, and is poor at others.
It is provided as a reimplementation of the Ansible processor and Jinja2 templating library. As such, it doesn't know about everything that these systems can do. It tries to emulate and provide a guide as to how the system might respond as well as it can.
Prerequisites
The tool requires perl and the packages listed in the cpan.txt file.
Usage
To use the tool to read a role, change to the directory that contains tols and use a command like:
ansible-analyse-roles/analyse-role.pl -role <role name>This will load the role and report and messages related to it.
Specific checks can be enabled in the tool - see the -help output for details.
For example, to find problems with tasks that are missing tags, you might use:
ansible-analyse-roles/analyse-role.pl -role <role name> --warn-missing-tagsRole warnings
The output from the tool may generate warnings with a backtrace that shows where the problems lie. For example, you might apply the above command to a role that installs ffmpeg and see the following messages:
Warning: [ffmpeg] (task-tags-missing) Tags were not set
- Action 'tags'
- Task index 1: Add RPMFusion to CentOS
- File 'main.yaml'
- Section 'tasks'
- Role 'ffmpeg'
Warning: [ffmpeg] (task-tags-missing) Tags were not set
- Action 'tags'
- Task index 2: Install ffmpeg packages
- File 'main.yaml'
- Section 'tasks'
- Role 'ffmpeg'
Info: Needs role 'ffmpeg'There are two warnings, and an informational telling you which roles were processed - if there were more dependencies, the would be included here as well.
The warning messages include:
- The role that was a problem (
[ffmpeg]). - The code for this warning (
(task-tags-missing)). These codes can be ignored if they're not relevant with the-ignore-warning <code>command line switch. - The problem description (
Tags were not set). - A backtrace of the components being processed, from the most specific, stepping out to the least specific. In this case there is an Action (given by name), then a Task (which is given by number and name), a file (given by its filename), the section within the role that is being processed (indicated by the directory name), and the role (by its name).
Understanding the role
The analyser attempts to process what would be done by the role. We can show information about what the role was trying to do. For example, to show the interpretation of a role you could use -list-tasks, which might produce this output:
# Add RPMFusion to CentOS
package:
- name: https://download1.rpmfusion.org/free/el/rpmfusion-free-release-7.noarch.rpm
- state: latest
- conditional: ansible_distribution == "CentOS" and ansible_distribution_major_version | int == 7
# Install ffmpeg packages
package:
- name: [ 'ffmpeg' ]
- state: latest
Info: Needs role 'ffmpeg'This shows how the role was interpreted. Variables are expanded, so for example the package name here has been expanded from internal variables.
Similarly, you might list variables used by the role with --list-variables:
Info: There are 3 variable(s) set/used in the role
Info: Role Source Template Checked Used : Variable : Value
Info: ------ -------------- --------- ------- ---- : -------------------- : -----
Info: ffmpeg ansible Raw - Used : ansible_distribution : 'Ubuntu'
Info: ffmpeg ansible Raw - Used : ansible_distribution_major_version : 22
Info: ffmpeg vars Templated - Used : ffmpeg_packages : { CentOS: [ 'ffmpeg' ], RedHat: [ 'ffmpeg' ], Ubuntu: [ 'ffmpeg' ] }
Info: Needs role 'ffmpeg'This produdes a table of the variables, and where they are stored. For example the ffmpeg_packages dictionary is held in the vars definitions, and the internal ansible-supplied variables are also referenced.
Generating documentation
It is very useful to be able to describe what the role does without having to dive into the (possibly many) tasks that are present. Similarly, knowing which tags are available in a role makes it easier to filter its operations.
The tool can generate a README.md which describes an example of what was interpreted by the analyser. Obviously this cannot be perfect because it does not know the target system, and any conditionals and derived information will not be available. But it can help to show what the role does, or be the basis for describing the tool in more detail.
To generate such a file, use a command like:
ansible-analyse-roles/analyse-role.pl -role <role> --generate-readmeIn the example role, this produces a README.md like this:
# Role 'ffmpeg'
## Requirements
* _None_
## Variables used
* _None_
## Tags
| Role | Tags | Role Tasks |
| ------ | ---------- | ------------ |
| ffmpeg | _untagged_ | 2 / 2 |
## Files affected
* _None_
## Packages affected
| Role | Package | Operation |
| ---- | ------- | --------- |
| ffmpeg | `package:ffmpeg` | upgraded |
| ffmpeg | `package:https://download1.rpmfusion.org/free/el/rpmfusion-free-release-7.noarch.rpm` | upgraded |If there were additional role dependencies, these would be described in the Requirements. Any external variables (those not described in vars) would be listed, together with their descriptive comment. The tag usage is reported (this is mostly useful for auditing, if you don't tag your tasks in roles). Any files and packages are recognised, together with the manner in which they are affected - whether they're created, removed, upgraded, or whatever.
A more general script can apply this README generation to all the roles in a directory. For example:
ansible-analyse-roles/generate-all-readmes.sh <ansible directory>