In this step, you will tackle errors related to Jinja2, Ansible's powerful templating engine. You'll learn why Jinja2 expressions often need to be quoted and how to debug issues when a playbook cannot find a specified template file. These are common runtime errors that occur after a playbook has already passed a syntax check.
-
Create a Jinja2 Template File
First, you need a template file. Unlike a static file, a template can contain variables that Ansible will replace with actual values during playbook execution. You will create a simple HTML template.
Use nano to create a file named index.html.j2 in your project directory (~/project/ansible_troubleshooting). The .j2 extension is a common convention for Jinja2 templates.
nano index.html.j2
Copy and paste the following HTML content into the editor. Note the {{ welcome_message }} placeholder, which is a Jinja2 variable.
<h1>{{ welcome_message }}</h1>
<p>This page was deployed by Ansible.</p>
Save the file and exit nano (Ctrl+X, Y, Enter).
-
Modify the Playbook to Use the Template and Introduce Errors
Now, modify your webserver.yml playbook to use the ansible.builtin.template module. You will also introduce two new errors: an unquoted Jinja2 variable and an incorrect template path.
Open webserver.yml with nano:
nano webserver.yml
Replace the entire content of the file with the following. The become: true directive tells Ansible to execute tasks with administrative privileges (using sudo), which is necessary to install software and write files to system directories like /var/www/html.
---
- name: Configure Web Server
hosts: localhost
become: true
vars:
package_name: httpd
welcome_message: "Welcome to Ansible with Jinja2"
tasks:
- name: Install httpd package
ansible.builtin.dnf:
## ERROR 1: Unquoted Jinja2 variable
name: { { package_name } }
state: present
- name: Create a test index page from template
ansible.builtin.template:
## ERROR 2: Incorrect template source path
src: index.j2
dest: /var/www/html/index.html
Save and exit the editor.
-
Identify and Fix the Jinja2 Quoting Error
Even though this is a Jinja2 issue, it can manifest as a YAML syntax error. Run the syntax checker to see how Ansible interprets it.
ansible-playbook --syntax-check webserver.yml
Expected Output (Error): You will get a syntax error because a YAML value starting with {{ is treated as a special construct and must be quoted to be interpreted as a string.
ERROR! A malformed block was encountered.
The error appears to be in '/home/labex/project/ansible_troubleshooting/webserver.yml': line 11, column 19, but may be elsewhere in the file depending on the exact syntax problem.
The offending line appears to be:
## ERROR 1: Unquoted Jinja2 variable
name: {{ package_name }}
^ here
Solution: Open webserver.yml and enclose the Jinja2 variable in double quotes.
nano webserver.yml
Modify the Install httpd package task:
## ... (rest of the file)
tasks:
- name: Install httpd package
ansible.builtin.dnf:
## FIX: Quote the Jinja2 expression
name: "{{ package_name }}"
state: present
## ... (rest of the file)
Save and exit. The syntax check should now pass.
-
Identify and Fix the Template Path Error
Now that the syntax is correct, try to run the playbook.
ansible-playbook webserver.yml
Expected Output (Error): The playbook will fail, but this time it's a runtime error, not a syntax error. The error message clearly states that the source file index.j2 could not be found.
TASK [Create a test index page from template] **********************************
fatal: [localhost]: FAILED! => {"changed": false, "msg": "Could not find or access '/home/labex/project/ansible_troubleshooting/index.j2' on the Ansible Controller."}
This happens because the src parameter in your playbook points to index.j2, but the file you created is named index.html.j2.
Solution: Open webserver.yml one last time and correct the filename.
nano webserver.yml
Modify the src parameter in the Create a test index page from template task:
## ... (rest of the file)
- name: Create a test index page from template
ansible.builtin.template:
## FIX: Correct template source filename
src: index.html.j2
dest: /var/www/html/index.html
## ... (rest of the file)
Save and exit the editor.
-
Run the Playbook Successfully
Run the playbook again. It should now complete all tasks successfully.
ansible-playbook webserver.yml
Expected Output (Success):
PLAY [Configure Web Server] ****************************************************
TASK [Gathering Facts] *********************************************************
ok: [localhost]
TASK [Install httpd package] ***************************************************
changed: [localhost]
TASK [Create a test index page from template] **********************************
changed: [localhost]
PLAY RECAP *********************************************************************
localhost : ok=3 changed=2 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0
