community.general.ansible_galaxy_install – Install Ansible roles or collections using ansible-galaxy

Note

This plugin is part of the community.general collection (version 3.8.1).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.general.

To use it in a playbook, specify: community.general.ansible_galaxy_install.

New in version 3.5.0: of community.general

Synopsis

  • This module allows the installation of Ansible collections or roles using ansible-galaxy.

Requirements

The below requirements are needed on the host that executes this module.

  • Ansible 2.9, ansible-base 2.10, or ansible-core 2.11 or newer

Parameters

Parameter Choices/Defaults Comments
ack_ansible29
boolean
    Choices:
  • no
  • yes
Acknowledge using Ansible 2.9 with its limitations, and prevents the module from generating warnings about them.
This option is completely ignored if using a version Ansible greater than 2.9.x.
dest
path
The path to the directory containing your collections or roles, according to the value of type.
Please notice that ansible-galaxy will not install collections with type=both, when requirements_file contains both roles and collections and dest is specified.
force
boolean
    Choices:
  • no
  • yes
Force overwriting an existing role or collection.
Using force=true is mandatory when downgrading.
Ansible 2.9 and 2.10: Must be true to upgrade roles and collections.
name
string
Name of the collection or role being installed.
Versions can be specified with ansible-galaxy usual formats. For example, community.docker:1.6.1 or ansistrano.deploy,3.8.0.
name and requirements_file are mutually exclusive.
requirements_file
path
Path to a file containing a list of requirements to be installed.
It works for type equals to collection and role.
name and requirements_file are mutually exclusive.
Ansible 2.9: It can only be used to install either type=role or type=collection, but not both at the same run.
type
string / required
    Choices:
  • collection
  • role
  • both
The type of installation performed by ansible-galaxy.
If type is both, then requirements_file must be passed and it may contain both roles and collections.
Note however that the opposite is not true: if using a requirements_file, then type can be any of the three choices.
Ansible 2.9: The option both will have the same effect as role.

Notes

Note

  • Ansible 2.9/2.10: The ansible-galaxy command changed significantly between Ansible 2.9 and ansible-base 2.10 (later ansible-core 2.11). See comments in the parameters.

Examples

- name: Install collection community.network
  community.general.ansible_galaxy_install:
    type: collection
    name: community.network

- name: Install role at specific path
  community.general.ansible_galaxy_install:
    type: role
    name: ansistrano.deploy
    dest: /ansible/roles

- name: Install collections and roles together
  community.general.ansible_galaxy_install:
    type: both
    requirements_file: requirements.yml

- name: Force-install collection community.network at specific version
  community.general.ansible_galaxy_install:
    type: collection
    name: community.network:3.0.2
    force: true

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key Returned Description
dest
string
always
The value of the dest parameter.

force
boolean
always
The value of the force parameter.

installed_collections
dictionary
always when installing collections
If requirements_file is specified instead, returns dictionary with all the collections installed per path.
If name is specified, returns that collection name and the version installed per path.
Ansible 2.9: Returns empty because ansible-galaxy has no list subcommand.

Sample:
{'/custom/ansible/ansible_collections': {'community.general': '3.1.0'}, '/home/az/.ansible/collections/ansible_collections': {'community.docker': '1.6.0', 'community.general': '3.0.2'}}
dictionary
success
Collections and versions for that path

installed_roles
dictionary
always when installing roles
If requirements_file is specified instead, returns dictionary with all the roles installed per path.
If name is specified, returns that role name and the version installed per path.
Ansible 2.9: Returns empty because ansible-galaxy has no list subcommand.

Sample:
{'/custom/ansible/roles': {'ansistrano.deploy': '3.8.0'}, '/home/user42/.ansible/roles': {'ansistrano.deploy': '3.9.0', 'baztian.xfce': 'v0.0.3'}}
dictionary
success
Roles and versions for that path.

name
string
always
The value of the name parameter.

new_collections
dictionary
success
New collections installed by this module.

Sample:
{'community.docker': '1.6.1', 'community.general': '3.1.0'}
new_roles
dictionary
success
New roles installed by this module.

Sample:
{'ansistrano.deploy': '3.8.0', 'baztian.xfce': 'v0.0.3'}
requirements_file
string
always
The value of the requirements_file parameter.

type
string
always
The value of the type parameter.



Authors

  • Alexei Znamensky (@russoz)

© 2012–2018 Michael DeHaan
© 2018–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/community/general/ansible_galaxy_install_module.html