Ansible when Conditional: Complete Guide with Examples

- name: Install nginx on Debian
  ansible.builtin.apt:
    name: nginx
    state: present
  when: ansible_os_family == "Debian"

# Variable is true
- debug: msg="Debug mode"
  when: debug_mode

# Variable is false
- debug: msg="Production mode"
  when: not debug_mode

# Variable equals value
- debug: msg="Version 2"
  when: app_version == "2.0"

# Numeric comparison
- debug: msg="Low disk"
  when: disk_free_gb < 10

# By OS family
- name: Install on RedHat family
  ansible.builtin.dnf:
    name: httpd
    state: present
  when: ansible_os_family == "RedHat"

# By distribution
- name: Install on Ubuntu only
  ansible.builtin.apt:
    name: nginx
    state: present
  when: ansible_distribution == "Ubuntu"

# By version
- name: Only on Ubuntu 24.04+
  ansible.builtin.apt:
    name: nginx
    state: present
  when:
    - ansible_distribution == "Ubuntu"
    - ansible_distribution_major_version | int >= 24

# Method 1: List (implicit AND)
- name: Install on Ubuntu production servers
  ansible.builtin.apt:
    name: nginx
  when:
    - ansible_distribution == "Ubuntu"
    - env == "production"
    - ansible_memtotal_mb >= 2048

# Method 2: Explicit AND
- name: Same thing with 'and'
  ansible.builtin.apt:
    name: nginx
  when: ansible_distribution == "Ubuntu" and env == "production"

- name: Install on Debian or Ubuntu
  ansible.builtin.apt:
    name: nginx
  when: ansible_distribution == "Debian" or ansible_distribution == "Ubuntu"

- name: Complex condition
  ansible.builtin.debug:
    msg: "Condition met"
  when: >-
    (ansible_distribution == "Ubuntu" and ansible_distribution_major_version | int >= 22) or
    (ansible_distribution == "Debian" and ansible_distribution_major_version | int >= 12)

# Variable is defined
- debug: msg="{{ my_var }}"
  when: my_var is defined

# Variable is not defined
- debug: msg="Using default"
  when: custom_port is not defined

# Variable is not empty
- debug: msg="{{ my_var }}"
  when: my_var | length > 0

# Variable is in a list
- debug: msg="Valid environment"
  when: env in ['production', 'staging', 'development']

# Variable contains string
- debug: msg="Found keyword"
  when: "'error' in log_output"

- name: Check if file exists
  ansible.builtin.stat:
    path: /etc/myapp/config.yml
  register: config_file

- name: Create config if missing
  ansible.builtin.template:
    src: config.yml.j2
    dest: /etc/myapp/config.yml
  when: not config_file.stat.exists

- name: Check service status
  ansible.builtin.command: systemctl is-active myapp
  register: service_status
  ignore_errors: true

- name: Start service if not running
  ansible.builtin.service:
    name: myapp
    state: started
  when: service_status.rc != 0

- name: Install only packages that aren't installed
  ansible.builtin.apt:
    name: "{{ item.name }}"
    state: present
  loop:
    - { name: nginx, install: true }
    - { name: apache2, install: false }
    - { name: postgresql, install: true }
  when: item.install

- name: RedHat-specific tasks
  when: ansible_os_family == "RedHat"
  block:
    - name: Install EPEL
      ansible.builtin.dnf:
        name: epel-release
        state: present

    - name: Install packages
      ansible.builtin.dnf:
        name: "{{ item }}"
        state: present
      loop:
        - nginx
        - postgresql-server

# String tests
when: my_var is match("^web\d+")
when: my_var is search("error")
when: my_var is regex("^[a-z]+$")

# Type tests
when: my_var is string
when: my_var is number
when: my_var is mapping   # dict
when: my_var is iterable

# Comparison tests
when: my_version is version('2.0', '>=')
when: path is file
when: path is directory
when: path is link

- name: Run only in real mode
  ansible.builtin.command: /opt/deploy.sh
  when: not ansible_check_mode

- name: Check if already configured
  ansible.builtin.stat:
    path: /opt/app/.configured
  register: configured

- name: Run initial setup
  ansible.builtin.command: /opt/app/setup.sh
  when: not configured.stat.exists

- name: Mark as configured
  ansible.builtin.file:
    path: /opt/app/.configured
    state: touch
  when: not configured.stat.exists

- name: Install on Debian only
  ansible.builtin.apt:
    name: nginx
    state: present
  when: ansible_os_family == "Debian"
  become: true

# OS family
when: ansible_os_family == "RedHat"
when: ansible_distribution == "Ubuntu"
when: ansible_distribution_version == "24.04"

# Architecture
when: ansible_architecture == "x86_64"

# Variable defined/undefined
when: my_var is defined
when: my_var is not defined

# Boolean
when: enable_feature
when: not disable_logging
when: enable_ssl | bool

# String checks
when: env == "production"
when: "'error' in command_output.stdout"
when: app_version is version('2.0', '>=')

# All must be true (implicit AND)
- apt: name=nginx
  when:
    - ansible_os_family == "Debian"
    - ansible_distribution_version is version('20.04', '>=')
    - env == "production"

- yum: name=httpd
  when: ansible_distribution == "CentOS" or ansible_distribution == "Rocky"

# Complex
- debug: msg="Install web server"
  when: >
    (ansible_distribution == "Ubuntu" and ansible_distribution_version == "24.04")
    or
    (ansible_distribution == "Rocky" and ansible_distribution_major_version == "9")

- command: systemctl is-active nginx
  register: nginx_status
  ignore_errors: true
  changed_when: false

- debug: msg="Nginx is running"
  when: nginx_status.rc == 0

- debug: msg="Nginx is stopped"
  when: nginx_status.rc != 0

# Check stdout
- command: cat /etc/os-release
  register: os_info
  changed_when: false

- debug: msg="Running Debian"
  when: "'Debian' in os_info.stdout"

# Empty check
when: my_list | length > 0
when: my_string | length > 0
when: my_var != ""
when: my_var is not none

# In list
when: inventory_hostname in groups['webservers']
when: "'admin' in user_roles"

# Numeric comparison
when: disk_usage | int > 80
when: ansible_memfree_mb > 1024

- name: Install only needed packages
  apt:
    name: "{{ item.name }}"
  loop:
    - { name: nginx, install: true }
    - { name: apache2, install: false }
    - { name: curl, install: true }
  when: item.install
  become: true

- block:
    - apt: name=nginx state=present
    - template: src=nginx.conf.j2 dest=/etc/nginx/nginx.conf
    - service: name=nginx state=started enabled=true
  when: ansible_os_family == "Debian"
  become: true

when: ansible_distribution_version is version('22.04', '>=')
when: app_version is version('3.0.0', '<')
when: ansible_python_version is version('3.8', '>=')

# Strict version comparison
when: pkg_version is version('2.0.0', '>=', strict=true)

- stat: { path: /opt/myapp/config.yml }
  register: config

- template: src=config.yml.j2 dest=/opt/myapp/config.yml
  when: not config.stat.exists

# WRONG: Don't use {{ }} in when
when: "{{ my_var }} == 'value'"

# CORRECT: when already templates
when: my_var == 'value'

# WRONG: Bare variable might be string "false"
when: enable_feature

# CORRECT: Force boolean
when: enable_feature | bool

when: not (ansible_os_family == "Debian")
when: my_var is not defined
when: my_var != "value"

roles:
  - role: nginx
    when: install_nginx | default(true) | bool

- apt: { name: nginx }
  when: ansible_os_family == "Debian"
  become: true

- yum: { name: nginx }
  when: ansible_os_family == "RedHat"
  become: true

- debug:
    msg: "Production Ubuntu server"
  when:
    - ansible_distribution == "Ubuntu"
    - env == "production"
    - ansible_memtotal_mb >= 4096

- debug:
    msg: "Debian-based"
  when: ansible_distribution == "Ubuntu" or ansible_distribution == "Debian"

# With 'in'
- debug:
    msg: "Supported distro"
  when: ansible_distribution in ["Ubuntu", "Debian", "CentOS", "Rocky"]

- debug:
    msg: "Using custom port {{ custom_port }}"
  when: custom_port is defined

- debug:
    msg: "Using default port"
  when: custom_port is not defined

- command: which docker
  register: docker_check
  ignore_errors: true
  changed_when: false

- debug:
    msg: "Docker is installed"
  when: docker_check.rc == 0

- debug:
    msg: "Docker NOT found"
  when: docker_check.rc != 0

- service:
    name: nginx
    state: started
  when: enable_webserver  # true/false

- service:
    name: nginx
    state: stopped
  when: not enable_webserver

# OS version
when: ansible_distribution_version is version('22.04', '>=')

# Architecture
when: ansible_architecture == "x86_64"

# Memory
when: ansible_memtotal_mb > 2048

# Disk space
when: ansible_mounts | selectattr('mount', 'eq', '/') | map(attribute='size_available') | first > 5368709120

- debug:
    msg: "Installing {{ item.name }}"
  loop:
    - { name: nginx, install: true }
    - { name: apache2, install: false }
  when: item.install

- block:
    - apt: { name: nginx }
    - template: { src: nginx.conf.j2, dest: /etc/nginx/nginx.conf }
    - service: { name: nginx, state: started }
  when: ansible_os_family == "Debian"
  become: true

when: my_string | length > 0          # Not empty
when: my_string is match("^web-.*")   # Regex match
when: "'error' in log_output.stdout"  # Contains
when: my_var is string                # Type check