# 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: ```yaml # 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: ```yaml # 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: ```yaml # 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: ```yaml - 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: ```yaml --- - 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: ```yaml - name : start service service: name : my_service state : started ``` ✅ GOOD: ```yaml - 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: ```yaml - name: Create directory ansible.builtin.file: path=/opt/app state=directory mode=0755 ``` ✅ GOOD: ```yaml - name: Create directory ansible.builtin.file: path: /opt/app state: directory mode: '0755' # Quote octal modes ``` - **Booleans:** Standardize on `true`/`false`. ❌ BAD: ```yaml - name: Enable service ansible.builtin.service: name=my_service enabled=yes become: True ``` ✅ GOOD: ```yaml - name: Enable service ansible.builtin.service: name=my_service enabled=true become: true ```
## 3. Naming Conventions
**Adopt consistent `snake_case` naming.** This applies to variables, tasks, files, and role names. Prefix role names with the collection namespace to prevent collisions.
- **Variables, Tasks, Files:** ❌ BAD: ```yaml # vars/main.yml myVariable: "value" My_Task_Name: "Install Software" ``` ✅ GOOD: ```yaml # vars/main.yml my_variable: "value" # tasks/install_software.yml - name: Install software ansible.builtin.apt: name=software state=present ``` - **Role Names:** ✅ GOOD: `my_namespace.my_collection.webserver`
## 4. Idempotency and Declarative Style
**Write idempotent tasks.** Running a playbook multiple times should yield the same result without unintended side effects. Favor declarative modules over imperative `command` or `shell`.
- **Declarative Modules:** ❌ BAD: ```yaml - name: Check if file exists and create if not ansible.builtin.shell: | if [ ! -f /etc/myapp.conf ]; then cp /etc/myapp.conf.template /etc/myapp.conf fi args: creates: /etc/myapp.conf # Still imperative logic ``` ✅ GOOD: ```yaml - name: Ensure myapp.conf exists ansible.builtin.copy: src: myapp.conf.template dest: /etc/myapp.conf owner: root group: root mode: '0644' backup: true # Idempotent file management ``` - **Atomic File Operations:** Always use `atomic_move` (implicitly via `copy`, `template` modules) for file modifications to prevent data corruption.
## 5. Configuration Management
**Manage configurations with templates and structured variables.**
- **Templates:** Use Jinja2 templates (`template` module) for dynamic configuration files. - **Variables:** Define role variables in `defaults/main.yml` (overridable) and `vars/main.yml` (not overridable by inventory/extra-vars). Prefer inventory variables for host-specific data. ❌ BAD: ```yaml # playbook.yml - hosts: webservers vars: nginx_port: 8080 # Hardcoded in playbook tasks: - name: Configure Nginx ansible.builtin.template: src=nginx.conf.j2 dest=/etc/nginx/nginx.conf ``` ✅ GOOD: ```yaml # roles/nginx/defaults/main.yml nginx_port: 80 # Default port
# inventory/group_vars/webservers.yml nginx_port: 8080 # Override default for webservers group
# roles/nginx/templates/nginx.conf.j2 listen {{ nginx_port }}; ```
## 6. Performance Considerations
**Optimize playbook execution for speed.**
- **Fact Gathering:** Disable fact gathering (`gather_facts: false`) if not explicitly needed. Use `setup` or `ansible.builtin.gather_facts` module selectively. ❌ BAD: ```yaml - hosts: all # gather_facts: true by default, even if not used tasks: - name: Ping all hosts ansible.builtin.ping: ``` ✅ GOOD: ```yaml - hosts: all gather_facts: false # No facts needed for ping tasks: - name: Ping all hosts ansible.builtin.ping: ``` - **Parallelism:** Leverage Ansible's parallelism by default, but be mindful of resource constraints.
## 7. Error Handling and Logging
**Implement robust error handling and informative logging.**
- **Fail Gracefully:** Use `fail_json` (in custom modules) or `ansible.builtin.fail` for clear error messages. Avoid raw tracebacks. ✅ GOOD: ```yaml - name: Ensure critical variable is defined ansible.builtin.fail: msg: "Required variable 'app_version' is not defined." when: app_version is not defined ``` - **Debug Verbosity:** Use the `ansible.builtin.debug` module with verbosity levels for controlled output. ✅ GOOD: ```yaml - name: Show debug info ansible.builtin.debug: var: my_variable when: ansible_verbosity >= 2 # Only show with -vv or higher ```
## 8. Testing and Linting
**Integrate linting and testing into your development workflow.**
- **Ansible Lint:** Run `ansible-lint` on every pull request. It enforces the official style guide and detects common issues. - **Ansible Test:** Use `ansible-test` for unit and integration testing of custom modules and roles. ✅ GOOD: ```bash # In your CI pipeline or pre-commit hook ansible-lint . ansible-test sanity --test flake8 --test ansible-doc --test pep8 # For custom modules ```
## 9. CI/CD Integration
**Embed Ansible into your automated CI/CD pipelines.**
- **Git Triggers:** Trigger playbook runs on Git pushes to automatically provision or update infrastructure. - **Collections:** Store reusable roles and modules in Ansible Collections (Galaxy or private registries) for easy dependency management. - **Pipeline Checks:** Include `ansible-lint` and collection dependency checks in your CI pipeline. ✅ GOOD: ```yaml # .github/workflows/ansible.yml name: Ansible CI/CD
on: [push, pull_request]
jobs: lint: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Install Ansible and dependencies run: pip install ansible ansible-lint - name: Run Ansible Lint run: ansible-lint .
deploy: runs-on: ubuntu-latest needs: lint if: github.ref == 'refs/heads/main' steps: - uses: actions/checkout@v4 - name: Install Ansible Collections run: ansible-galaxy collection install -r requirements.yml - name: Run Playbook env: ANSIBLE_VAULT_PASSWORD: ${{ secrets.ANSIBLE_VAULT_PASSWORD }} run: ansible-playbook -i inventory/prod.yml site.yml --vault-password-file /dev/stdin ```