{{tag>Ansible CA}}

= Ansible collection

Voir :
  * https://setgetweb.com/p/ansible/user_guide/collections_using.html
  * https://www.jeffgeerling.com/blog/2020/ansible-best-practices-using-project-local-collections-and-roles:
  * https://bryanttseng.medium.com/use-ansible-collection-from-github-private-repository-cd7837958ddd
  * https://docs.fedoraproject.org/en-US/packaging-guidelines/Ansible_collections/
  * https://blog.octo.com/introduction-aux-ansible-content-collections
  * https://docs.ansible.com/ansible/latest/reference_appendices/config.html


Dépendances :
  * https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_reuse_roles.html#role-dependencies
  * https://labexio.medium.com/how-to-manage-dependencies-in-ansible-roles-6148675bf4b8
  * https://docs.ansible.com/ansible/latest/galaxy/user_guide.html
  * https://labex.io/fr/tutorials/ansible-how-to-manage-dependencies-in-ansible-roles-415194
  * https://docs.debops.org/en/master/ansible/roles/etc_aliases/dependency.html
  * https://hostperl.com/kb/tutorials/advanced-ansible-playbooks




Exemple

''/data/ansible/collections/ansible_collections/acme_it/test''

''.ansible.cfg''
<code python>
collections_path = /data/ansible/collections, $HOME/.ansible/collections, /usr/share/ansible/collections
</code>

Voir aussi la variable d’environnement ''ANSIBLE_COLLECTIONS_PATHS''

''collections/requirements.yml''
<code yaml>
---

collections:
  - name: https://git.acme.local/ansible_collections/my_collection
    # type: git
    scm: git
    version: master
</code>

<code bash>
ansible-galaxy collection install -r collections/requirements.yml -p /home/ansible/.ansible/collections/
</code>


<code yaml>
    - name: Install collections
      community.general.ansible_galaxy_install:
        type: collection
        requirements_file: collections/requirements.yml
        dest: ~/.ansible/collections/
      changed_when: false
</code>


== Généralités

Les collections les plus utilisées
  * ansible.builtin
  * community.general
  * ansible.posix

Dépôts distants :
* https://github.com/orgs/ansible-collections/repositories

Collection path

<code ->
$ ansible --version | grep collection
  ansible collection location = /home/ansible/.ansible/collections:/usr/share/ansible/collections

$ ansible-config dump | grep -i collection

$ ansible-config init --disabled  | grep -i collection | grep -v ^#
</code>


Lister les collections installées
<code bash>
ansible-galaxy collection list
</code>

Rechercher une collection distante
<code bash>
ansible-galaxy search plop
</code>


== Utiliser une collection distante

''collections/requirements.yml''
<code yaml>
---
collections:
  - name: https://acme.fr/plop/acme-plop.tar.gz
    version: X.Y.Z

  - name: git+https://git.acme.local/acme/plop.git#ansible_collections/acme/plop
    version: master
</code>

Rapatrier les collections distantes en local
<code bash>
ansible-galaxy collection install -r collections/requirements.yml
</code>

''play.yml''
<code yaml>
#!/usr/bin/env ansible-playbook
---
- name: exemple
  hosts: localhost
  collections:
    - acme.plop

  roles:
    - install_plop
</code>

Ou 

<code bash>
git clone ssh://git@git.acme.fr/plop/plop.git

cd plop/
mkdir ~/.ansible/
cp -a collection/ ~/.ansible/

ls -l ~/.ansible/collections/ansible_collections/awx

ansible-doc acme.awx.tower_credential
</code>


=== Exemple de role distant sur Git

''roles/requirements.yml''
<code yaml>
---

- src: ssh://git@git.acme.local:2222/ansible/ansible-role-test_jb.git
  scm: git
  version: master

</code>



=== Exemple de collection distante sur Git

''collections/requirements.yml''
<code yaml>
---    

collections:
  - name: https://git.acme.fr/ansible-automation-platform/PlaybooksGroupe/dns_cache_enable
    # type: git
    scm: git
</code>


git.acme.fr/ansible-automation-platform/PlaybooksGroupe/dns_cache_enable

dns_cache_enable/
 * roles/
 * galaxy.yml


''galaxy.yml''
<code yaml>
---

namespace: acme
name: dns
version: 1.0.0
license: BSD
readme: README.md
authors:
  - Jean <jean@acme.fr>

description: DNS client collection
</code>


''tasks/main.yml''
<code yaml>

- name: Enable local cache DNS
  include_role:
    name: acme.dns.enable_local_cache_dns

</code>


== Utiliser une collection locale


Chemin possible
* ~/.ansible/collections/ansible_collections/acme/plop/
* collections/ansible_collections/acme/plop/

== Composition d'une collection

Exemple d'arborescence :
  * COPYING
  * FILES.json
  * images/
  * MANIFEST.json
  * meta/
  * plugins/
  * README.md
  * requirements.txt
  * setup.cfg
  * test/
  * TESTING.md
  * tests/
  * tools/


== Autres

<code bash>
git clone ssh://git@git.acme.fr/plop/projet1.git

cd projet1/
mkdir ~/.ansible/
cp -a collection/ ~/.ansible/

ln -s ~/.ansible/collections/ansible_collections/acme ~/.ansible/collections/ansible_collections/awx

ansible-doc acme.awx.tower_credential
</code>