ansible

ansible Best Practices

Ansible excels when treated as infrastructure-as-code. These guidelines ensure your playbooks, roles, and modules are consistent, idempotent, and production-ready.

1. Code Organization and Structure

Always structure your Ansible content into roles and collections. Roles encapsulate specific functionalities, while collections group related roles, modules, and plugins, promoting reusability and discoverability.

• Role Scoping: Each role or module must focus on a single, well-defined task. Avoid monolithic roles. ❌ BAD:

  # roles/webserver/tasks/main.yml
  - name: Install Nginx
    ansible.builtin.apt: name=nginx state=present
  - name: Configure Nginx
    ansible.builtin.template: src=nginx.conf.j2 dest=/etc/nginx/nginx.conf
  - name: Start Nginx
    ansible.builtin.service: name=nginx state=started
  - name: Install PHP-FPM
    ansible.builtin.apt: name=php-fpm state=present
  # ... and more
  

  ✅ GOOD:

  # roles/nginx/tasks/main.yml
  - name: Ensure Nginx is installed and configured
    ansible.builtin.include_tasks: setup.yml
  - name: Ensure Nginx service is running
    ansible.builtin.service: name=nginx state=started enabled=true
  
  # roles/php-fpm/tasks/main.yml
  - name: Ensure PHP-FPM is installed and configured
    ansible.builtin.include_tasks: setup.yml
  

• Fact Modules: Create dedicated _info or _facts modules/tasks for gathering information, rather than overloading existing ones. ✅ GOOD:

  # roles/system_facts/tasks/main.yml
  - name: Gather custom system facts
    ansible.builtin.set_fact:
      custom_os_version: "{{ ansible_facts['distribution_major_version'] }}"
  

2. YAML Hygiene and Syntax

Enforce strict YAML formatting. Consistent syntax improves readability and prevents subtle parsing errors.

• File Start: All YAML files must begin with ---.
• Indentation: Use two spaces for indentation, never tabs.
• Quotes: Quote strings only when necessary (e.g., when they contain special characters or Jinja map references). Prefer single quotes. Use double quotes for escaping characters or multi-line strings. ❌ BAD:

  - name: "Install a package"
    ansible.builtin.apt: name="my-package" state="present"
  - name: Set fact
    set_fact:
      myvar: '{{ item["key"] }}' # Incorrect quoting for Jinja map
  

  ✅ GOOD:

  ---
  - name: Install a package
    ansible.builtin.apt:
      name: my-package
      state: present
  - name: Set fact
    ansible.builtin.set_fact:
      my_var: "{{ item['key'] }}" # Double quotes for Jinja map
  - name: Print multi-line message
    ansible.builtin.debug:
      msg: |
        This is line one.
        This is line two.
  

• Colon Spacing: Use exactly one space after a colon in key-value pairs. ❌ BAD:

  - name : start service
    service:
        name    : my_service
        state   : started
  

  ✅ GOOD:

  - name: start service
    ansible.builtin.service:
      name: my_service
      state: started
  

• Structured Map Style: Always use the structured map style for module parameters, not the legacy key=value style. ❌ BAD:

  - name: Create directory
    ansible.builtin.file: path=/opt/app state=directory mode=0755
  

  ✅ GOOD:

  - name: Create directory
    ansible.builtin.file:
      path: /opt/app
      state: directory
      mode: '0755' # Quote octal modes
  

• Booleans: Standardize on true/false. ❌ BAD:

  - name: Enable service
    ansible.builtin.service: name=my_service enabled=yes
    become: True
  

  ✅ GOOD:

  - name: Enable service
    ansible.builtin.service: name=my_service enabled=true
    become: true