ANSIBLE BEST PRACTICES: THE ESSENTIALS

Timothy Appnel
Senior Product Manager, Ansible

GitHub: tima
Twitter: appnelgroup
 THE ANSIBLE WAY

2
 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.

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

4
 Principal 3
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.

5
WORKFLOW

Treat your Ansible content like code

● Version control your Ansible content

● Start as simple as possible and iterate
○ Start with a basic playbook and static inventory
○ Refactor and modularize later

6
WORKFLOW

Do It with Style

● Create a style guide for developers

● Consistency in:
○ Tagging
○ Whitespace
○ Naming of Tasks, Plays, Variables, and Roles
○ Directory Layouts
● Enforce the style

7
PROJECT LAYOUTS: BASIC

basic-project
├── inventory
│ ├── group_vars
│ │ └── web.yml
│ ├── host_vars
│ │ └── db1.yml
│ └── hosts
└── site.yml

8
PROJECT LAYOUTS: ORGANIZATIONAL ROLES

myapp
├── roles
│ ├── myapp
│ │ ├── tasks
│ │ │ └── main.yml
│ │ └── ...
│ ├── nginx
│ │ └── ...
│ └── proxy
│ └── ...
└── site.yml

9
 PROJECT LAYOUTS: SHARED ROLES

myapp
├── config.yml
├── provision.yml
├── roles
│ └── requirements.yml
└── site.yml

10
 INVENTORY

Give inventory nodes human-meaningful

EXHIBIT A EXHIBIT B
10.1.2.75 db1 ansible_host=10.1.2.75
10.1.5.45 db2 ansible_host=10.1.5.45
10.1.4.5 db3 ansible_host=10.1.4.5
10.1.0.40 db4 ansible_host=10.1.0.40

w14301.example.com web1 ansible_host=w14301.example.com

w17802.example.com web2 ansible_host=w17802.example.com
w19203.example.com web3 ansible_host=w19203.example.com
w19304.example.com web4 ansible_host=w19203.example.com

11
 INVENTORY

Group hosts for easier inventory selection and less

conditional tasks -- the more groups the better.
WHAT WHERE WHEN

[db] [east] [dev]

db[1:4] db1 db1
web1 web1
[web] db3
web[1:4] web3 [test]
db3
[west] web3
db2
web2 [prod]
db4 db2
db1 = db, east, dev web4 web2
db4
12 web4
 INVENTORY

Use a single source of truth if you have it -- even if you have

multiple sources, Ansible can unify them.

● Stay in sync automatically

● Reduce human error

CMDB

PUBLIC / PRIVATE
CLOUD

13
 VARIABLES

Proper variable naming can make plays more readable and

avoid variable name conflicts

● Use descriptive, unique human-meaningful variable names

● Prefix role variables with its “owner” such as a role name or
package
apache_max_keepalive: 25
apache_port: 80
tomcat_port: 8080

14
 VARIABLES

Make the most of variables

● Find the appropriate place for your variables based on what,

where and when they are set or modified
● Separate logic (tasks) from variables to reduce repetitive
patterns and provided added flexibility.

15
 SEPARATE LOGIC FROM VARIABLES

- name: Clone student lesson app for a user

host: nodes
tasks:
EXHIBIT A
- name: Create ssh dir
file:
state: directory
path: /home/{{ username }}/.ssh
● Embedded parameter
- name: Set Deployment Key
copy:
values and repetitive home
src: files/deploy_key directory value pattern in
dest: /home/{{ username }}/.ssh/id_rsa
multiple places
- name: Clone repo
git: ● Works but could be more
accept_hostkey: yes
clone: yes clearer and setup to be
dest: /home/{{ username }}/exampleapp
key_file: /home/{{ username }}/.ssh/id_rsa more flexible and
repo: git@github.com:example/apprepo.git
maintainable

16
 SEPARATE LOGIC FROM VARIABLES

- name: Clone student lesson app for a user

host: nodes
vars:
EXHIBIT B
user_home_dir: /home/{{ username }}
user_ssh_dir: "{{ user_home_dir }}/.ssh"
deploy_key: "{{ user_ssh_dir }}/id_rsa"
app_dir: "{{ user_home_dir }}/exampleapp"
tasks:
● Parameters values are set
- name: Create ssh dir
file:
thru values away from the
state: directory task and can be overridden.
path: "{{ user_ssh_dir }}"

- name: Set Deployment Key

● Human meaningful
copy: variables “document” what’s
src: files/deploy_key
dest: "{{ deploy_key }}" getting plugged into a task
- name: Clone repo parameter
git:
dest: "{{ app_dir }}" ● More easily refactored into
key_file: "{{ deploy_key }}"
repo: git@github.com:example/exampleapp.git a role
accept_hostkey: yes
clone: yes
17
 PLAYS & TASKS

Use native YAML syntax to maximize the readability of your

plays

● Vertical reading is easier

● Supports complex parameter values
● Works better with editor syntax highlighting in editors

18
 USE NATIVE YAML SYNTAX

NO!

- name: install telegraf

yum: name=telegraf-{{ telegraf_version }} state=present update_cache=yes disabl
notify: restart telegraf

- name: configure telegraf

template: src=telegraf.conf.j2 dest=/etc/telegraf/telegraf.conf

- name: start telegraf

service: name=telegraf state=started enabled=yes

19
 USE NATIVE YAML SYNTAX

Better, but no

- name: install telegraf

yum: >
name=telegraf-{{ telegraf_version }}
state=present
update_cache=yes
disable_gpg_check=yes
enablerepo=telegraf
notify: restart telegraf

- name: configure telegraf

template: src=telegraf.conf.j2 dest=/etc/telegraf/telegraf.conf

- name: start telegraf

service: name=telegraf state=started enabled=yes

20
 USE NATIVE YAML SYNTAX

Yes!
- name: install telegraf
yum:
name: telegraf-{{ telegraf_version }}
state: present
update_cache: yes
disable_gpg_check: yes
enablerepo: telegraf
notify: restart telegraf

- name: configure telegraf

template:
src: telegraf.conf.j2
dest: /etc/telegraf/telegraf.conf
notify: restart telegraf

- name: start telegraf

service:
name: telegraf
state: started
enabled: yes
21
 PLAYS & TASKS

Names improve readability and user feedback

● Give all your playbooks, tasks and blocks brief, reasonably

unique and human-meaningful names

22
 PLAYS & TASKS

EXHIBIT A
- hosts: web PLAY [web]
tasks: ********************************
- yum:
name: httpd TASK [setup]
state: latest ********************************
ok: [web1]

- service: TASK [yum]

name: httpd ********************************
state: started ok: [web1]
enabled: yes
TASK [service]
********************************
ok: [web1]

23
 PLAYS & TASKS

EXHIBIT B
PLAY [install and start apache]
- hosts: web
********************************
name: install and start apache
tasks:
TASK [setup]
- name: install apache packages
********************************
yum:
ok: [web1]
name: httpd
state: latest
TASK [install apache packages]
********************************
- name: start apache service
ok: [web1]
service:
name: httpd
TASK [start apache service]
state: started
********************************
enabled: yes
ok: [web1]

24
 PLAYS & TASKS

Focus avoids complexity

● Keep plays and playbooks focused. Multiple simple ones are

better than having a huge single playbook full of conditionals
● Follow Linux principle of do one thing, and one thing well

25
 PLAYS & TASKS

Clean up your debugging tasks

● Make them optional with the verbosity parameter so they’re

only displayed when they are wanted.

- debug:
msg: "This always displays"

- debug:
msg: "This only displays with ansible-playbook -vv+"
verbosity: 2

26
 PLAYS & TASKS

Don’t just start services -- use smoke tests

- name: check for proper response

uri:
url: http://localhost/myapp
return_content: yes
register: result
until: '"Hello World" in result.content'
retries: 10
delay: 1

27
 PLAYS & TASKS

Use command modules sparingly

● Use the run command modules like shell and command as a

last resort
● The command module is generally safer
● The shell module should only be used for I/O redirect

28
 PLAYS & TASKS

Always seek out a module first

- name: add user - name: add user

command: useradd appuser user:
name: appuser
- name: install apache state: present
command: yum install httpd
- name: install apache
- name: start apache yum:
shell: | name: httpd
service httpd start && chkconfig httpd on state: latest

- name: start apache

service:
name: httpd
state: started
enabled: yes

29
 PLAYS & TASKS

Still using command modules a lot?

- hosts: all
vars:
cert_store: /etc/mycerts
cert_name: my cert
tasks:
- name: check cert
shell: certify --list --name={{ cert_name }} --cert_store={{ cert_store }} | grep "{{ cert_name }}"
register: output

- name: create cert

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

- name: sign cert

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

30
 PLAYS & TASKS

Develop your own module

- hosts: all ● Understandable by

vars:
cert_store: /etc/mycerts non-technical people
cert_name: my cert
● CRUD (Create, read, update
tasks:
- name: create and sign cert and delete)
certify:
state: present
sign: yes
user: chris
name: "{{ cert_name }}"
cert_store: "{{ cert_store }}"

31
 PLAYS & TASKS

Separate provisioning from deployment and configuration

tasks

acme_corp/
├── configure.yml
├── provision.yml
└── site.yml

$ cat site.yml
---
- import_playbook: provision.yml
- import_playbook: configure.yml

32
 TEMPLATES

Jinja2 is powerful but you needn't use all of it

● Templates should be simple:

○ Variable substitution
○ Conditionals
○ Simple control structures/iterations
○ Design your templates for your use case, not the world's
● Things to avoid:
○ Anything that can be done directly in Ansible
○ Managing variables in a template
○ Extensive and intricate conditionals
○ Conditional logic based on embedded hostnames
○ Complex nested iterations
33
 TEMPLATES

Careful when mixing manual and automated configuration

● Label template output files as being generated by Ansible

{{ ansible_managed | comment }}

34
 ROLES

● Like playbooks -- keep roles purpose and function focused

● Use a roles/ subdirectory for roles developed for
organizational clarity in a single project
● Follow the Ansible Galaxy pattern for roles that are to be
shared beyond a single project
● Limit role dependencies

35
 ROLES

● Use ansible-galaxy init to start your roles...

● ...then remove unneeded directories and stub files
● Use ansible-galaxy to install your roles -- even private ones
● Use a roles files (i.e. requirements.yml) to manifest any
external roles your project is using
● Always peg a role to a specific version such as a tag or commit

36
 SCALING YOUR ANSIBLE WORKFLOW

Command line tools have their limitations

● Coordination across a distributed teams & organization…

● Controlling access to credentials...
● Track, audit and report automation and management activity...
● Provide self-service or delegation…
● Integrate automation with enterprise systems...

37
 Thank you

Complexity Kills Productivity

Optimize For Readability
Think Declaratively

38