Ansible troubleshooting - Error 404: no-relative-paths

Introduction

Ansible is renowned for its flexibility and efficiency in automating various IT tasks. When it comes to managing files and templates in Ansible playbooks, the “copy” and “template” modules are frequently used to handle file transfers and template rendering. However, mismanaging paths in these modules can lead to confusion and unexpected behavior. Ansible Rule 404, known as “no-relative-paths,” guides users to maintain best practices for handling paths within these modules.

Demystifying Rule 404 - “no-relative-paths”

Rule 404, “no-relative-paths,” is a vital component of Ansible’s rule set, aimed at ensuring the proper handling of paths within the “ansible.builtin.copy” and “ansible.builtin.template” modules. These modules are commonly used to interact with local and remote files in Ansible playbooks. While paths are fundamental to these modules, using relative paths can result in errors, disorganized projects, and user confusion.

The core principle emphasized by this rule is that the “src” argument in these modules should refer to local files and directories on the control node, not remote resources. Users are strongly advised to store files and templates in specific locations within the playbook or role directory:

1. Use the “files/” folder in the playbook or role directory for the “copy” module.
2. Use the “templates/” folder in the playbook or role directory for the “template” module.

These dedicated folders provide a clear and organized structure for managing your files and templates, allowing you to omit path information or use subfolders when specifying files with the “src” argument.

Problematic Code

Let’s examine a problematic code snippet to understand how Rule 404, “no-relative-paths,” can pinpoint issues in your playbooks:

---
- name: Example playbook
  hosts: all
  tasks:
    - name: Template a file to /etc/file.conf
      ansible.builtin.template:
        src: ../my_templates/foo.j2 # <- Uses a relative path in the src argument.
        dest: /etc/file.conf
        owner: bin
        group: wheel
        mode: "0644"

- name: Example playbook
  hosts: all
  vars:
    source_path: ../../my_templates/foo.j2 # <- Sets a variable to a relative path.
  tasks:
    - name: Copy a file to /etc/file.conf
      ansible.builtin.copy:
        src: "{{ source_path }}" # <- Uses the variable in the src argument.
        dest: /etc/foo.conf
        owner: foo
        group: foo
        mode: "0644"

In this code, both “ansible.builtin.template” and “ansible.builtin.copy” modules use relative paths in the “src” argument. This approach can lead to unexpected behavior and issues, especially when working with remote files.

Correct Code

To align with best practices advocated by Rule 404, the correct code should adhere to the following guidelines:

---
- name: Example playbook
  hosts: all
  tasks:
    - name: Template a file to /etc/file.conf
      ansible.builtin.template:
        src: foo.j2 # <- Uses a path from inside the "templates/" directory.
        dest: /etc/file.conf
        owner: bin
        group: wheel
        mode: "0644"

- name: Example playbook
  hosts: all
  vars:
    source_path: foo.j2 # <- Uses a path from inside the "files/" directory.
  tasks:
    - name: Copy a file to /etc/file.conf
      ansible.builtin.copy:
        src: "{{ source_path }}" # <- Uses the variable in the src argument.
        dest: /etc/foo.conf
        owner: foo
        group: foo
        mode: "0644"

In this improved code, the “src” argument references paths within the “templates/” and “files/” directories, maintaining a well-structured project and preventing potential issues stemming from relative paths.

Implementing Rule 404 - “no-relative-paths”

Rule 404, “no-relative-paths,” underscores the importance of maintaining clean and organized project structures when handling files and templates in Ansible playbooks. By following this rule, you can prevent confusion and ensure that your playbooks operate seamlessly, even in complex environments.

To effectively implement this rule, remember to:

1. Use the “files/” directory for the “copy” module and the “templates/” directory for the “template” module.
2. Reference files and templates within these dedicated directories to ensure clarity and predictability in your playbook executions.

By adhering to these practices, you can ensure that your Ansible automation remains reliable and easy to manage, even as your projects grow in complexity and scale.

Conclusion

In conclusion, Rule 404, “no-relative-paths,” is a valuable guideline offered by Ansible Lint to maintain structured and well-organized Ansible playbooks and roles. It encourages the use of recommended locations, such as the files/ and templates/ folders, for your files and templates, eliminating the need for relative paths. By following this rule, you can reduce the risk of project disorganization, confusion, and mismanagement. Ensuring that your Ansible automation projects are efficient and maintainable is crucial for long-term success. Adhering to Rule 404 is a significant step toward achieving these goals and keeping your infrastructure automation in check.

Academy

Learn the Ansible automation technology with some real-life examples in my Udemy 300+ Lessons Video Course.

My book Ansible By Examples: 200+ Automation Examples For Linux and Windows System Administrator and DevOps

Donate

Want to keep this project going? Please donate

Patreon Buy me a Pizza