.. _ag_setup_roles:

Roles
-----

.. contents::
   :local:
   :depth: 2

Namespace vbotka
^^^^^^^^^^^^^^^^
  
If you want to install other roles from the namespace `vbotka`_, see ``setup/vars/roles.yml``. The
dictionary ``bsd_roles`` keeps the tested roles

.. code-block:: yaml
   :force:

   bsd_roles:
     - galaxy: vbotka.ansible
       name: ansible
       scm: git
       src: https://github.com/vbotka/ansible-ansible
       version: 2.7.1
     - galaxy: vbotka.ansible_lib
       name: lib
       scm: git
       src: https://github.com/vbotka/ansible-lib
       version: 2.7.0
       ...
     - galaxy: vbotka.config_light
       name: config_light
       scm: git
       src: https://github.com/vbotka/ansible-config-light
       version: 2.7.
       ...
     - galaxy: vbotka.freebsd_custom_image
       name: custom_image
       scm: git
       src: https://github.com/vbotka/ansible-freebsd-custom-image
       version: 2.7.5
     - galaxy: vbotka.freebsd_dns
       name: dns
       scm: git
       src: https://github.com/vbotka/ansible-freebsd-dns
       version: 2.6.2
       ...

Put the roles you want to install into the list ``bsd_roles_install`` in
``setup/vars/roles_linstall.yml`` and run the play

.. code-block:: console

   shell> cd setup
   shell> ansible-playbook setup.yml -t roles

Manually remove obsolete versions from the directory ``roles``.

Naming convention
"""""""""""""""""

The naming convention is simple:

* The GitHub repositories' names always start with ``ansible-``. If a role works with FreeBSD only,
  the GitHub name starts with ``ansible-freebsd``.

* The Ansible Galaxy roles' names start with the namespace ``vbotka`` and follow with the GitHub name
  without the prefix ``ansible-`` where dashes ``-`` are replaced with underscores ``_``.

* The collection roles' names start with ``vbotka.freebsd`` and follow with the last parts of the
  GitHub names where dashes ``-`` are replaced by underscores ``_``.

For example,

.. csv-table::
   :header: "GitHub vbotka", "Galaxy vbotka", "Collection vbotka.freebsd"
   :widths: 30, 30, 30

   "ansible-ansible", "vbotka.ansible", "vbotka.freebsd.ansible"
   "ansible-config-light", "vbotka.config_light", "vbotka.freebsd.config_light"
   "ansible-freebsd-custom-image", "vbotka.freebsd_custom_image", "vbotka.freebsd.custom_image"

The roles imported in the Ansible Galaxy namespace `vbotka`_ and included in the collection
`vbotka.freebsd`_ are identical. You can use them in parallel or interchange them without
restrictions.

.. note::

   The roles' files ``README.md`` are imported in the collection documentation. The titles might
   be misleading because they keep the Galaxy names. For example, the role
   `vbotka.freebsd.custom_image`_ documentation says:

   .. code-block:: text
      
     freebsd_custom_image
     --------------------

     This role is included in the collection vbotka.freebsd as vbotka.freebsd.custom_image

Role vbotka.ansible_lib
"""""""""""""""""""""""

The role `vbotka.ansible_lib`_ comprises independent tasks. The purpose is providing reusable tasks
that can be imported or included in playbooks and other roles.

.. csv-table::
   :header: "GitHub vbotka", "Galaxy vbotka", "Collection vbotka.freebsd"
   :widths: 30, 30, 30

   "ansible-lib", "vbotka.ansible_lib", "vbotka.freebsd.lib"

Some roles depend on it. If such roles are included in the collection `vbotka.freebsd`_ they are
modified to use the dictionary ``<name>_ansible_lib``. For example, the dictionary ``rsnapshot_ansible_lib``

.. code-block:: yaml

   rsnapshot_ansible_lib:
     vbotka.rsnapshot: vbotka.ansible_lib
     vbotka.freebsd.rsnapshot: vbotka.freebsd.lib

is used to select ``vbotka.ansible_lib`` or ``vbotka.freebsd.lib`` depending on the role running in
the collection or not. For example,

.. code-block:: yaml

   - name: "Vars: Include OS vars."
     vars:
       al_os_vars_path: "{{ ansible_parent_role_paths.0 }}"
     ansible.builtin.include_role:
       name: "{{ rsnapshot_ansible_lib[ansible_role_name] }}"
       tasks_from: al_include_os_vars_path

.. seealso::

   The special variable `ansible_role_name`_

Other dependent roles
"""""""""""""""""""""

There are other dependent roles. For example, the role `vbotka.freebsd.zfs`_ depends on the role
`vbotka.freebsd.postinstall`_. The dictionary ``fzfs_freebsd_postinstall``

.. code-block:: yaml

   fzfs_freebsd_postinstall:
     vbotka.freebsd_zfs: vbotka.freebsd_postinstall
     vbotka.freebsd.zfs: vbotka.freebsd.postinstall

is used to select ``vbotka.freebsd_postinstall`` or ``vbotka.freebsd.postinstall`` depending on the
role running in the collection or not. For example,

.. code-block:: yaml

   - name: "Sysctl: Include vbotka.freebsd.postinstall sysctl"
     ansible.builtin.include_role:
       name: "{{ fzfs_freebsd_postinstall[ansible_role_name] }}"
       tasks_from: sysctl.yml
       apply:
         tags: fzfs_sysctl
         vars:
           fp_sysctl_conf: "{{ fzfs_sysctl_conf }}"
           fp_sysctl_tuneables_warning: "{{ fzfs_sysctl_tuneables_warning | bool }}"

Other roles
^^^^^^^^^^^

If you want to install other roles into this collection update the dictionary ``bsd_roles``.

.. seealso::

   `Migrating Roles to Roles in Collections on Galaxy`_.

.. note::

   To install roles outside this collection see
   `Installing roles <https://docs.ansible.com/ansible/latest/galaxy/user_guide.html#installing-roles>`_.

.. warning::

   * The collection upgrade will override the changes. Backup your changes before you upgrade the
     collection.

   * This collection does not provide an upgrade procedure that preserve changes. After the upgrade,
     you are responsible for restoring your changes.


.. _vbotka: https://galaxy.ansible.com/ui/standalone/namespaces/7289
.. _vbotka.freebsd: https://galaxy.ansible.com/ui/repo/published/vbotka/freebsd
.. _vbotka.freebsd.lib: https://galaxy.ansible.com/ui/repo/published/vbotka/freebsd/content/role/lib
.. _vbotka.ansible_lib: https://galaxy.ansible.com/ui/standalone/roles/vbotka/ansible_lib

.. _vbotka.freebsd.zfs: https://galaxy.ansible.com/ui/repo/published/vbotka/freebsd/content/role/zfs
.. _vbotka.freebsd.postinstall: https://galaxy.ansible.com/ui/repo/published/vbotka/freebsd/content/role/postinstall
.. _vbotka.freebsd_zfs: https://galaxy.ansible.com/ui/standalone/roles/vbotka/freebsd_zfs
.. _vbotka.freebsd_postinstall: https://galaxy.ansible.com/ui/standalone/roles/vbotka/freebsd_postinstall

.. _vbotka.freebsd.custom_image: https://galaxy.ansible.com/ui/repo/published/vbotka/freebsd/content/role/custom_image

.. _Migrating Roles to Roles in Collections on Galaxy: https://docs.ansible.com/ansible/devel/dev_guide/migrating_roles.html
.. _ansible_role_name: https://docs.ansible.com/ansible/latest/reference_appendices/special_variables.html#term-ansible_role_name
