Templating Migration Guide

Last updated: January 12, 2026

⚠️ Critical: This guide addresses the significant templating changes introduced in ansible-core 2.19/Ansible 12. These changes affect security, performance, and user experience. Review this guide before upgrading.

Why This Guide Exists

In late 2025, the Ansible project introduced major templating engine improvements in ansible-core 2.19 (Ansible 12). While these changes bring substantial benefits, they also break some previously "working" playbooks that relied on problematic behaviors. This guide will help you understand what changed, why it changed, and how to update your automation to be compatible.

What Changed in ansible-core 2.19

The templating changes can be grouped into three main categories:

1. Stricter Template Validation

Templates that previously failed silently now report errors explicitly.

2. Security Enhancements

Unsafe operations that could lead to code injection are now blocked by default.

3. Performance Optimizations

Template rendering is faster and more efficient, but requires cleaner syntax.

Impact Assessment: Is Your Content Affected?

Run this quick check to see if you need to migrate:

# Check your Ansible version
ansible --version

# If you're on ansible-core 2.19+ or Ansible 12+, review your playbooks
# Run playbooks with check mode first
ansible-playbook site.yml --check

# Look for deprecation warnings
ANSIBLE_DEPRECATION_WARNINGS=True ansible-playbook site.yml --check

Common Breaking Changes and Fixes

Change 1: Undefined Variables in Templates

Problem: Previously, undefined variables in templates would sometimes fail silently or return empty strings.

Old Behavior (ansible-core 2.18):

- name: Print variable
  debug:
    msg: "{{ undefined_variable }}"
  # Might print nothing or cause cryptic errors

New Behavior (ansible-core 2.19):

- name: Print variable
  debug:
    msg: "{{ undefined_variable }}"
  # ERROR: 'undefined_variable' is undefined

Solution: Use the default filter or proper conditional checks:

# Option 1: Provide a default value
- name: Print variable with default
  debug:
    msg: "{{ undefined_variable | default('Not set') }}"

# Option 2: Check if defined first
- name: Print variable if defined
  debug:
    msg: "{{ my_variable }}"
  when: my_variable is defined

# Option 3: Use default with omit for module parameters
- name: Create user with optional parameter
  user:
    name: john
    comment: "{{ user_comment | default(omit) }}"

Change 2: Type Coercion in Conditionals

Problem: Loose type coercion in conditionals could lead to unexpected behavior.

Old Behavior:

# These all evaluated to true in unexpected ways
- name: Check value
  debug:
    msg: "Value is true"
  when: "0"  # String "0" was sometimes truthy

- name: Check empty list
  debug:
    msg: "List has items"
  when: my_list  # Empty list behavior was inconsistent

New Behavior: Stricter boolean evaluation

Solution: Be explicit in your conditionals:

# Bad - implicit boolean conversion
when: my_variable

# Good - explicit checks
when: my_variable is defined and my_variable | length > 0

# For lists
when: my_list is defined and my_list | length > 0

# For strings
when: my_string is defined and my_string | length > 0

# For booleans
when: my_bool is defined and my_bool | bool

# For numbers
when: my_number is defined and my_number > 0

Change 3: Template Syntax Validation

Problem: Malformed Jinja2 syntax that was previously tolerated is now rejected.

Old Behavior:

# Missing closing braces might have worked
- name: Bad template
  debug:
    msg: "{{ my_variable "

# Nested braces without proper escaping
- name: Nested template
  debug:
    msg: "{{ '{{ inner }}' }}"

New Behavior: Strict syntax enforcement

Solution: Use proper syntax and escaping:

# Correct syntax
- name: Good template
  debug:
    msg: "{{ my_variable }}"

# Proper nesting with escaping
- name: Nested template
  debug:
    msg: "{{ '{{' }} inner {{ '}}' }}"

# Or use the raw block for literal Jinja2
- name: Template with raw Jinja2
  copy:
    dest: /tmp/template.j2
    content: |
      {% raw %}
      {{ this_is_literal_jinja2 }}
      {% endraw %}

Change 4: Filter Argument Validation

Problem: Filters with incorrect argument types were sometimes accepted.

Old Behavior:

# Passing wrong types to filters might work
- name: Bad filter usage
  debug:
    msg: "{{ my_list | join(123) }}"  # join expects string

New Behavior: Type checking enforced

Solution: Use correct types:

# Correct filter usage
- name: Good filter usage
  debug:
    msg: "{{ my_list | join(',') }}"  # String argument

# Convert types explicitly if needed
- name: Convert before filtering
  debug:
    msg: "{{ my_number | string }}"

Change 5: Loop Variable Scope

Problem: Loop variables leaking into nested contexts.

Old Behavior:

# Item from outer loop might pollute inner loop
- name: Nested loops
  include_tasks: inner.yml
  loop: "{{ outer_items }}"
  # Inner tasks might see 'item' from outer loop

New Behavior: Stricter variable scoping

Solution: Use loop_control to avoid conflicts:

# Use explicit loop variable names
- name: Nested loops with control
  include_tasks: inner.yml
  loop: "{{ outer_items }}"
  loop_control:
    loop_var: outer_item

# In inner.yml, use its own loop variable
# - name: Inner task
#   debug:
#     msg: "Outer: {{ outer_item }}, Inner: {{ item }}"
#   loop: "{{ inner_items }}"

Change 6: Template Security Restrictions

Problem: Templates that attempt to access Python internals are now blocked.

Old Behavior:

# Accessing __class__ and other internals might have worked
- name: Security hole
  debug:
    msg: "{{ ''.__class__.__bases__[0] }}"

New Behavior: Security restrictions enforced

Solution: Don't try to access Python internals. Use proper Ansible constructs:

# Use Ansible's provided variables and filters
- name: Secure approach
  debug:
    msg: "{{ ansible_facts['distribution'] }}"

# Create custom filters if you need complex Python logic
# In filter_plugins/my_filters.py:
# def my_custom_filter(value):
#     return process_value(value)

Change 7: Implicit String Concatenation

Problem: Implicit string concatenation in templates is no longer supported.

Old Behavior:

# Adjacent strings might concatenate automatically
- name: Implicit concatenation
  debug:
    msg: "{{ 'Hello' 'World' }}"

New Behavior: Explicit concatenation required

Solution: Use the concatenation operator or filters:

# Option 1: Use + operator
- name: Explicit concatenation
  debug:
    msg: "{{ 'Hello' + ' ' + 'World' }}"

# Option 2: Use format filter
- name: Format string
  debug:
    msg: "{{ '%s %s' | format('Hello', 'World') }}"

# Option 3: Use string interpolation in the template
- name: String interpolation
  debug:
    msg: "Hello {{ 'World' }}"

Migration Strategy

Phase 1: Assessment (Week 1)

1. Inventory Your Playbooks

   # Find all playbooks
   find . -name "*.yml" -o -name "*.yaml" | grep -E "(playbook|site|main)" > playbook-inventory.txt
   
   # Count templates used
   grep -r "template:" . --include="*.yml" | wc -l

2. Test in Non-Production

   # Create test environment with ansible-core 2.19
   python3 -m venv ansible-test-env
   source ansible-test-env/bin/activate
   pip install "ansible-core>=2.19.0"
   
   # Run playbooks in check mode
   ansible-playbook site.yml --check --diff

3. Collect Errors

   # Run with verbose output to capture all issues
   ansible-playbook site.yml --check -vvv 2>&1 | tee migration-errors.log
   
   # Extract template-related errors
   grep -i "template" migration-errors.log > template-issues.txt

Phase 2: Prioritization (Week 1-2)

Create a migration priority matrix:

Priority	Criteria	Action
P0	Production-critical playbooks with errors	Fix immediately
P1	Production playbooks with warnings	Fix within 2 weeks
P2	Development/test playbooks with errors	Fix within 1 month
P3	Deprecated but working playbooks	Document for future fix

Phase 3: Fixing (Week 2-4)

Work through your priority list systematically:

# Create a fix template
---
# Fix for: [Playbook name]
# Issue: [Describe the problem]
# Priority: [P0/P1/P2/P3]
# Original code:
#   [paste original]
# Fixed code:
#   [paste fix]
# Tested: [Yes/No]
# Tested by: [Name]
# Date: [Date]

Phase 4: Testing (Week 3-5)

# Create comprehensive test suite
# tests/test-templates.yml
---
- name: Template migration tests
  hosts: localhost
  gather_facts: yes
  
  tasks:
    - name: Test undefined variable handling
      debug:
        msg: "{{ test_var | default('PASS: Default works') }}"
    
    - name: Test type coercion
      debug:
        msg: "PASS: Boolean check works"
      when: test_bool is defined and test_bool | bool
    
    - name: Test filter arguments
      debug:
        msg: "{{ ['a', 'b', 'c'] | join(',') }}"
    
    # Add more tests based on your specific issues

Phase 5: Deployment (Week 5-6)

1. Deploy to development

2. Run automated tests

3. Deploy to staging

4. Conduct user acceptance testing

5. Deploy to production (with rollback plan)

Automated Migration Tools

Script to Identify Common Issues

#!/usr/bin/env python3
"""
Scan Ansible playbooks for common templating issues
"""
import re
import sys
from pathlib import Path

def scan_file(filepath):
    issues = []
    
    with open(filepath, 'r') as f:
        content = f.read()
        line_num = 0
        
        for line in content.split('\n'):
            line_num += 1
            
            # Check for undefined variable usage without default
            if '{{' in line and 'default' not in line and 'is defined' not in line:
                if re.search(r'\{\{\s*\w+\s*\}\}', line):
                    issues.append({
                        'file': filepath,
                        'line': line_num,
                        'type': 'UNDEFINED_VAR',
                        'content': line.strip()
                    })
            
            # Check for implicit boolean in when
            if 'when:' in line and '|' not in line and 'is' not in line:
                issues.append({
                    'file': filepath,
                    'line': line_num,
                    'type': 'IMPLICIT_BOOL',
                    'content': line.strip()
                })
            
            # Check for nested loops without loop_control
            if 'loop:' in line or 'with_items:' in line:
                # Simple heuristic - could be improved
                if 'include' in content[:content.find(line)]:
                    if 'loop_control' not in content:
                        issues.append({
                            'file': filepath,
                            'line': line_num,
                            'type': 'NESTED_LOOP',
                            'content': line.strip()
                        })
    
    return issues

def main():
    all_issues = []
    
    # Scan all YAML files
    for yaml_file in Path('.').rglob('*.yml'):
        if '.git' in str(yaml_file):
            continue
        
        issues = scan_file(yaml_file)
        all_issues.extend(issues)
    
    # Report findings
    print(f"Found {len(all_issues)} potential issues:\n")
    
    for issue in all_issues:
        print(f"{issue['type']}: {issue['file']}:{issue['line']}")
        print(f"  {issue['content']}\n")
    
    return 0 if len(all_issues) == 0 else 1

if __name__ == '__main__':
    sys.exit(main())

Save this as check_templates.py and run:

python3 check_templates.py

Real-World Migration Example

Here's a before/after of a real playbook migration:

Before (ansible-core 2.18)

---
- name: Deploy application
  hosts: webservers
  vars:
    app_version: "{{ version }}"  # No default!
  
  tasks:
    - name: Check if deployed
      stat:
        path: "/opt/app-{{ app_version }}"
      register: app_dir
    
    - name: Deploy if needed
      unarchive:
        src: "app-{{ app_version }}.tar.gz"
        dest: /opt/
      when: app_dir.stat.exists  # Implicit boolean
    
    - name: Configure app
      template:
        src: config.j2
        dest: "/opt/app-{{ app_version }}/config.yml"
      vars:
        # Unsafe variable access
        db_host: "{{ hostvars[groups['database'][0]].ansible_host }}"

After (ansible-core 2.19)

---
- name: Deploy application
  hosts: webservers
  vars:
    # Provide defaults for all variables
    app_version: "{{ version | default('1.0.0') }}"
    app_base_dir: "/opt"
  
  tasks:
    - name: Check if deployed
      stat:
        path: "{{ app_base_dir }}/app-{{ app_version }}"
      register: app_dir
    
    - name: Deploy if needed
      unarchive:
        src: "app-{{ app_version }}.tar.gz"
        dest: "{{ app_base_dir }}/"
      # Explicit boolean check
      when:
        - app_dir.stat is defined
        - not app_dir.stat.exists
    
    - name: Get database host
      set_fact:
        db_host: "{{ hostvars[groups['database'][0]].ansible_host }}"
      when:
        - groups['database'] is defined
        - groups['database'] | length > 0
    
    - name: Configure app
      template:
        src: config.j2
        dest: "{{ app_base_dir }}/app-{{ app_version }}/config.yml"
      # db_host now safely set or task skipped
      when: db_host is defined

Testing Your Migration

Create a comprehensive test playbook:

---
- name: Template migration validation
  hosts: localhost
  gather_facts: yes
  
  vars:
    test_scenarios:
      - name: "Undefined variable with default"
        test: "{{ undefined_var | default('PASS') }}"
        expected: "PASS"
      
      - name: "Boolean coercion"
        test: "{{ true | bool }}"
        expected: true
      
      - name: "List join"
        test: "{{ ['a', 'b', 'c'] | join('-') }}"
        expected: "a-b-c"
  
  tasks:
    - name: Run test scenarios
      assert:
        that:
          - item.test == item.expected
        success_msg: "✓ {{ item.name }}"
        fail_msg: "✗ {{ item.name }} - Expected: {{ item.expected }}, Got: {{ item.test }}"
      loop: "{{ test_scenarios }}"
      loop_control:
        label: "{{ item.name }}"

Rollback Plan

If migration causes issues in production:

---
# Emergency rollback playbook
- name: Rollback to ansible-core 2.18
  hosts: control_nodes
  become: yes
  
  tasks:
    - name: Backup current environment
      command: >
        pip freeze > /tmp/ansible-backup-{{ ansible_date_time.epoch }}.txt
    
    - name: Downgrade ansible-core
      pip:
        name: ansible-core
        version: "2.18.9"
        state: present
    
    - name: Verify version
      command: ansible --version
      register: ansible_version
    
    - name: Confirm rollback
      debug:
        msg: "Rolled back to: {{ ansible_version.stdout }}"

Best Practices for Future-Proof Templates

1. Always Use Defaults

   msg: "{{ my_var | default('safe_default') }}"

2. Explicit Type Checking

   when: my_var is defined and my_var | bool

3. Named Loop Variables

   loop_control:
     loop_var: specific_item_name

4. Validate Templates

   ansible-playbook --syntax-check playbook.yml

5. Use Check Mode

   ansible-playbook --check playbook.yml

Conclusion

The ansible-core 2.19/Ansible 12 templating changes represent a significant improvement in security, performance, and reliability. While migration requires effort, the result is more robust, maintainable automation code.

Take the time to migrate properly – your future self (and your team) will thank you!

---

Further Reading

• Official Ansible 12 Porting Guide

• Jinja2 Template Designer Documentation

• Ansible Templating Documentation

Ready to upgrade? Follow this guide step-by-step for a smooth migration! 🚀