ansible

Best Practices

• CRITICAL: In role task files (roles/*/tasks/main.yml), write ONLY the task list — NO play-level keys (hosts, become, etc.). Correct role task file: '---\n- name: Install nginx\n ansible.builtin.apt:\n name: nginx\n state: present'. WRONG role task file: '---\n- hosts: all\n tasks:\n - name: Install nginx' — role tasks are NOT plays.
• CRITICAL: Modules go INSIDE tasks: list, NEVER at the play level. Correct play: '- hosts: all\n tasks:\n - name: Install nginx\n ansible.builtin.apt:\n name: nginx'. WRONG: '- hosts: all\n ansible.builtin.apt:\n name: nginx' — this causes 'not a valid attribute for a Play' error.
• Use handlers for service restarts triggered by configuration changes (notify + handler)
• Group related tasks with blocks and meaningful names
• Use variables for environment-specific values, with defaults in defaults/main.yml
• Prefer modules over raw/shell commands (e.g., ansible.builtin.apt over shell: apt-get)
• Use become (sudo) only when necessary and specify become_user explicitly
• Include tags for selective task execution (install, configure, deploy, security)
• Use ansible-vault for sensitive data references (passwords, keys, tokens)
• Each task must have a descriptive name starting with a verb (Install, Configure, Ensure)