Ansible Block And Handlers

Last updated: June 30, 2025

My Journey with Blocks and Handlers in Ansible

When I first started writing Ansible playbooks, I created simple, sequential tasks that ran one after another. As my infrastructure grew more complex, I found myself repeating error-handling patterns and creating redundant notification systems for service restarts. That's when I discovered the power of Ansible blocks and handlers.

Learning to use blocks transformed how I structure my playbooks. Instead of scattering error handling across tasks, I could group related tasks and handle exceptions in a cleaner, more Python-like way. And with handlers, I could eliminate redundant service restarts, ensuring that services only restarted once, no matter how many configuration changes were made.

In this blog post, I'll share my experiences with Ansible blocks and handlers, providing practical examples for both Linux and Windows environments. These features have significantly improved the reliability and efficiency of my automation code, and I believe they can do the same for yours.

Understanding Blocks in Ansible

Blocks in Ansible allow you to group related tasks together and apply common parameters to them. They're especially useful for error handling and applying conditional logic to multiple tasks at once.

Think of blocks as similar to the try/except/finally structure in Python:

• block section = try section (main tasks to execute)

• rescue section = except section (tasks to run if the block fails)

• always section = finally section (tasks to run regardless of success or failure)

Here's a comparison table to visualize the relationship:

Python	Ansible Block
try	block
except	rescue
finally	always

Basic Block Usage

Let's start with a simple example. Here's how you can group related tasks in a block:

---
- name: Configure web server
  hosts: web_servers
  tasks:
    - name: Web server configuration
      block:
        - name: Install Apache
          ansible.builtin.package:
            name: "{{ apache_package }}"
            state: present

        - name: Copy configuration file
          ansible.builtin.template:
            src: httpd.conf.j2
            dest: "{{ apache_config_path }}"

        - name: Ensure Apache is running
          ansible.builtin.service:
            name: "{{ apache_service }}"
            state: started
            enabled: yes
      vars:
        apache_package: "{{ 'httpd' if ansible_facts['os_family'] == 'RedHat' else 'apache2' }}"
        apache_config_path: "{{ '/etc/httpd/conf/httpd.conf' if ansible_facts['os_family'] == 'RedHat' else '/etc/apache2/apache2.conf' }}"
        apache_service: "{{ 'httpd' if ansible_facts['os_family'] == 'RedHat' else 'apache2' }}"

In this example, all tasks within the block share common variables that determine the appropriate package, configuration path, and service name based on the operating system.

Blocks with Conditionals

One of the most powerful features of blocks is the ability to apply conditionals to an entire group of tasks:

---
- name: Operating system specific configurations
  hosts: all
  tasks:
    - name: Linux specific configurations
      block:
        - name: Install Linux tools
          ansible.builtin.package:
            name:
              - vim
              - htop
              - tmux
            state: present

        - name: Set Linux kernel parameters
          ansible.builtin.sysctl:
            name: net.ipv4.ip_forward
            value: '1'
            sysctl_set: yes
      when: ansible_facts['os_family'] != 'Windows'

    - name: Windows specific configurations
      block:
        - name: Install Windows features
          win_feature:
            name:
              - Web-Server
              - Web-Mgmt-Tools
            state: present

        - name: Configure Windows Firewall
          win_firewall_rule:
            name: Allow HTTP
            localport: 80
            action: allow
            direction: in
            protocol: tcp
            state: present
      when: ansible_facts['os_family'] == 'Windows'

This playbook applies different configurations based on whether the target system is running Linux or Windows, using blocks to group the OS-specific tasks.

Error Handling with Blocks

Blocks really shine when it comes to error handling. Here's an example that demonstrates how to use the rescue and always sections:

---
- name: Database backup with error handling
  hosts: database_servers
  tasks:
    - name: Database backup process
      block:
        - name: Stop the database
          ansible.builtin.service:
            name: postgresql
            state: stopped

        - name: Backup database files
          ansible.builtin.command: tar -czf /backup/db_backup.tar.gz /var/lib/postgresql/data
          args:
            creates: /backup/db_backup.tar.gz

        - name: Start the database
          ansible.builtin.service:
            name: postgresql
            state: started
      rescue:
        - name: Ensure database is running if backup failed
          ansible.builtin.service:
            name: postgresql
            state: started

        - name: Send failure notification
          ansible.builtin.mail:
            subject: Database backup failed
            to: [email protected]
            body: The database backup process failed. Please check the server.
      always:
        - name: Cleanup temporary files
          ansible.builtin.file:
            path: /tmp/backup_temp
            state: absent

        - name: Log backup attempt
          ansible.builtin.shell: echo "Backup attempted at $(date)" >> /var/log/db_backup_history.log

In this example:

1. The block section attempts to stop the database, create a backup, and restart the database.

2. If any task in the block fails, the rescue section ensures the database is running again and sends a notification.

3. The always section runs regardless of success or failure, cleaning up temporary files and logging the attempt.

Windows Error Handling Example

Here's a similar example for Windows environments:

---
- name: Windows service deployment with error handling
  hosts: windows_servers
  tasks:
    - name: Deploy Windows service
      block:
        - name: Stop the service
          win_service:
            name: MyWindowsService
            state: stopped

        - name: Copy new service executable
          win_copy:
            src: files/MyWindowsService.exe
            dest: C:\Services\MyWindowsService.exe

        - name: Start the service
          win_service:
            name: MyWindowsService
            state: started
      rescue:
        - name: Restore previous version if deployment fails
          win_copy:
            src: files/MyWindowsService.exe.bak
            dest: C:\Services\MyWindowsService.exe
            remote_src: yes

        - name: Ensure service is running
          win_service:
            name: MyWindowsService
            state: started

        - name: Log failure in Windows Event Log
          win_shell: |
            Write-EventLog -LogName Application -Source "Ansible" -EventID 3001 -EntryType Error -Message "Service deployment failed, restored previous version"
      always:
        - name: Update deployment log
          win_shell: |
            Add-Content -Path C:\Logs\deployment_history.log -Value "Deployment attempted at $(Get-Date)"

Accessing Error Information

When using the rescue section, you can access information about the failed task using special variables:

---
- name: Demo accessing error information
  hosts: all
  tasks:
    - name: Task with error handling
      block:
        - name: Attempt a task that might fail
          ansible.builtin.command: /usr/bin/some_command
          register: command_result
      rescue:
        - name: Display information about the failure
          ansible.builtin.debug:
            msg: "Failed task name: {{ ansible_failed_task.name }}. Error was: {{ ansible_failed_result }}"

        - name: Take different actions based on the error
          ansible.builtin.debug:
            msg: "Taking corrective action"
          when: "'permission denied' in ansible_failed_result.stderr"

Understanding Handlers in Ansible

Handlers are special tasks that only run when notified by other tasks. They are particularly useful for operations that should only occur once, regardless of how many tasks might trigger them, such as restarting a service after multiple configuration changes.

Handlers have two key characteristics:

1. They only run when explicitly notified by a task using the notify directive

2. They run only once at the end of a play, even if notified multiple times

Basic Handler Usage

Here's a simple example showing how handlers work:

---
- name: Configure Apache with handlers
  hosts: web_servers
  tasks:
    - name: Install Apache
      ansible.builtin.package:
        name: "{{ 'httpd' if ansible_facts['os_family'] == 'RedHat' else 'apache2' }}"
        state: present

    - name: Copy Apache configuration
      ansible.builtin.template:
        src: httpd.conf.j2
        dest: "{{ '/etc/httpd/conf/httpd.conf' if ansible_facts['os_family'] == 'RedHat' else '/etc/apache2/apache2.conf' }}"
      notify: Restart Apache

    - name: Copy virtual host configuration
      ansible.builtin.template:
        src: vhost.conf.j2
        dest: "{{ '/etc/httpd/conf.d/vhost.conf' if ansible_facts['os_family'] == 'RedHat' else '/etc/apache2/sites-available/vhost.conf' }}"
      notify: Restart Apache

  handlers:
    - name: Restart Apache
      ansible.builtin.service:
        name: "{{ 'httpd' if ansible_facts['os_family'] == 'RedHat' else 'apache2' }}"
        state: restarted

In this playbook:

1. We have two tasks that modify Apache configuration files

2. Both tasks notify the "Restart Apache" handler if they make changes

3. The handler will only run once at the end of the play, even though it might be notified twice

Windows Handlers Example

Handlers work the same way on Windows:

---
- name: Configure IIS with handlers
  hosts: windows_web_servers
  tasks:
    - name: Install IIS
      win_feature:
        name: Web-Server
        state: present
      notify: Restart IIS

    - name: Copy web.config
      win_template:
        src: web.config.j2
        dest: C:\inetpub\wwwroot\web.config
      notify: Restart IIS

    - name: Copy application files
      win_copy:
        src: app_files/
        dest: C:\inetpub\wwwroot\
      notify: Refresh Application Pool

  handlers:
    - name: Restart IIS
      win_service:
        name: W3SVC
        state: restarted

    - name: Refresh Application Pool
      win_shell: |
        Import-Module WebAdministration
        Restart-WebAppPool -Name "DefaultAppPool"

Notifying Multiple Handlers

A single task can notify multiple handlers:

---
- name: Configure Redis with multiple handlers
  hosts: cache_servers
  tasks:
    - name: Copy Redis configuration
      ansible.builtin.template:
        src: redis.conf.j2
        dest: /etc/redis/redis.conf
      notify:
        - Restart Redis
        - Update Redis status log
        - Send notification email

  handlers:
    - name: Restart Redis
      ansible.builtin.service:
        name: redis
        state: restarted

    - name: Update Redis status log
      ansible.builtin.shell: echo "Redis configuration updated at $(date)" >> /var/log/redis_updates.log

    - name: Send notification email
      ansible.builtin.mail:
        to: [email protected]
        subject: Redis configuration updated
        body: The Redis configuration was updated on {{ inventory_hostname }}

Handlers with Listen Directive

The listen directive provides a more flexible way to organize handlers. Multiple handlers can listen to the same notification topic:

---
- name: Web service deployment with listen handlers
  hosts: web_servers
  tasks:
    - name: Update web application
      ansible.builtin.copy:
        src: app/
        dest: /var/www/html/
      notify: web service updated

  handlers:
    - name: Restart Apache
      ansible.builtin.service:
        name: "{{ 'httpd' if ansible_facts['os_family'] == 'RedHat' else 'apache2' }}"
        state: restarted
      listen: web service updated

    - name: Clear application cache
      ansible.builtin.file:
        path: /var/cache/webapp/
        state: absent
      listen: web service updated

    - name: Update application log
      ansible.builtin.shell: echo "Web application updated at $(date)" >> /var/log/webapp_updates.log
      listen: web service updated

By using the listen directive, you can notify multiple handlers with a single topic name, making your playbooks more maintainable and decoupled.

Controlling When Handlers Run

By default, handlers run at the end of a play. However, sometimes you might want handlers to run earlier. You can use the meta: flush_handlers task to force notified handlers to run immediately:

---
- name: Database migration with mid-play handler execution
  hosts: database_servers
  tasks:
    - name: Stop application servers
      ansible.builtin.service:
        name: app_server
        state: stopped

    - name: Update database schema
      ansible.builtin.shell: /usr/local/bin/db_migrate
      notify: Update schema version

    - name: Force handlers to run now
      meta: flush_handlers

    - name: Start application servers
      ansible.builtin.service:
        name: app_server
        state: started

  handlers:
    - name: Update schema version
      ansible.builtin.shell: echo "$(date) - Schema updated to version $(cat /var/db/schema_version)" >> /var/log/db_migrations.log

In this example, we want to ensure that the schema version log is updated before we start the application servers, so we use meta: flush_handlers to run any notified handlers immediately.

Combining Blocks and Handlers

Blocks and handlers can be used together to create robust playbooks with elegant error handling:

---
- name: Deploy web application with error handling
  hosts: web_servers
  tasks:
    - name: Application deployment
      block:
        - name: Clone application repository
          ansible.builtin.git:
            repo: https://github.com/myorg/myapp.git
            dest: /var/www/myapp
          notify: Restart web service

        - name: Install application dependencies
          ansible.builtin.pip:
            requirements: /var/www/myapp/requirements.txt
            state: present
          notify: Restart web service

        - name: Apply database migrations
          ansible.builtin.command: python /var/www/myapp/manage.py migrate
          args:
            chdir: /var/www/myapp
          notify: Restart web service
      rescue:
        - name: Rollback to previous version
          ansible.builtin.git:
            repo: https://github.com/myorg/myapp.git
            dest: /var/www/myapp
            version: stable
          notify: Restart web service after rollback

        - name: Send deployment failure notification
          ansible.builtin.mail:
            to: [email protected]
            subject: "Deployment failed on {{ inventory_hostname }}"
            body: "The application deployment failed. Rolled back to stable version."
      always:
        - name: Clean up temporary files
          ansible.builtin.file:
            path: /tmp/deployment
            state: absent

  handlers:
    - name: Restart web service
      ansible.builtin.service:
        name: "{{ 'httpd' if ansible_facts['os_family'] == 'RedHat' else 'apache2' }}"
        state: restarted

    - name: Restart web service after rollback
      ansible.builtin.service:
        name: "{{ 'httpd' if ansible_facts['os_family'] == 'RedHat' else 'apache2' }}"
        state: restarted
      listen: web service rollback

Sequence Diagram: Blocks and Handlers Workflow

Here's a sequence diagram illustrating how blocks and handlers work in Ansible:

This diagram shows how:

1. Tasks are executed sequentially within a block

2. If a task fails, execution jumps to the rescue section

3. The always section runs regardless of success or failure

4. Handlers are queued when notified but only run at the end of the play

Best Practices for Blocks and Handlers

Based on my experience, here are some best practices for using blocks and handlers effectively:

For Blocks:

1. Group related tasks: Use blocks to group tasks that are logically related or share common properties (like conditionals or privilege escalation).

2. Plan error handling carefully: Design your rescue sections to properly handle failures and maintain system stability.

3. Use meaningful names: Give your blocks descriptive names to improve readability.

4. Avoid deep nesting: While blocks can be nested, deep nesting makes playbooks harder to read and maintain.

For Handlers:

1. Use unique names: Ensure handler names are unique across your playbook and included roles.

2. Idempotent operations: Make sure handlers are idempotent (can run multiple times without negative effects).

3. Consider using 'listen': For complex playbooks, the listen directive can make your code more maintainable.

4. Be cautious with variables in handler names: Variables in handler names can cause issues if the values change mid-play.

Common Pitfalls and Solutions

Mistake: Using variables in handler names

# Problematic code
tasks:
  - name: Configure service
    template:
      src: template.j2
      dest: /etc/service.conf
    notify: "Restart {{ service_name }}"

handlers:
  - name: "Restart {{ service_name }}"
    service:
      name: "{{ service_name }}"
      state: restarted

Solution: Place variables in the task parameters, not in the handler name:

tasks:
  - name: Configure service
    template:
      src: template.j2
      dest: /etc/service.conf
    notify: Restart service

handlers:
  - name: Restart service
    service:
      name: "{{ service_name }}"
      state: restarted

Mistake: Not handling errors appropriately in blocks

# Problematic code - no rescue or always sections
tasks:
  - name: Database backup
    block:
      - name: Stop database
        service:
          name: postgresql
          state: stopped
          
      - name: Backup files
        command: tar -czf /backup/db.tar.gz /var/lib/postgresql/data

Solution: Always include proper error handling:

tasks:
  - name: Database backup
    block:
      - name: Stop database
        service:
          name: postgresql
          state: stopped
          
      - name: Backup files
        command: tar -czf /backup/db.tar.gz /var/lib/postgresql/data
    rescue:
      - name: Ensure database is running
        service:
          name: postgresql
          state: started
    always:
      - name: Log backup attempt
        shell: echo "Backup attempted at $(date)" >> /var/log/backup.log

Conclusion

Blocks and handlers are powerful features in Ansible that significantly improve how you organize and structure your playbooks. Blocks provide clean error handling and task grouping, while handlers ensure that operations like service restarts happen at the right time and only when necessary.

In my automation journey, these features have been invaluable for creating more robust and maintainable playbooks. They've helped me reduce code duplication, handle errors gracefully, and ensure that services are only restarted when needed.

As you build your own automation, I encourage you to incorporate blocks and handlers into your playbooks. Start with simple implementations and gradually explore more complex patterns as you become comfortable with the concepts.