Ansible Style Guide

tasks:
 - name: Ensure the packages are installed
   yum:
     name: "{{ item }}"
     state: present
   loop:
     - httpd
     - mod_ssl
     - httpd-tools
     - mariadb-server
     - mariadb
     - php
     - php-mysqlnd

tasks:
 - name: Ensure the packages are installed
   yum:
     state: present
     name:
       - httpd
       - mod_ssl
       - httpd-tools
       - mariadb-server
       - mariadb
       - php
       - php-mysqlnd

PLAY [localhost]
********************************

TASK [include_vars]
********************************
ok: [localhost]

TASK [yum]
********************************
ok: [localhost]

PLAY [Create a new virtual machine]
********************************

TASK [Include vmware-credentials]
********************************
ok: [localhost]

TASK [Install required packages with yum]
********************************
ok: [localhost]

# bad
# set another variable
- set_fact:
    my_second_var: "{{ my_var }}"

# good
- name: set another variable
  set_fact:
    my_second_var: "{{ my_var }}"

#bad
- name: 'Change status'
  service:
    enabled: true
    name: 'httpd'
    state: '{{ state }}'
  become: true

#good
- name: 'Change status of httpd to {{ state }}'
  service:
    enabled: true
    name: 'httpd'
    state: '{{ state }}'
  become: true

# bad
lvm

# good
mycompany-setup-lvm

# bad
- name: install httpd
  tasks:
    - command: "yum install httpd"

# good
- name: install packages
  tasks:
    - name: 'install httpd'
      yum:
        name: 'httpd'
        state: 'present'

#bad
- name: 'Change httpd status'
  service:
    enabled: true
    name: 'httpd'
    state: '{{ state }}'
  become: true

#good
# Example usage: ansible-playbook -e state=started playbook.yml
# This playbook changes the state of the httpd daemon

---

- name: 'Change httpd status'
  service:
    enabled: true
    name: 'httpd'
    state: '{{ state }}'
  become: true

# bad
- name: 'start robot named my-robot'
  service:
    name: my-robot
    state: started
    enabled: true
  become: true

# good
- name: 'start robot named my-robot'
  service:
    name: 'my-robot'
    state: 'started'
    enabled: true
  become: true

# double quotes w/ nested single quotes
- name: 'start all robots'
  service:
    name: '{{ item["robot_name"] }}'
    state: 'started'
    enabled: true
  with_items: '{{ robots }}'
  become: true

# double quotes to escape characters
- name 'print some text on two lines'
  debug:
    msg: "This text is on\ntwo lines"

# folded scalar style
- name: 'robot infos'
  debug:
    msg: >
      Robot {{ item['robot_name'] }} is {{ item['status'] }} and in {{ item['az'] }}
      availability zone with a {{ item['curiosity_quotient'] }} curiosity quotient.
  with_items: robots

# folded scalar when the string has nested quotes already
- name: 'print some text'
  debug:
    msg: >
      "I haven't the slightest idea," said the Hatter.

# do not quote booleans/numbers
- name: 'download google homepage'
  get_url:
    dest: '/tmp'
    timeout: 60
    url: 'https://google.com'
    validate_certs: true

# variables example 1
- name: 'set a variable'
  set_fact:
    my_var: 'test'

# variables example 2
- name: 'print my_var'
  debug:
    var: my_var
  when: ansible_os_family == 'Darwin'

# variables example 3
- name: 'set another variable'
  set_fact:
    my_second_var: '{{ my_var }}'

#bad
- name: 'template client.json to /etc/sensu/conf.d/'
  template:
    dest: '/etc/sensu/conf.d/client.json'
    src: 'client.json.j2'
  sudo: true

# good
- name: 'template client.json to /etc/sensu/conf.d/'
  template:
    dest: '/etc/sensu/conf.d/client.json'
    src: 'client.json.j2'
  become: true

# example
- hosts: 'webservers'
  remote_user: 'centos'
  vars:
    tomcat_state: 'started'
  pre_tasks:
    - name: 'set the timezone to America/Boise'
      lineinfile:
        dest: '/etc/environment'
        line: 'TZ=America/Boise'
        state: 'present'
      become: true
  roles:
    - { role: 'tomcat', tags: 'tomcat' }
  tasks:
    - name: 'start the tomcat service'
      service:
        name: 'tomcat'
        state: '{{ tomcat_state }}'

# example
- name: 'create some ec2 instances'
  tags: 'ec2'
  ec2:
    assign_public_ip: true
    image: 'ami-c7d092f7'
    instance_tags:
      Name: '{{ item }}'
    key_name: 'my_key'
  with_items: '{{ instance_names }}'
  ignore_errors: true
  register: ec2_output
  when: ansible_os_family == 'Darwin'

# bad
- include: other_file.yml

- include: 'second_file.yml'

- include: third_file.yml tags=third

# good

- include: 'other_file.yml'
- include: 'second_file.yml'

- include: 'third_file.yml'
  tags: 'third'

# bad
- name: 'start httpd'
  service:
    name: 'httpd'
    state: 'restarted'
    enabled: 1
  become: 'yes'

# good
- name: 'start httpd'
  service:
    name: 'httpd'
    state: 'restarted'
    enabled: true
  become: true

# bad
- name : 'start httpd'
  service:
    name    : 'httpd'
    state   : 'restarted'
    enabled : true
  become : true

# good
- name: 'start httpd'
  service:
    name: 'httpd'
    state: 'restarted'
    enabled: true
  become: true

# bad
- name: 'create conf.d directory'
  file: 'path=/etc/httpd/conf.d/ state=directory mode=0755 owner=httpd group=httpd'
  become: true

- name: 'copy mod_ssl.conf to /etc/httpd/conf.d'
  copy: 'dest=/etc/httpd/conf.d/ src=mod_ssl.conf'
  become: true

# good
- name: 'create conf.d directory'
  file:
    group: 'httpd'
    mode: '0755'
    owner: 'httpd'
    path: '/etc/httpd/conf.d'
    state: 'directory'
  become: true

- name: 'copy mod_ssl.conf to /etc/httpd/conf.d'
  copy:
    dest: '/etc/httpd/conf.d/'
    src: 'mod_ssl.conf'
  become: true

# Example: ansible-playbook --ask-become-pass --ask-vault-pass style.yml
#
# This is a sample Ansible script to showcase all of our style decisions.
# Pay close attention to things like spacing, where we use quotes, etc.
# The only thing you can ignore is where comments are, except this first comment:
# It's generally a good idea to include some good information like sample usage
# at the beginning of your file, so that someone can run head on the script
# to see what they should do.
#
# A good rule of thumb on quoting is to quote anything that represents a value
# that does not represent either a primitive type, or something within the
# playbook; e.g. do not quote integers, booleans, variable names, boolean logic
# Variable names still need to be quoted when they are module parameters for
# Ansible to properly resolve them.
# You should also always have single quotes around the outer string, and
# double quotes on the inside.
# If for some reason this is not possible or it would require escaping quotes
# (which you should avoid if you can), use the scalar string operator (shown
# in this playbook).
#
# Directory structure style:
# Your directory structure should match the structure described by the Ansible
# developers: http://docs.ansible.com/ansible/playbooks_best_practices.html
#
# ---
#
# - include: 'role_name.yml'
#   become: true # only if every task in the role requires super user
#
# The self-named yml file contains all of the actual role tasks.
#
# Header comments are followed by blank line, then --- to signify start of YAML,
# then another blank line, then the script.

---

- hosts: 'localhost'
  tasks:
    - name: 'fail if someone tries to run this'
      fail:
        msg: 'this playbook was not meant to actually be ran. just inspect the source!'

- include: 'first_include.yml' # quote filenames
- include: 'second_include.yml' # no blank line needed between includes without tags

- include: 'third_include.yml' # includes with tags should have blank lines between
  tags: 'third_include'

- include: 'fourth_include.yml'
  tags: 'fourth_include'

- hosts: 'tag_environment_samplefruit'
  remote_user: 'centos' # options in alphabetical order
  vars:
    sample_str: 'dood' # use snake_case for variable names
    sample_bool: true # do not quote booleans or integers
    sample_int: 42
  vars_files:
    - 'group_vars/secrets.yml'
  pre_tasks: # then pre_tasks, roles, tasks
    - name: 'this runs a command that involves both single and double quotes'
      command: >
        echo "I can't even"
      args:
        chdir: '/tmp'

    - name: 'this command just involves double quotes'
      command: 'echo "Hey man"'
  roles:
    - { role: 'sample_role', tags: 'sample_role' } # use this format for role listing
  tasks:
    - name: 'get list of directory permissions in /tmp'
      command: 'ls -l /tmp'
      register: tmp_listing # do not quote variable names when registering

    # A task should be defined in the following order:
    # name
    # tags
    # module
    # module arguments, alphabetical
    # loop operator (e.g. with_items, with_fileglob)
    # other options, alphabetical (e.g. become, ignore_errors, when)

    - name: 'a more complicated task to show where everything goes: touch all items from /tmp'
      tags: 'debug' # tags go immediately after name
      file:
        path: '{{ item }}' # use path for single file actions, dest/src for multi file actions
        state: 'touch' # arguments go in alphabetical order
      with_items: tmp_listing.stdout_lines # loop things go immediately after module
      # the rest of the task options are in alphabetical order
      become: true # try to keep become only on the tasks that need it. If every task in a host uses become, then move it up to the host options
      ignore_errors: true
      when: ansible_os_family == 'Darwin' and tmp_listing.stdout_lines | length > 1

    - name: 'some modules can have maps in their maps (woah man)'
      ec2:
        assign_public_ip: true
        group: ['wca_ssh', 'wca_tomcat']
        image: 'ami-c7d092f7'
        instance_tags:
          Name: 'instance'
          service_tomcat: ''
        key_name: 'ops'

- hosts: 'tag_environment_secondfruit'
  tasks:
    - name: 'this task has multiple tags'
      tags: ['tagme', 'tagmetoo']
      set_fact:
        mr_fact: 'w'

    - name: 'perform an action'
      action: ec2_facts
      delegate_to: 'localhost'

# newline at end of file

# bad
- name: 'set some facts'
  set_fact:
    myBoolean: true
    int: 20
    MY_STRING: 'test'

# good
- name: 'set some facts'
  set_fact:
    rolename_my_boolean: true
    rolename_my_int: 20
    rolename_my_string: 'test'

# bad
- name: set some facts
  set_fact:
    my_new_var: "{{my_old_var}}"

# good
- name: set some facts
  set_fact:
    my_new_var: "{{ my_old_var }}"

# bad
- name: validate required variables
  fail:
    msg: "No value specified for '{{ item }}'"
  when: (vars[item] is undefined) or (vars[item] is defined and vars[item] | trim == "")

  with_items: "{{ appd_required_variables }}"

- name: Create an user and add to the global group
  include_tasks: user.yml
  when:
  - username is defined
  - username != ""

# good
- name: Validate required variables
  fail:
    msg: "No value specified for '{{ item }}'"
  when: (vars[item] is undefined) or (vars[item] is defined and not vars[item] | trim == "")
  with_items: "{{ appd_required_variables }}"

- name: Create an user and add to the global group
  include_tasks: user.yml
  when:
  - username is defined
  - username

# bad
- name: Send summary mail
  local_action:
    module: mail
    subject: "Summary Mail"
    to: "{{ mail_recipient }}"
    body: "{{ mail_body }}"
  run_once: true

# good
- name: Send summary mail
  mail:
    subject: "Summary Mail"
    to: "{{ mail_recipient }}"
    body: "{{ mail_body }}"
  delegate_to: localhost
  run_once: true

# bad
~/tasks.yaml

# good
~/tasks.yml

# bad
~/template.conf

# good
~/template.conf.j2

# bad
~/secrets.yml

# good
~/secrets.vault

# bad
- name: print my_var
  debug:
    var: my_var
  when: ansible_os_family == "Darwin"

# good
- name: print my_var
  debug:
    var: my_var
    verbosity: 2
  when: ansible_os_family == "Darwin"

- block:
    copy:
      src: critical.conf
      dest: /etc/critical/crit.conf
    service:
      name: critical
      state: restarted
  rescue:
   command: shutdown -h now

    [defaults]
    callback_whitelist = profile_tasks, profile_role, timer

.
├── ansible.cfg
├── ansible_modules
├── group_vars
│   ├── webservers
│   └── all
├── hosts
│   ├── webserver01
│   └── webserver02
├── host_vars
├── modules
├── playbooks
│   └── ansible-cmdb.yml
└── roles
    ├── requirements.yml
    ├── galaxy
        └── dev-sec.ssh-hardening
            └── auditd
        ├── files
        │   ├── auditd.conf
        │   ├── audit.yml
        ├── handlers
        │   └── main.yml
        ├── meta
        │   └── main.yml
        └── tasks
            └── main.yml