ANSIBLE BEST PRACTICES AT SCALE

LEARNING THE 10 BEST PRACTICES USED BY LEADING OSS THAT DEPEND ON ANSIBLE

Keith Resar@KeithResar

@KeithResar

Keith Resar: BioWear many hats

@KeithResar Keith.Resar@RedHat.com

Coder

Open Source Contributor and Advocate

Infrastructure Architect

ANSIBLE WAS MADE TO HELP MORE PEOPLE EXPERIENCE THE POWER OF

AUTOMATION SO THEY COULD WORK BETTER AND FASTER TOGETHER

The Open Source Container Application Platform.

Built around a core of Docker container packaging and Kubernetes container cluster management, Origin is also augmented by application lifecycle management functionality and DevOps tooling. Origin provides a complete open source container application platform.

YOUR LOOK INSIDE HOW OPENSHIFT DOES ANSIBLE

ANSIBLE FILES SHOULD NOT USE JSON (USE PURE YAML INSTEAD)

RULE1

@KeithResarhttps://github.com/openshift/openshift-ansible/blob/master/docs/best_practices_guide.adoc#Ansible-files-SHOULD-NOT-use-JSON-use-pure-YAML-instead

- foo- bar: - baz - kwa - 1.0 - 2

[ "foo", { "bar": [ "baz", "kwa", 1, 2 ] }]

JSON YAML

ANSIBLE FILES SHOULD NOT USE JSON (USE PURE YAML INSTEAD)

RULE1

@KeithResarhttps://github.com/openshift/openshift-ansible/blob/master/docs/best_practices_guide.adoc#Ansible-files-SHOULD-NOT-use-JSON-use-pure-YAML-instead

YAML is a superset of JSON, which means that Ansible allows JSON syntax to be interspersed. Even though YAML (and by extension Ansible) allows for this, JSON SHOULD NOT be used.

Reasons:● Ansible is able to give clearer error messages when the files are pure

YAML● YAML makes for nicer diffs as YAML tends to be multi-line, whereas

JSON tends to be more concise● YAML reads more nicely (opinion?)

3 OR MORE PARAMETERS TO ANSIBLE MODULES SHOULD USE THE YAML DICTIONARY FORMAT

RULE2

@KeithResarhttps://github.com/openshift/openshift-ansible/blob/master/docs/best_practices_guide.adoc#Parameters-to-Ansible-modules-SHOULD-use-the-Yaml-dictionary-format-when-3-or-more-parameters-are-being-passed

# ✘ BAD- file: src=/file/to/link/to \ dest=/path/to/symlink owner=foo \ group=foo state=link

# ✔ GOOD- file: src: /file/to/link/to dest: /path/to/symlink owner: foo group: foo state: link

3 OR MORE PARAMETERS TO ANSIBLE MODULES SHOULD USE THE YAML DICTIONARY FORMAT

RULE2

@KeithResarhttps://github.com/openshift/openshift-ansible/blob/master/docs/best_practices_guide.adoc#Parameters-to-Ansible-modules-SHOULD-use-the-Yaml-dictionary-format-when-3-or-more-parameters-are-being-passed

When a module has several parameters that are being passed in, it’s hard to see exactly what value each parameter is getting.

It is preferred to use the Ansible Yaml syntax to pass in parameters so that it’s more clear what values are being passed for each parameter.

PARAMETERS TO ANSIBLE MODULES SHOULD USE THE DICTIONARY FORMAT IF LINES WOULD EXCEED 120 CHARACTERS

RULE3

@KeithResarhttps://github.com/openshift/openshift-ansible/blob/master/docs/best_practices_guide.adoc#Parameters-to-Ansible-modules-SHOULD-use-the-Yaml-dictionary-format-when-the-line-length-exceeds-120-characters

# ✘ BAD- get_url: url=http://example.com/path/file.conf dest=/etc/foo.conf sha256sum=b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c

# ✔ GOOD- get_url: url: http://example.com/path/file.conf dest: /etc/foo.conf Sha256sum: B5bb9d8014a0f9b1d61e21e796d78dc...d32812f4850b878ae4944c

PARAMETERS TO ANSIBLE MODULES SHOULD USE THE DICTIONARY FORMAT IF LINES WOULD EXCEED 120 CHARACTERS

RULE3

@KeithResarhttps://github.com/openshift/openshift-ansible/blob/master/docs/best_practices_guide.adoc#Parameters-to-Ansible-modules-SHOULD-use-the-Yaml-dictionary-format-when-the-line-length-exceeds-120-characters

Lines that are long quickly become a wall of text that isn’t easily parsable.

It is preferred to use the Ansible Yaml syntax to pass in parameters so that it’s more clear what values are being passed for each parameter.

THE ANSIBLE COMMAND MODULE SHOULD BE USED INSTEAD OF THE ANSIBLE SHELL MODULE

RULE4

@KeithResarhttps://github.com/openshift/openshift-ansible/blob/master/docs/best_practices_guide.adoc#The-Ansible-command-module-SHOULD-be-used-instead-of-the-Ansible-shell-module

# ✘ POOR- name: Bare shell execution shell: cat myfile

# BETTER- name: Quoting templated variable to avoid injection shell: cat {{ myfile | quote }}

# ✔ BEST- name: Quoting templated variable to avoid injection command: cat {{ myfile }}

THE ANSIBLE COMMAND MODULE SHOULD BE USED INSTEAD OF THE ANSIBLE SHELL MODULE

RULE4

@KeithResarhttps://github.com/openshift/openshift-ansible/blob/master/docs/best_practices_guide.adoc#The-Ansible-command-module-SHOULD-be-used-instead-of-the-Ansible-shell-module

If you want to execute a command securely and predictably, it may be better to use the command module instead, using the shell module only when explicitly required.

The Ansible shell module can run most commands that can be run from a bash CLI. This makes it extremely powerful, but it also opens our playbooks up to being exploited by attackers.

When running ad-hoc commands, use your best judgement.

ANSIBLE PLAYBOOKS MUST BEGIN WITH CHECKS FOR ANY VARIABLES THAT THEY REQUIRE

RULE5

@KeithResarhttps://github.com/openshift/openshift-ansible/blob/master/docs/best_practices_guide.adoc#Ansible-playbooks-MUST-begin-with-checks-for-any-variables-that-they-require

---- hosts: localhost gather_facts: no tasks: - fail: msg="Playbook requires g_env to be set and non empty" when: g_env is not defined or g_env == ''

---# tasks/main.yml- fail: msg="Role requires arl_env to be set and non empty" when: arl_env is not defined or arl_env == ''

ANSIBLE PLAYBOOKS MUST BEGIN WITH CHECKS FOR ANY VARIABLES THAT THEY REQUIRE

RULE5

@KeithResarhttps://github.com/openshift/openshift-ansible/blob/master/docs/best_practices_guide.adoc#Ansible-playbooks-MUST-begin-with-checks-for-any-variables-that-they-require

If an Ansible playbook or role requires certain variables to be set, it’s best to check for these up front before any other actions have been performed.

In this way, the user knows exactly what needs to be passed into the playbook.

ANSIBLE TASKS SHOULD NOT BE USED IN ANSIBLE PLAYBOOKS. INSTEAD, USE PRE_TASKS AND POST_TASKS

RULE6

@KeithResarhttps://github.com/openshift/openshift-ansible/blob/master/docs/best_practices_guide.adoc#Ansible-tasks-SHOULD-NOT-be-used-in-ansible-playbooks-Instead-use-pre_tasks-and-post_tasks

# ✘ BAD- hosts: localhost tasks: - name: Executes AFTER the example_role, so it’s confusing debug: msg="in tasks list" roles: - role: example_role

# ✔ GOOD- hosts: localhost pre_tasks: - name: Executes BEFORE the example_role, so it makes sense debug: msg="in pre_tasks list" roles: - role: example_role

ANSIBLE TASKS SHOULD NOT BE USED IN ANSIBLE PLAYBOOKS. INSTEAD, USE PRE_TASKS AND POST_TASKS

RULE6

@KeithResarhttps://github.com/openshift/openshift-ansible/blob/master/docs/best_practices_guide.adoc#Ansible-tasks-SHOULD-NOT-be-used-in-ansible-playbooks-Instead-use-pre_tasks-and-post_tasks

An Ansible play is defined as a Yaml dictionary and because of that Ansible doesn’t know if the play’s tasks list or roles list was specified first. Therefore, Ansible always runs tasks after roles.

This can be quite confusing if the tasks list is defined in the playbook before the roles list because people assume in order execution in Ansible.

Therefore, we SHOULD use pre_tasks and post_tasks to make it more clear when the tasks will be run.

ALL TASKS IN A ROLE SHOULD BE TAGGED WITH THE ROLE NAME

RULE7

@KeithResarhttps://github.com/openshift/openshift-ansible/blob/master/docs/best_practices_guide.adoc#All-tasks-in-a-role-SHOULD-be-tagged-with-the-role-name

# roles/example_role/tasks/main.yml- debug: msg="in example_role" tags: - example_role

ALL TASKS IN A ROLE SHOULD BE TAGGED WITH THE ROLE NAME

RULE7

@KeithResarhttps://github.com/openshift/openshift-ansible/blob/master/docs/best_practices_guide.adoc#All-tasks-in-a-role-SHOULD-be-tagged-with-the-role-name

Ansible tasks can be tagged, and then these tags can be used to either run or skip the tagged tasks using the --tags and --skip-tags ansible-playbook options respectively.

This is very useful when developing and debugging new tasks. It can also significantly speed up playbook runs if the user specifies only the roles that changed.

THE ANSIBLE ROLES DIRECTORY MUST MAINTAIN A FLAT STRUCTURE

RULE8

@KeithResarhttps://github.com/openshift/openshift-ansible/blob/master/docs/best_practices_guide.adoc#The-Ansible-roles-directory-MUST-maintain-a-flat-structure

production # inventory file for production serversstaging # inventory file for staging environment

group_vars/host_vars/

site.yml # master playbookwebservers.yml # playbook for webserver tierdbservers.yml # playbook for dbserver tier

roles/ common/ # this hierarchy represents a "role" tasks/, handlers/, templates/, files/, vars/, defaults/, meta/

THE ANSIBLE ROLES DIRECTORY MUST MAINTAIN A FLAT STRUCTURE

RULE8

@KeithResarhttps://github.com/openshift/openshift-ansible/blob/master/docs/best_practices_guide.adoc#The-Ansible-roles-directory-MUST-maintain-a-flat-structure

The purpose of this rule is to:

● Comply with the upstream best practices● Make it familiar for new contributors● Make it compatible with Ansible Galaxy

ANSIBLE ROLES SHOULD BE NAMED TECH_COMPONENT[_SUBCOMPONENT]

RULE9

@KeithResarhttps://github.com/openshift/openshift-ansible/blob/master/docs/best_practices_guide.adoc#Ansible-Roles-SHOULD-be-named-like-technology_component_subcomponent

roles/

# this hierarchy represents a "role" common/

# ✘ BAD database/

# ✔ GOOD mysql_slave/

ANSIBLE ROLES SHOULD BE NAMED TECH_COMPONENT[_SUBCOMPONENT]

RULE9

@KeithResarhttps://github.com/openshift/openshift-ansible/blob/master/docs/best_practices_guide.adoc#Ansible-Roles-SHOULD-be-named-like-technology_component_subcomponent

For consistency, role names SHOULD follow the above naming pattern. It is important to note that this is a recommendation for role naming, and follows the pattern used by upstream.

Many times the technology portion of the pattern will line up with a package name. It is advised that whenever possible, the package name should be used.

THE DEFAULT FILTER SHOULD REPLACE EMPTY STRINGS, LISTS, ETC

RULE10

@KeithResarhttps://github.com/openshift/openshift-ansible/blob/master/docs/best_practices_guide.adoc#The-default-filter-SHOULD-replace-empty-strings-lists-etc

- hosts: localhost gather_facts: no vars: somevar: '' tasks: - debug: var=somevar

# ✘ BAD - name: "Will output 'somevar: []'" debug: "msg='somevar: [{{ somevar | default('empty str') }}]'"

# ✔ GOOD - name: "Will output 'somevar: [the string was empty]'" debug: "msg='somevar: [{{ somevar | default('empty str', true)}}]'"

THE DEFAULT FILTER SHOULD REPLACE EMPTY STRINGS, LISTS, ETC

RULE10

@KeithResarhttps://github.com/openshift/openshift-ansible/blob/master/docs/best_practices_guide.adoc#The-default-filter-SHOULD-replace-empty-strings-lists-etc

When using the jinja2 default filter, unless the variable is a boolean, specify true as the second parameter. This will cause the default filter to replace empty strings, lists, etc with the provided default rather than only undefined variables.

This is because it is preferable to either have a sane default set than to have an empty string, list, etc. For example, it is preferable to have a config value set to a sane default than to have it simply set as an empty string.

AUTOMATION FOR EVERYONE

ANSIBLE IS DESIGNED AROUND THE WAY PEOPLE WORK AND THE WAY PEOPLE WORK TOGETHER.

RESOURCES

OPENSHIFT ORIGINhttps://www.openshift.org

OPENSHIFT ANSIBLE BEST PRACTICEShttps://github.com/../docs/best_practices_guide

ANSIBLE MINNEAPOLIS MEETUPhttps://www.meetup.com/Ansible-Minneapolis/

@KeithResar

@KeithResar

THANKS!