ANSIBLE BEST PRACTICES: ROLES & MODULES

Tim Appnel, Senior Product Manager

GitHub: tima
Twitter: appnelgroup
 THE ANSIBLE WAY

4
 COMPLEXITY KILLS PRODUCTIVITY.
That's not just a marketing slogan. We really mean it and
believe that. We strive to reduce complexity in how we've
designed Ansible tools and encourage you to do the
same. Strive for simplification in what you automate.

5
 OPTIMIZE FOR READABILITY.
If done properly, it can be the documentation of your
workflow automation.

6
 THINK DECLARATIVELY.
Ansible is a desired state engine by design. If you're
trying to "write code" in your plays and roles, you're
setting yourself up for failure. Our YAML-based
playbooks were never meant to be for programming.

7
ROLES + MODULES

Use the right tool for the job

ROLES MODULES
• Self-contained portable units • Small “programs” that
of Ansible automation perform actions on remote
• Expressed in YAML and hosts or on their behalf
bundled with associated • Expressed as code
assets – i.e. Python, PowerShell
• Decoupled from assumptions • Called by an Ansible task
made by plays • Modules do all of the heavy
lifting in Ansible

8
ROLES + MODULES

Use the right tool for the job

ROLES MODULES
• Reuse and collaboration of • Sophisticated interactions
common automation and logic of a unit of work
workflows & configurations usually with a command line
• Provide full life-cycle tool or APIs
management of a service, • Abstract complexity away
microservice or container from users to make powerful
• “De-facto” enforcement of automation simple
standards and policies

9
 ROLES + MODULES

Use the right tool for the job

ROLES MODULES

10
 BEST PRACTICES: ROLES

11
 ROLES ARE ANSIBLE CONTENT

The same best practices for your plays still apply

• Use native YAML syntax

• Version control your Ansible content
• Use command modules sparingly
• Always seek out a module first
• “Name” your plays, blocks and tasks
• Use human meaningful names with variables, hosts, etc.
• Clean up your debugging messages

12
 ROLE DESIGN

Keep the purpose and function of a role self-contained and

focused to do one thing well

• Think about the full life-cycle of a service, microservice or

container — not a whole stack or environment
• Keep provisioning separate from configuration and app
deployment

• Roles are not classes or object or libraries – those are

programming constructs
• Keep roles loosely-coupled — limit hard dependencies on other
roles or external variables

13
 EXHIBIT A EXHIBIT B

# blackbox_role_playbook.yml # componentized_roles_playbook.yml
--- ---
- hosts: all - hosts: localhost
roles: roles:
- umbrella_corp_stack - azure_provisioner
- hosts: all
roles:
- system_security
- hosts: webservers
roles:
- python_common
- python_django
- nginx_uwsgi
- racoon_app
- hosts: databases
roles:
- pgsql-replication

14
 ROLE DESIGN

Maximize your role design for portability and reuse

# requirements.yml
• Use ansible-galaxy to
---
install your roles - src: nginxinc.nginx
• Use a roles files (i.e. version: 0.8.0
- src: samdoran.pgsql-replication
requirements.yml) to version: b5013e6
manifest your project roles - src: geerlingguy.firewall
version: 2.4.0
• When using a shared role
always declare a specific
version such as a tag or
commit

16
 ROLE USABILITY

Roles should run with as few, if any, parameter variables as

possible

• Practice convention over configuration

• Provide sane defaults
• Use variable parameters to modify default behaviour
• Easier to develop, test and use quickly & securely
• A role should always be more than a single task file

17
 EXHIBIT A EXHIBIT B

# defaults_no_playbook.yml # defaults_yes_playbook.yml
--- ---
- hosts: webservers - hosts: webservers
roles: roles:
- role: apache_simple - role: apache_simple
apache_http_port: 80 - role: apache_simple
apache_doc_root: /var/www/html apache_http_port: 8080
apache_user: apache apache_doc_root: /www/example.com
apache_group: apache
- role: apache_simple
apache_http_port: 8080 # default/main.yml
apache_doc_root: /www/example.com ---
apache_user: apache apache_http_port: 80
apache_group: apache apache_doc_root: /var/www/html
apache_user: apache
apache_group: apache

18
 ROLE USABILITY

Use variables in your roles appropriately

• defaults/ are easy to override and most commonly used to

modify behavior
– i.e. port number or default user

• vars/ are used by the role and not likely to be changed

– i.e. a list of packages, lookup table of machine images by region

19
# default/main.yml # vars/main.yml
--- ---
apache_http_port: 80 apache_packages:
apache_doc_root: /var/www/html redhat:
apache_user: apache - httpd
apache_group: apache - mod_wsgi
debian:
- apache2
- libapache2-mod-wsgi

20
 ROLE USABILITY

Automate the testing of your roles

Use molecule, a testing framework designed to aid in the

development and testing of Ansible Roles.

Initially developed by the community, led by John Dewey of Cisco, and

adopted by Red Hat as an official Ansible project.

https://github.com/ansible/molecule

22
 ROLE USABILITY

Automate the testing of your roles

Use ansible-lint, a command-line static analysis tool that checks

playbooks and roles for identifying behaviour that could be improved.

Initially developed by Will Thames and recently adopted by Red Hat as

an official Ansible project.

https://github.com/ansible/ansible-lint

HINT: ansible-lint can be run as part of your Molecule test runs.

23
 ROLE READABILITY

Still using command modules a lot?

- name: check cert

shell: certify --list --name={{ cert_name }} --cert_store={{ cert_store }} | grep "{{ cert_name }}"
register: check_output

- name: create cert

command: certify --create --user=chris --name={{ cert_name }} --cert_store={{ cert_store }}
when: check_output.stdout.find(cert_name) != -1
register: create_output

- name: sign cert

command: certify --sign --name={{ cert_name }} --cert_store={{ cert_store }}
when: create_output.stdout.find("created") != -1

24
 ROLE READABILITY

Develop your own module

- name: create and sign cert

certify:
state: present
sign: yes
user: chris
name: "{{ cert_name }}"
cert_store: "{{ cert_store }}"

25
 BEST PRACTICES: MODULES

26
 MODULE DESIGN

Good modules are user-centric

• Modules are how Ansible balances simple and powerful

• They implement common automation tasks for a user
• They make easy tasks easier and complicated tasks possible
• They abstract users from having to know the details to get things done
• They are not one-to-one mapping of an API or command line tool interface
– This is why you should not auto-generate your modules
• They are not monolithic “does everything” modules that are hard to
understand and complicated to use correctly

27
 MODULE IMPLEMENTATION

Making the powerful simple starts with the implementation

• No side-effects with multiple runs

• Err on the side of safety
– i.e. use a temporary file and atomic_move when writing to a file
• Fail fast —— immediately detect and report failure conditions
• Support check mode
• Minimal use of dependencies

28
 MODULES INTERFACE

Modules should provide a predictable user interface

• Think desired state, think declaratively

• Avoid action or command parameters
• Keep parameters focused and narrowly defined — refrain from
parameters that take complex data structures
• Parameter names should be in lowercase and use underscores:

update_cache # YES
UpdateCache # NO
updateCache # NO

29
 MODULES INTERFACE

Modules should provide a predictable user interface

• Normalize common parameter names with other modules such

as:
– name
– state
– dest
– src
– path
– username
– password

31
 MODULES IN THE WILD

For your consideration...

• kubernetes
– monolithic and requires expert knowledge of k8s
• ansible-kubernetes-modules
– fine grained API mapping that is autogenerated
• k8s
– better implementation but complex parameters abound and expert knowledge
still required
• k8s_scale
– more focused on a specific task — more of this please

32
 MODULE RESPONSES

Provide informative and consistent responses

• Be consistent in what you return

• Make response data reusable by a play or role
• Return only relevant output — no logs files please
• Accurately report changed status
• Support diff mode if applicable — and return the diff conditionally

33
 MODULE EXCEPTION HANDLING

Handle errors gracefully and predictably

• Apply defensive programming

• Fail fast — validate upfront and use the built-in argument spec function
• Fail predictably and informatively when errors happen
• Avoid catch all exceptions

34
 MODULE IMPLEMENTATION

Don't reinvent the wheel

• Make use of module_utils/ -- they’re your friends

– basic.py
– api.py
– facts/
– urls.py
– six.py
– noteworthy others: ec2.py, docker.py, database.py, mysql.py,
powershell.ps1 — and many many more!

36
 MODULE DOCUMENTATION

Documentation is a requirement

• Examples should include the most common and real world usage
• Examples should be in native YAML syntax
• Return responses must be included and described
• Document your dependencies in the requirements section

37
 MODULE TESTING

Test before you commit and push your code

• Utilize the testing tools in ansible/hacking/

– test-module
– ansible-test sanity <MODULE_NAME>
• Create roles and playbooks and to test and verify all your
documented examples
– molecule
• Test locally — not with the CI/CD system

38
 MODULES IN THE WILD

(More) For your consideration...

• sysctl
– a master class in writing a “best practice” module
• ping
– the hello world of Ansible
• cron
– module implementing an interface to a command line tool
• get_url
– module implementing an interface to a python library

39
 MODULE & ACTION PLUGINS

Sometimes modules need something more

• Local controller execution of a module entirely possible or required...

• Special setup requirements before the module is dispatched to the host...
• Need to supplement a module with the services of another core module
such as copy and a role won’t cut it...

An Action Plugin executes on the controller and perform logic before

dispatching a module

40
 Thanks

41
 MORE RESOURCES

Ansible Developers Guide

http://docs.ansible.com/ansible/devel/dev_guide/index.html

43