Ansible 12 Upgrade Guide: Breaking Changes, Data Tagging & What to Test First

# 1. Check current version
ansible --version
ansible-core --version

# 2. Create a virtualenv for testing
python3 -m venv ~/ansible12-test
source ~/ansible12-test/bin/activate
pip install ansible==12.0.0

# 3. Run playbooks in check mode first
ansible-playbook site.yml --check -v

# 4. Enable broken conditionals warning (don't error)
export ANSIBLE_ALLOW_BROKEN_CONDITIONALS=true
ansible-playbook site.yml --check -v 2>&1 | grep -i "broken conditional\|warning"

# ❌ BREAKS in Ansible 12 — truthy string, not boolean
- name: Check hostname
  ansible.builtin.assert:
    that: inventory_hostname

# Error: Conditional result was 'myhost' of type 'str',
# which evaluates to True. Conditionals must have a boolean result.

# ✅ WORKS — explicit boolean result
- name: Check hostname is set
  ansible.builtin.assert:
    that: inventory_hostname | length > 0

# ✅ Also works — use 'is defined' or 'is truthy'
- name: Check hostname is defined
  ansible.builtin.assert:
    that: inventory_hostname is defined

# ❌ Truthy check on registered variable
- name: Run command
  ansible.builtin.command: whoami
  register: result

- name: Check result
  ansible.builtin.debug:
    msg: "Success"
  when: result.stdout
  # Fix → when: result.stdout | length > 0

# ❌ Accidental string in assert
- name: Bad assert
  ansible.builtin.assert:
    that: inventory_hostname is defined and 'inventory_hostname | length > 0'
  # Fix → remove quotes: inventory_hostname is defined and inventory_hostname | length > 0

# ❌ Dictionary as conditional (YAML parsing trap)
- name: Check message
  ansible.builtin.assert:
    that:
      - result.msg == "some_key: some_value"
  # Fix → quote the whole expression:
  # - 'result.msg == "some_key: some_value"'

# ❌ Jinja operator precedence
- name: Contains check
  ansible.builtin.assert:
    that: inventory_hostname is contains "local" ~ "host"
  # Fix → add parentheses:
  # that: inventory_hostname is contains("local" ~ "host")

# ansible.cfg
[defaults]
allow_broken_conditionals = true

export ANSIBLE_ALLOW_BROKEN_CONDITIONALS=true

# ❌ BREAKS — template delimiters inside expression
- name: Calculate value
  ansible.builtin.assert:
    that: 1 + {{ value }} == 2
  vars:
    value: 1

# Error: Syntax error in expression. Template delimiters are not
# supported in expressions: expected token ':', got '}'

# ✅ WORKS — reference variable directly
- name: Calculate value
  ansible.builtin.assert:
    that: 1 + value == 2
  vars:
    value: 1

# ❌ BREAKS — dynamic template construction
- name: Dynamic conditional
  ansible.builtin.debug:
    msg: "Dynamic"
  when: "{{ my_condition }}"
  # Fix → when: my_condition

# ❌ BREAKS — nested template in variable
- name: Nested template
  ansible.builtin.debug:
    msg: "Value is {{ '{{ inner_var }}' }}"
  # Fix → msg: "Value is {{ inner_var }}"

# ❌ BREAKS — template in loop expression
- name: Loop with template
  ansible.builtin.debug:
    msg: "{{ item }}"
  loop: "{{ {{ my_list }} }}"
  # Fix → loop: "{{ my_list }}"

# ❌ BREAKS — trailing comma (syntax error)
- name: Compare values
  ansible.builtin.assert:
    that: 1 == 2,
# Error: Syntax error in expression: chunk after expression
# Fix → remove the trailing comma: that: 1 == 2

# Find potential broken conditionals
grep -rn "when:" roles/ playbooks/ | grep -v "is defined\|is not defined\|==\|!=\|>.*<\|in \|not in\|is true\|is false\|bool"

# Find nested templates
grep -rn "{{ {{ \|{{ '{{" roles/ playbooks/

# Find template delimiters in when/assert
grep -rn "when: \"{{ \|that: .* {{ " roles/ playbooks/

# test-upgrade.yml — Run against staging
- name: Test Ansible 12 compatibility
  hosts: staging
  gather_facts: true
  tasks:
    - name: Verify version
      ansible.builtin.debug:
        msg: "Running ansible-core {{ ansible_version.full }}"

    - name: Test boolean conditional
      ansible.builtin.debug:
        msg: "Boolean conditionals work"
      when: ansible_os_family == "Debian"

    - name: Test explicit length check
      ansible.builtin.assert:
        that:
          - inventory_hostname | length > 0
          - ansible_distribution is defined

# Run with verbose output to catch warnings
ansible-playbook site.yml --check -vv 2>&1 | tee upgrade-check.log

# Count issues
grep -c "broken conditional\|Syntax error\|Template delimiters" upgrade-check.log

# Upgrade
pip install --upgrade ansible==12.0.0

# Verify
ansible --version
# ansible [core 2.19.x]

# Run smoke test
ansible-playbook smoke-test.yml