Mention a way for absolute path referencing

jdorel commented 3 years ago

Summary

When you start having a lot of playbooks, it makes sense to want to reorganize them or to split reusable tasks in separate files. But if you are referencing other files (like templates, files or other playbooks) in those playbooks, you can't move them easily. There is a way to implement absolute referencing (although it is a workaround and I believe an environment variable should exist in ansible directly) and I believe it should be included in the documentation. Although I'm not sure of where.

Issue Type

Documentation Report

Component Name

docs/docsite/rst/user_guide/

Ansible Version

N/A

Configuration

N/A

OS / Environment

N/A

Additional Information

Proposed inclusion :

Absolute paths
--------------

Considering you might want to reorganize files referenced in your playbooks later, you should consider using absolute paths. To do that, set the following variables for the `all` group::

    ansible_repo_path: "{{ ansible_config_file[:-12] }}" # Get current repo path : remove trailing /ansible.cfg
    files_path: "{{ ansible_repo_path }}/playbooks/files"
    templates_path: "{{ ansible_repo_path }}/playbooks/templates"
    tasks_path: "{{ ansible_repo_path }}/playbooks/tasks"
    vaults_path: "{{ ansible_repo_path }}/playbooks/vaults"

Then, after creating the file ``playbooks/files/foo.conf``, you can reference it in your playbooks like this::

    - name: Copy file
      ansible.builtin.copy:
        src: {{ files_path }}/foo.conf
        dest: /etc/foo.conf

.. note: This use the fact that you have a ``ansible.cfg`` file at the root of your folder. If this file doesn't exists, this method won't work.

Code of Conduct

[X] I agree to follow the Ansible Code of Conduct

ansibot commented 3 years ago

Files identified in the description:

If these files are incorrect, please update the component name section of the description or use the !component bot command.

click here for bot help

sivel commented 3 years ago

I would not advise using an example that references ansible.cfg as the source of what indicates the root of a project.

Our general consensus, is that config dependent content is a bad idea, so using ansible.cfg as the root of which the project is defined, goes against that principal.

I'd lean more toward just a generic statement of something to the effect of:

You may find playbook_dir, inventory_dir, inventory_file, role_path, or ansible_config_file useful for determining paths relative to known locations within your project directory.

jdorel commented 3 years ago

I know it's a hack around current ansible limitation, but the generic statement you propose doesn't provide users a way to implement absolute referencing.

ansibot commented 2 years ago

Files identified in the description: