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.7.0).

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)