diff options
Diffstat (limited to 'docs/usage.md')
| -rw-r--r-- | docs/usage.md | 334 |
1 files changed, 334 insertions, 0 deletions
diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 0000000..dbe115d --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,334 @@ +# Using + +## Using commands + +After you install Ansible-lint, run `ansible-lint --help` to display available +commands and their options. + +```console exec="1" source="console" +$ ansible-lint --help +``` + +### Command output + +Ansible-lint prints output on both `stdout` and `stderr`. + +- `stdout` displays rule violations. +- `stderr` displays logging and free-form messages like statistics. + +Most `ansible-lint` examples use pep8 as the output format (`-p`) which is +machine parseable. + +Ansible-lint also print errors using their [annotation] format when it detects +the `GITHUB_ACTIONS=true` and `GITHUB_WORKFLOW=...` variables. + +[annotation]: + https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#setting-an-error-message + +## Caching + +For optimal performance, Ansible-lint creates caches with installed or mocked +roles, collections, and modules in the `{project_dir}/.cache` folder. The +location of `{project_dir}` is passed with a command line argument, determined +by the location of the configuration file, git project top-level directory, or +user home directory. + +To perform faster re-runs, Ansible-lint does not automatically clean the cache. +If required you can do this manually by simply deleting the `.cache` folder. +Ansible-lint creates a new cache on the next invocation. + +You should add the `.cache` folder to the `.gitignore` file in your git +repositories. + +## Gradual adoption + +For an easier gradual adoption, adopters should consider [ignore +file][configuring.md#ignoring-rules-for-entire-files] feature. This allows the +quick introduction of a linter pipeline for preventing addition of new +violations, while known violations are ignored. Some people can work on +addressing these historical violations while others may continue to work on +other maintenance tasks. + +The deprecated `--progressive` mode was removed in v6.16.0 as it added code +complexity and performance overhead. It also presented several corner cases +where it failed to work as expected and caused false negatives. + +## Linting playbooks and roles + +Ansible-lint recommends following the [collection structure layout] whether you +plan to build a collection or not. + +Following that layout assures the best integration with all ecosystem tools +because it helps those tools better distinguish between random YAML files and +files managed by Ansible. When you call `ansible-lint` without arguments, it +uses internal heuristics to determine file types. + +You can specify the list of **roles** or **playbooks** that you want to lint +with the `-p` argument. For example, to lint `examples/playbooks/play.yml` and +`examples/roles/bobbins`, use the following command: + +```console exec="1" source="console" returncode="2" +$ ansible-lint --offline -p examples/playbooks/play.yml examples/roles/bobbins +``` + +[collection structure layout]: + https://docs.ansible.com/ansible-core/devel/dev_guide/developing_collections_structure.html#collection-structure + +## Running example playbooks + +Ansible-lint includes an `ansible-lint/examples` folder that contains example +playbooks with different rule violations and undesirable characteristics. You +can run `ansible-lint` on the example playbooks to observe Ansible-lint in +action, as follows: + +```console exec="1" source="console" returncode="2" +$ ansible-lint --offline -p examples/playbooks/example.yml +``` + +Ansible-lint also handles playbooks that include other playbooks, tasks, +handlers, or roles, as the `examples/playbooks/include.yml` example +demonstrates. + +```console exec="1" source="console" returncode="2" +$ ansible-lint --offline -q -p examples/playbooks/include.yml +``` + +## Output formats + +### pep8 + +```console exec="1" source="console" returncode="2" +$ ansible-lint --offline -q -f pep8 examples/playbooks/norole.yml +``` + +### SARIF JSON + +Using `--format sarif` or `--format json` the linter will output on stdout a +report in [SARIF] + +We also have an option `--sarif-file FILE` option that can make the linter dump +the output to a file while not altering its normal stdout output. This can be +used in CI/CD pipelines. + +```bash exec="1" source="tabbed-left" result="json" returncode="2" +ansible-lint --offline -q -f sarif examples/playbooks/norole.yml +``` + +### Code Climate JSON + +You can generate `JSON` reports based on the [Code Climate] specification as the +`examples/playbooks/norole.yml` example demonstrates. + +```bash exec="1" source="tabbed-left" result="json" returncode="2" +ansible-lint --offline -q -f codeclimate examples/playbooks/norole.yml +``` + +Historically `-f json` was used to generate Code Climate JSON reports but in +never versions we switched its meaning point SARIF JSON format instead. + +!!! warning + + When possible we recommend using the [SARIF](#sarif-json) format instead of the Code Climate + as that one is more complete and has a full specification and also a JSON + validation schema. Code Climate format does not expose our severity + levels because we use that field to map warnings + as `minor` and errors as `major` issues. + +## Specifying rules at runtime + +By default, `ansible-lint` applies rules found in +`ansible-lint/src/ansiblelint/rules`. Use the `-r /path/to/custom-rules` option +to specify the directory path to a set of custom rules. For multiple custom rule +sets, pass each set with a separate `-r` option. + +You can also combine the default rules with custom rules with the `-R` option +along with one or more `-r` options. + +### Including rules with tags + +Each rule has an associated set of one or more tags. Use the `-T` option to view +the list of tags for each available rule. + +You can then use the `-t` option to specify a tag and include the associated +rules in the lint run. For example, the following `ansible-lint` command applies +only the rules associated with the _idempotency_ tag: + +```console exec="1" source="console" returncode="0" +$ ansible-lint -t idempotency playbook.yml +``` + +The following shows the available tags in an example set of rules and the rules +associated with each tag: + +```bash exec="1" source="console" +ansible-lint -T 2>/dev/null +``` + +### Excluding rules with tags + +To exclude rules by identifiers or tags, use the `-x SKIP_LIST` option. For +example, the following command applies all rules except those with the +_formatting_ and _metadata_ tags: + +```bash +$ ansible-lint -x formatting,metadata playbook.yml +``` + +### Ignoring rules + +To only warn about rules, use the `-w WARN_LIST` option. For example, the +following command displays only warns about violations with rules associated +with the `experimental` tag: + +```console +$ ansible-lint -w experimental playbook.yml +``` + +By default, the `WARN_LIST` includes the `['experimental']` tag. If you define a +custom `WARN_LIST` you must add `'experimental'` so that Ansible-lint does not +fail against experimental rules. + +## Muting warnings to avoid false positives + +Not all linting rules are precise, some are general rules of thumb. Advanced +_git_, _yum_ or _apt_ usage, for example, can be difficult to achieve in a +playbook. In cases like this, Ansible-lint can incorrectly trigger rule +violations. + +To disable rule violations for specific tasks, and mute false positives, add +`# noqa: [rule_id]` to the end of the line. It is best practice to add a comment +that explains why rules are disabled. + +You can add the `# noqa: [rule_id]` comment to the end of any line in a task. +You can also skip multiple rules with a space-separated list. + +```yaml +- name: This task would typically fire git-latest and partial-become rules + become_user: alice # noqa: git-latest partial-become + ansible.builtin.git: src=/path/to/git/repo dest=checkout +``` + +If the rule is line-based, `# noqa: [rule_id]` must be at the end of the line. + +```yaml +- name: This would typically fire jinja[spacing] + get_url: + url: http://example.com/file.conf + dest: "{{dest_proj_path}}/foo.conf" # noqa: jinja[spacing] +``` + +If you want Ansible-lint to skip a rule entirely, use the `-x` command line +argument or add it to `skip_list` in your configuration. + +The least preferred method of skipping rules is to skip all task-based rules for +a task, which does not skip line-based rules. You can use the +`skip_ansible_lint` tag with all tasks or the `warn` parameter with the +_command_ or _shell_ modules, for example: + +```yaml +- name: This would typically fire no-free-form + command: warn=no chmod 644 X + +- name: This would typically fire command-instead-of-module + command: git pull --rebase + args: + warn: false + +- name: This would typically fire git-latest + git: src=/path/to/git/repo dest=checkout + tags: + - skip_ansible_lint +``` + +## Applying profiles + +Ansible-lint profiles allow content creators to progressively improve the +quality of Ansible playbooks, roles, and collections. + +During early development cycles, you need Ansible-lint rules to be less strict. +Starting with the minimal profile ensures that Ansible can load your content. As +you move to the next stage of developing content, you can gradually apply +profiles to avoid common pitfalls and brittle complexity. Then, when you are +ready to publish or share your content, you can use the `shared` and +`production` profiles with much stricter rules. These profiles harden security, +guarantee reliability, and ensure your Ansible content is easy for others to +contribute to and use. + +!!! note + + Tags such as `opt-in` and `experimental` do not take effect for rules that are included in profiles, directly or indirectly. + If a rule is in a profile, Ansible-lint applies that rule to the content. + +After you install and configure `ansible-lint`, you can apply profiles as +follows: + +1. View available profiles with the `--list-profiles` flag. + + ```bash + ansible-lint --list-profiles + ``` + +2. Specify a profile with the `--profile` parameter to lint your content with + those rules, for example: + +- Enforce standard styles and formatting with the `basic` profile. + + ```bash + ansible-lint --profile=basic + ``` + +- Ensure automation consistency, reliability, and security with the `safety` + profile. + + ```bash + ansible-lint --profile=safety + ``` + +## Vaults + +As ansible-lint executes ansible, it also needs access to encrypted secrets. If +you do not give access to them or you are concerned about security implications, +you should consider refactoring your code to allow it to be linted without +access to real secrets: + +- Configure dummy fallback values that are used during linting, so Ansible will + not complain about undefined variables. +- Exclude the problematic files from the linting process. + +```yaml +--- +# Example of avoiding undefined variable error +foo: "{{ undefined_variable_name | default('dummy') }}" +``` + +Keep in mind that a well-written playbook or role should allow Ansible's syntax +check from passing on it, even if you do not have access to the vault. + +Internally ansible-lint runs `ansible-playbook --syntax-check` on each playbook +and also on roles. As ansible-code does not support running syntax-check +directly on roles, the linter will create temporary playbooks that only include +each role from your project. You will need to change the code of the role in a +way that it does not produce syntax errors when called without any variables or +arguments. This usually involves making use of `defaults/` but be sure that you +fully understand [variable precedence]. + +[code climate]: + https://github.com/codeclimate/platform/blob/master/spec/analyzers/SPEC.md#data-types +[sarif]: + https://docs.oasis-open.org/sarif/sarif/v2.1.0/csprd01/sarif-v2.1.0-csprd01.html +[variable precedence]: + https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_variables.html#understanding-variable-precedence + +## Dependencies and requirements + +Ansible-lint will recognize `requirements.yml` files used for runtime and +testing purposes and install them automatically. Valid locations for these files +are: + +- [`requirements.yml`](https://docs.ansible.com/ansible/latest/galaxy/user_guide.html#installing-roles-and-collections-from-the-same-requirements-yml-file) +- `roles/requirements.yml` +- `collections/requirements.yml` +- `tests/requirements.yml` +- `tests/integration/requirements.yml` +- `tests/unit/requirements.yml` +- [`galaxy.yml`](https://docs.ansible.com/ansible/latest/dev_guide/collections_galaxy_meta.html) |