2018-12-19 11:19:07 +01:00
# ansible-later
2018-12-19 13:19:23 +01:00
[](https://cloud.drone.io/xoxys/ansible-later)
[](https://pypi.org/project/ansible-later/)
[](https://pypi.org/project/ansible-later/)
[](https://pypi.org/project/ansible-later/)
2018-12-19 11:19:07 +01:00
This is a fork of Will Thames [ansible-review ](https://github.com/willthames/ansible-review ) so credits goes to him
for his work on ansible-review and ansible-lint.
2019-01-28 11:25:56 +01:00
`ansible-later` is a best pratice scanner and linting tool. In most cases, if you write ansibel roles in a team,
it helps to have a coding or best practice guideline in place. This will make ansible roles more readeble for all
maintainers and can reduce the troubleshooting time.
`ansible-later` does _**not**_ ensure that your role will work as expected.
`ansible-later` is an acronym for **L**ovely **A**utomation **TE**sting f**R**mework.
2018-12-19 11:19:07 +01:00
## Table of Content
- [Setup ](#setup )
- [Using pip ](#using-pip )
- [From source ](#from-source )
- [Usage ](#usage )
- [Configuration ](#configuration )
- [Review a git repositories ](#review-a-git-repositories )
- [Review a list of files ](#review-a-list-of-files )
- [Buildin rules ](#buildin-rules )
- [Build your own ](#build-your-own )
- [The standards file ](#the-standards-file )
- [Candidates ](#candidates )
- [Minimal standards checks ](#minimal-standards-checks )
- [License ](#license )
- [Maintainers and Contributors ](#maintainers-and-contributors )
---
### Setup
#### Using pip
```Shell
# From internal pip repo as user
pip install ansible-later --user
# .. or as root
sudo pip install ansible-later
```
#### From source
```Shell
# Install dependency
git clone https://repourl
export PYTHONPATH=$PYTHONPATH:`pwd`/ansible-later/ansiblelater
export PATH=$PATH:`pwd`/ansible-later/ansiblelater/bin
```
### Usage
```Shell
ansible-later FILES
```
Where FILES is a space delimited list of files to review.
ansible-later is _not_ recursive and won't descend
into child folders; it just processes the list of files you give it.
Passing a folder in with the list of files will elicit a warning:
```Shell
WARN: Couldn't classify file ./foldername
```
ansible-later will review inventory files, role
files, python code (modules, plugins) and playbooks.
- The goal is that each file that changes in a
changeset should be reviewable simply by passing
those files as the arguments to ansible-later.
- Roles are slightly harder, and sub-roles are yet
harder still (currently just using `-R` to process
roles works very well, but doesn't examine the
structure of the role)
- Using `{{ playbook_dir }}` in sub roles is so far
very hard.
- This should work against various repository styles
- per-role repository
- roles with sub-roles
- per-playbook repository
- It should work with roles requirement files and with local roles
#### Configuration
If your standards (and optionally inhouse rules) are set up, create
a configuration file in the appropriate location (this will depend on
your operating system)
The location can be found by using `ansible-later` with no arguments.
You can override the configuration file location with the `-c` flag.
```INI
[rules]
standards = /path/to/your/standards/rules
```
The standards directory can be overridden with the `-d` argument.
#### Review a git repositories
- `git ls-files | xargs ansible-later` works well in
a roles repo to review the whole role. But it will
review the whole of other repos too.
- `git ls-files *[^LICENSE,.md] | xargs ansible-later`
works like the first example but excludes some
unnecessary files.
- `git diff branch_to_compare | ansible-later` will
review only the changes between the branches and
surrounding context.
#### Review a list of files
- `find . -type f | xargs ansible-later` will review
all files in the current folder (and all subfolders),
even if they're not checked into git
#### Buildin rules
Reviews are nothing without some rules or standards against which to review. ansible-later
comes with a couple of built-in checks explained in the following table.
| Rule | ID | Description | Parameter |
| ------------------------------- | ----------- | ---------------------------------------------------------------- | -------------------------------------------------------------------- |
| check_yaml_empty_lines | LINT0001 | YAML should not contain unnecessarily empty lines. | {max: 1, max-start: 0, max-end: 0} |
| check_yaml_indent | LINT0002 | YAML should be correctly indented. | {spaces: 2, check-multi-line-strings: false, indent-sequences: true} |
| check_yaml_hyphens | LINT0003 | YAML should use consitent number of spaces after hyphens (-). | {max-spaces-after: 1} |
| check_yaml_document_start | LINT0004 | YAML should contain document start marker. | {document-start: {present: true}} |
| check_yaml_colons | LINT0005 | YAML should use consitent number of spaces around colons. | {colons: {max-spaces-before: 0, max-spaces-after: 1}} |
| check_yaml_file | LINT0006 | Roles file should be in yaml format. | |
| check_yaml_has_content | LINT0007 | Files should contain useful content. | |
| check_native_yaml | LINT0008 | Use YAML format for tasks and handlers rather than key=value. | |
| check_line_between_tasks | ANSIBLE0001 | Single tasks should be separated by an empty line. | |
| check_meta_main | ANSIBLE0002 | Meta file should contain a basic subset of parameters. | author, description, min_ansible_version, platforms, dependencies |
| check_unique_named_task | ANSIBLE0003 | Tasks and handlers must be uniquely named within a file. | |
| check_braces | ANSIBLE0004 | YAML should use consitent number of spaces around variables. | |
| check_scm_in_src | ANSIBLE0005 | Use scm key rather than src: scm+url in requirements file. | |
| check_named_task | ANSIBLE0006 | Tasks and handlers must be named. | excludes: meta, debug, include\_\*, import\_\*, block |
| check_name_format | ANSIBLE0007 | Name of tasks and handlers must be formatted. | formats: first letter capital |
| check_command_instead_of_module | ANSIBLE0008 | Commands should not be used in place of modules. | |
| check_install_use_latest | ANSIBLE0009 | Package managers should not install with state=latest. | |
| check_shell_instead_command | ANSIBLE0010 | Use Shell only when piping, redirecting or chaining commands. | |
| check_command_has_changes | ANSIBLE0011 | Commands should be idempotent and only used with some checks. | |
| check_empty_string_compare | ANSIBLE0012 | Don't compare to "" - use `when: var` or `when: not var` | |
| check_compare_to_literal_bool | ANSIBLE0013 | Don't compare to True/False - use `when: var` or `when: not var` | |
2019-01-28 11:25:56 +01:00
| check_literal_bool_format | ANSIBLE0014 | Literal bools should be written as `True/False` or `yes/no` | forbidden values are `true|false|TRUE|FALSE|Yes|No|YES|NO` |
2018-12-19 11:19:07 +01:00
### Build your own
#### The standards file
A standards file comprises a list of standards, and optionally some methods to
check those standards.
Create a file called standards.py (this can import other modules)
```Python
from ansiblelater include Standard, Result
tasks_are_uniquely_named = Standard(dict(
id="ANSIBLE0003",
name="Tasks and handlers must be uniquely named within a single file",
check=check_unique_named_task,
version="0.1",
types=["playbook", "task", "handler"],
))
standards = [
tasks_are_uniquely_named,
role_must_contain_meta_main,
]
```
When you add new standards, you should increment the version of your standards.
Your playbooks and roles should declare what version of standards you are
using, otherwise ansible-later assumes you're using the latest. The declaration
is done by adding standards version as first line in the file. e.g.
```INI
# Standards: 1.2
```
To add standards that are advisory, don't set the version. These will cause
a message to be displayed but won't constitute a failure.
When a standard version is higher than declared version, a message will be
displayed 'WARN: Future standard' and won't constitute a failure.
An example standards file is available at
[ansiblelater/examples/standards.py ](ansiblelater/examples/standards.py )
If you only want to check one or two standards quickly (perhaps you want
to review your entire code base for deprecated bare words), you can use the
`-s` flag with the name of your standard. You can pass `-s` multiple times.
```Shell
git ls-files | xargs ansible-later -s "bare words are deprecated for with_items"
```
You can see the name of the standards being checked for each different file by running
`ansible-later` with the `-v` option.
#### Candidates
Each file passed to `ansible-later` will be classified. The result is a `Candidate` object
which contains some meta informations and is an instance of one of following object types.
| Object type | Description |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------- |
| Task | all files within the parent dir `tasks` |
| Handler | all files within the parent dir `handler` |
| RoleVars | all files within the parent dir `vars` or `default` |
| GroupVars | all files (including subdirs) within the parent dir `group_vars` |
| HostVars | all files (including subdirs) within the parent dir `host_vars` |
| Meta | all files within the parent dir `meta` |
| Code | all files within the parent dir `library` , `lookup_plugins` , `callback_plugins` and `filter_plugins` or python files (`.py`) |
| Inventory | all files within the parent dir `inventory` and `inventory` or `hosts` in filename |
| Rolesfile | all files with `rolesfile` or `requirements` in filename |
| Makefile | all files with `Makefile` in filename |
| Template | all files (including subdirs) within the parent dir `templates` or jinja2 files (`.j2`) |
| File | all files (including subdirs) within the parent dir `files` |
| Playbook | all yaml files (`.yml` or `.yaml` ) not maching a previous object type |
| Doc | all files with `README` in filename |
#### Minimal standards checks
A typical standards check will look like:
```Python
def check_playbook_for_something(candidate, settings):
result = Result(candidate.path) # empty result is a success with no output
with open(candidate.path, 'r') as f:
for (lineno, line) in enumerate(f):
if line is dodgy:
# enumerate is 0-based so add 1 to lineno
result.errors.append(Error(lineno+1, "Line is dodgy: reasons"))
return result
```
All standards check take a candidate object, which has a path attribute.
The type can be inferred from the class name (i.e. `type(candidate).__name__` )
or from the table [here ](#candidates ).
They return a `Result` object, which contains a possibly empty list of `Error`
objects. `Error` objects are formed of a line number and a message. If the
error applies to the whole file being reviewed, set the line number to `None` .
Line numbers are important as `ansible-later` can review just ranges of files
to only review changes (e.g. through piping the output of `git diff` to
`ansible-later` ).
### License
This project is licensed under the MIT License - see the [LICENSE ](LICENSE ) file for details.
### Maintainers and Contributors
[Robert Kaussow ](https://github.com/xoxys )
