Ansible wait_for Module: Wait for Conditions, Ports & Files (Guide)
By Luca Berton · Published 2024-01-01 · Category: troubleshooting
Complete guide to Ansible wait_for module. Wait for ports to open, files to appear, services to start, connections to drain, and processes to finish with practical examples.
The ansible.builtin.wait_for module pauses playbook execution until a specified condition is met — a port is open, a file exists, a string appears in a file, or connections drain. It's essential for service readiness checks, deployment orchestration, and handling reboots.
Wait for a Port
Port to Open (Service Ready)
Port to Close (Connections Drained)
Wait for Port After Restart
Wait for a File
File to Exist
File to Contain a String
File to Be Absent
Wait for Connection (After Reboot)
wait_for_connection is purpose-built for reconnecting after reboots:
Real-World Patterns
Rolling Deployment with Health Checks
Database Startup Chain
Wait for Cloud Instance
Parameters Reference
| Parameter | Description | Default | |-----------|-------------|---------| | port | Port number to check | — | | host | Host to check | 127.0.0.1 | | path | File path to check | — | | state | started, stopped, present, absent, drained | started | | delay | Seconds to wait before first check | 0 | | timeout | Seconds before giving up | 300 | | sleep | Seconds between checks | 1 | | search_regex | Regex to match in file | — | | exclude_hosts | Hosts to ignore for drained | — | | connect_timeout | Seconds for each connection attempt | 5 | | msg | Custom failure message | — |
FAQ
What does wait_for do in Ansible?
The wait_for module pauses playbook execution until a specified condition is met: a TCP port opens, a file appears/disappears, or a regex pattern is found in a file. It's used to wait for services to start, connections to drain, or processes to complete.
What is the difference between wait_for and wait_for_connection?
wait_for checks for ports, files, or strings on target hosts. wait_for_connection specifically waits for Ansible to be able to connect (SSH/WinRM) to a host — designed for use after reboots.
How do I wait for a service to be ready?
Use wait_for with the service port: wait_for: port=8080 delay=5 timeout=60. For HTTP health checks, use the uri module with retries and until instead.
What happens when wait_for times out?
The task fails with a timeout error and the playbook stops (unless ignore_errors: true is set). Use the msg parameter to provide a helpful failure message.
Can I wait for multiple conditions?
Not in a single task. Use separate wait_for tasks for each condition, or use ansible.builtin.async with poll: 0 to check multiple conditions in parallel.
Conclusion • Port checks: port: 8080 with state: started (open) or drained (closed) • File checks: path: with state: present/absent or search_regex • After reboots: Use wait_for_connection instead • Always set timeout — don't let tasks hang forever • Use delay to skip the initial startup period
Related Articles • Ansible retries & until: Retry Failed Tasks • Ansible delegate_to: Run Tasks on Different Hosts • Ansible systemd Module: Manage Services
Category: troubleshooting