Skip to content

Latest commit

 

History

History
167 lines (149 loc) · 5.22 KB

README.adoc

File metadata and controls

167 lines (149 loc) · 5.22 KB
Raw

Playbooks good practices

Keep your playbooks as simple as possible

Details
Explanations

Don’t put too much logic in your playbook, put it in your roles (or even in custom modules), and try to limit your playbooks to a list of a roles.

Rationale

Roles are meant to be re-used and the structure helps you to make your code re-usable. The more code you put in roles, the higher the chances you, or others, can reuse it. Also, if you follow the type-function pattern, you can very easily create new (type) playbooks by just re-shuffling the roles. This way you can create a playbook for each purpose without having to duplicate a lot of code. This, in turn, also helps with the maintainability as there is only a single place where necessary changes need to be implemented, and that is in the role

Examples
An example of playbook containing only roles
---
- name: A playbook can solely be a list of roles
  hosts: all
  gather_facts: false
  become: false
  roles:
    - role1
    - role2
    - role3
Tip
 we’ll explain later why there might be a case for using include_role/import_role tasks instead of the role section.

Use either the tasks or roles section in playbooks, not both

Details
Explanations

A playbook can contain pre_tasks, roles, tasks and post_tasks sections. Avoid using both roles and tasks sections, the latter possibly containing import_role or include_role tasks.

Rationale

The order of execution between roles and tasks isn’t obvious, and hence mixing them should be avoided.

Examples

Either you need only static importing of roles and you can use the roles section, or you need dynamic inclusion and you should use only the tasks section. Of course, for very simple cases, you can just use tasks without roles.

Use tags cautiously either for roles or for complete purposes

Details
Explanations

limit your usage of tags to two aspects:

  1. either tags called like the roles to switch on/off single roles,

  2. or specific tags to reach a meaningful purpose

Don’t set tags which can’t be used on their own, or can be destructive if used on their own.

Also document tags and their purpose(s).

Rationale

there is nothing worse than tags which can’t be used alone, they bear the risk to destroy something by being called standalone. An acceptable exception is the pattern to use the role name as tag name, which can be useful while developing the playbook to test, or exclude, individual roles.

Important is that your users don’t need to learn the right sequence of tags necessary to get a meaningful result, one tag should be enough.

Examples
An example of playbook importing roles with tags
---
- name: A playbook can be a list of roles imported with tags
  hosts: all
  gather_facts: false
  become: false
  tasks:
    - name: Import role1
      ansible.builtin.import_role:
        name: role1
      tags:
        - role1
        - deploy

    - name: Import role2
      ansible.builtin.import_role:
        name: role2
      tags:
        - role2
        - deploy
        - configure

    - name: Import role3
      ansible.builtin.import_role:
        name: role3
      tags:
        - role3
        - configure

You see that each role can be skipped/run individually, but also that the tags deploy and configure can be used to do something we’ll assume to be meaningful, without having to explain at length what they do.

The same approach is also possible with include_role but requires additionally to apply the same tags to the role’s tasks, which doesn’t make the code easier to read:

An example of playbook including roles with tags
- name: a playbook can be a list of roles included with tags applied
  hosts: all
  gather_facts: false
  become: false

  tasks:
    - name: include role1
      include_role:
        name: role1
        apply:
          tags:
            - role1
            - deploy
      tags:
        - role1
        - deploy
    - name: include role2
      include_role:
        name: role2
        apply:
          tags:
            - role2
            - deploy
            - configure
      tags:
        - role2
        - deploy
        - configure
    - name: include role3
      include_role:
        name: role3
        apply:
          tags:
            - role3
            - configure
      tags:
        - role3
        - configure

Use the verbosity parameter with debug statements

Details
Explanations

Debug messages should have a verbosity defined as appropriate for the message.

Rationale

Debug messages are useful during testing and development, and can be useful to retain as playbooks go into production for future troubleshooting. However, log messages will clutter your output, which can confuse users with non-relevant information.

Examples
Adding verbosity to debug messages
- name: don't make messages always display
  debug:
    msg: "This message will clutter your log in production"

- name: this message will only appear when verbosity is 2 or more
  debug:
    msg: "Some more debug information if needed"
    verbosity: 2