From 2c0897caf2b2fe6eecc2361f4fd5446ba1991105 Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Wed, 6 Feb 2019 15:56:52 -0500 Subject: [PATCH] mention ansible-lint and editor tools that help with playbook development (#51769) * introduce ansible-lint in playbook docs, mention editors help playbook syntax Co-Authored-By: samccann --- .../community/other_tools_and_programs.rst | 1 + .../rst/user_guide/playbooks_intro.rst | 55 ++++++++++++++----- 2 files changed, 42 insertions(+), 14 deletions(-) diff --git a/docs/docsite/rst/community/other_tools_and_programs.rst b/docs/docsite/rst/community/other_tools_and_programs.rst index c54db6b7f8..87f62786ef 100644 --- a/docs/docsite/rst/community/other_tools_and_programs.rst +++ b/docs/docsite/rst/community/other_tools_and_programs.rst @@ -83,6 +83,7 @@ There are various ways to find existing issues and pull requests (PRs) - `PR by File `_ - shows a current list of all open pull requests by individual file. An essential tool for Ansible module maintainers. - `jctanner's Ansible Tools `_ - miscellaneous collection of useful helper scripts for Ansible development. +.. _validate-playbook-tools: ****************************** Tools for Validating Playbooks diff --git a/docs/docsite/rst/user_guide/playbooks_intro.rst b/docs/docsite/rst/user_guide/playbooks_intro.rst index fe811c0aa7..901358871c 100644 --- a/docs/docsite/rst/user_guide/playbooks_intro.rst +++ b/docs/docsite/rst/user_guide/playbooks_intro.rst @@ -1,6 +1,9 @@ Intro to Playbooks ================== +.. contents:: + :local: + .. _about_playbooks: About Playbooks @@ -37,6 +40,10 @@ Playbook Language Example Playbooks are expressed in YAML format (see :ref:`yaml_syntax`) and have a minimum of syntax, which intentionally tries to not be a programming language or script, but rather a model of a configuration or a process. +.. note:: + Some editors have add-ons that can help you write clean YAML syntax in your playbooks. See :ref:`other_tools_and_programs` for details. + + Each playbook is composed of one or more 'plays' in a list. The goal of a play is to map a group of hosts to some well defined roles, represented by @@ -52,7 +59,9 @@ server group, then more commands back on the webservers group, etc. to do different things. It's not as if you were just defining one particular state or model, and you can run different plays at different times. -For starters, here's a playbook that contains just one play:: +.. _apache-playbook: + +For starters, here's a playbook, ``verify-apache.yml`` that contains just one play:: --- - hosts: webservers @@ -469,29 +478,47 @@ Run ``ansible-pull --help`` for details. There's also a `clever playbook `_ available to configure ``ansible-pull`` via a crontab from push mode. -.. _tips_and_tricks: +.. _linting_playbooks: -Tips and Tricks -``````````````` +Linting playbooks +````````````````` -To check the syntax of a playbook, use ``ansible-playbook`` with the ``--syntax-check`` flag. This will run the -playbook file through the parser to ensure its included files, roles, etc. have no syntax problems. +You can use `ansible-lint `_ to run a detail check of your playbooks before you execute them. -Look at the bottom of the playbook execution for a summary of the nodes that were targeted -and how they performed. General failures and fatal "unreachable" communication attempts are -kept separate in the counts. +For example, if you run ``ansible-lint`` on the :ref:`verify-apache.yml playbook ` introduced earlier in this section, you'll get the following results: -If you ever want to see detailed output from successful modules as well as unsuccessful ones, -use the ``--verbose`` flag. This is available in Ansible 0.5 and later. +.. code-block:: bash + + $ ansible-lint veryify-apache.yml + [403] Package installs should not use latest + verify-apache.yml:8 + Task/Handler: ensure apache is at the latest version + +The `ansible-lint default rules `_ page describes each error. For ``[403]``, the recommended fix is to change ``state: latest`` to ``state: present`` in the playbook. -To see what hosts would be affected by a playbook before you run it, you -can do this:: +Other playbook verification options +``````````````````````````````````` +See :ref:`validate-playbook-tools` for a detailed list of tools you can use to verify your playbooks. Here are some others that you should consider: - ansible-playbook playbook.yml --list-hosts +* To check the syntax of a playbook, use ``ansible-playbook`` with the ``--syntax-check`` flag. This will run the + playbook file through the parser to ensure its included files, roles, etc. have no syntax problems. + +* Look at the bottom of the playbook execution for a summary of the nodes that were targeted + and how they performed. General failures and fatal "unreachable" communication attempts are kept separate in the counts. + +* If you ever want to see detailed output from successful modules as well as unsuccessful ones, + use the ``--verbose`` flag. This is available in Ansible 0.5 and later. + +* To see what hosts would be affected by a playbook before you run it, you + can do this:: + + ansible-playbook playbook.yml --list-hosts .. seealso:: + `ansible-lint `_ + Learn how to test Ansible Playbooks syntax :ref:`yaml_syntax` Learn about YAML syntax :ref:`playbooks_best_practices`