Skip to content

Latest commit

 

History

History
222 lines (193 loc) · 4.27 KB

ROLE_DEVELOPMENT_GUIDELINES.adoc

File metadata and controls

222 lines (193 loc) · 4.27 KB
Raw

JonasPammer’s Ansible Role Development Guidelines

💡
 For an overview of General Ansible Role Development Practices, take a look at my Ansible Role Development (Best) Practices document.
Table of Contents

Naming Variables

Type Format Examples

defaults

[role name]_[var name]

 
apache_listen_ip: "*"

vars

[role name]__[var name]

 
apache__vhosts_version: "2.2"

register

[role name]__register_[module name]_[var name]

 
- name: stat if apache's default DocumentRoot contains a favicon at its root
  ansible.builtin.stat:
    path: /var/www/html/favicon.ico
  register: apache2__register_stat_favicon

Naming Tasks

  • Use a fully qualified collection names (FQCNs), as per Ansible’s 2.10 Recommendation.

    Without FQCNs With FQCNs (Ansible 2.10+ recommendation) 
    - name: check if all variables have been set correctly
  import_tasks: assert.yml
    - name: install mpdf using composer
  composer: …
    		 
    - name: check if all variables have been set correctly
  ansible.builtin.import_tasks: assert.yml
    - name: install mpdf using composer
  community.general.composer: …

  • Tasks that do not actually do anything to the system should start lowercase and not end with a dot.

    Examples of important Tasks 
    - name: Ensure Apache service is started and enabled on boot.
  service:
    name: "{{ apache__service }}"
    state: started
    enabled: true
    - name: Include Tasks for installing Apache by using the system package manager (when configured).
  ansible.builtin.include_tasks: "install-{{ ansible_os_family }}.yml"
  when: apache2_install_method in ["system", "package"]
    Examples of unimportant Tasks 
    - name: include os-specific vars
  ansible.builtin.include_vars: "{{ ansible_os_family }}.yml"
    - name: check if all variables have been set correctly
  ansible.builtin.import_tasks: assert.yml
  run_once: true
  delegate_to: localhost
    - name: set 'apache_packages' to OS-dependant value (when not already defined)
  ansible.builtin.set_fact:
    apache_packages: "{{ __apache_packages | list }}"
  when: apache_packages is not defined
    - name: test if 'apache_packages' is set correctly
  ansible.builtin.assert:
    that:
      - apache_packages is defined
      - apache_packages is string or apache_packages is iterable
    quiet: true

  • Use "Ensure" sparingly. Start with the Action.

    Instead of… Use… 
    - name: Ensure Apache2 packages are installed.
  ansible.builtin.apt:
    name: "{{ apache_packages }}"
    state: present
    		 
    - name: Install Apache2 packages.
  ansible.builtin.apt:
    name: "{{ apache_packages }}"
    state: present
    		 
    - name: Ensure mediawiki destination directory exists.
  ansible.builtin.file:
    path: "{{ mediawiki_destination }}"
    state: directory
    		 
    - name: Create mediawiki destination directory.
  ansible.builtin.file:
    path: "{{ mediawiki_destination }}"
    state: directory
    Completely valid usages of "Ensure" 
    - name: Ensure Apache service is started and enabled on boot.
  service:
    name: "{{ apache__service }}"
    state: started
    enabled: true
    		 
    - name: Create PHP configuration directories and ensure correct mode.
  ansible.builtin.file:
    path: "{{ item }}"
    state: directory
    follow: true
    mode: u=rwx,g=rx,o=rx
  loop: "{{ php_conf_paths }}"