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

Note

This module is part of the community.general collection (version 9.4.0).

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. You need further requirements to be able to use this module, see Requirements for details.

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

New in community.general 3.5.0

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-core 2.11 or newer

Parameters

Parameter

Comments

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

Force overwriting existing roles and/or collections.

It can be used for upgrading, but the module output will always report changed=true.

Using force=true is mandatory when downgrading.

Choices:

  • false ← (default)

  • true

name

string

Name of the collection or role being installed.

Versions can be specified with ansible-galaxy usual formats. For example, the collection community.docker:1.6.1 or the role ansistrano.deploy,3.8.0.

name and requirements_file are mutually exclusive.

no_deps

boolean

added in community.general 4.5.0

Refrain from installing dependencies.

Choices:

  • false ← (default)

  • true

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.

state

string

added in community.general 9.1.0

If state=present then the collection or role will be installed. Note that the collections and roles are not updated with this option.

Currently the state=latest is ignored unless type=collection, and it will ensure the collection is installed and updated to the latest available version.

Please note that force=true can be used to perform upgrade regardless of type.

Choices:

  • "present" ← (default)

  • "latest"

type

string / required

The type of installation performed by ansible-galaxy.

If type=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.

Choices:

  • "collection"

  • "role"

  • "both"

Attributes

Attribute

Support

Description

check_mode

Support: none

Can run in check_mode and return changed status prediction without modifying target.

diff_mode

Support: none

Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode.

Notes

Note

  • Support for Ansible 2.9/2.10 was removed in community.general 8.0.0.

  • The module will try and run using the C.UTF-8 locale. If that fails, it will try en_US.UTF-8. If that one also fails, the module will fail.

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

Description

dest

string

The value of the dest parameter.

Returned: always

force

boolean

The value of the force parameter.

Returned: always

installed_collections

dictionary

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.

Returned: always when installing collections

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"}}

<path>

dictionary

Collections and versions for that path

Returned: success

installed_roles

dictionary

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.

Returned: always when installing roles

Sample: {"/custom/ansible/roles": {"ansistrano.deploy": "3.8.0"}, "/home/user42/.ansible/roles": {"ansistrano.deploy": "3.9.0", "baztian.xfce": "v0.0.3"}}

<path>

dictionary

Roles and versions for that path.

Returned: success

name

string

The value of the name parameter.

Returned: always

new_collections

dictionary

New collections installed by this module.

Returned: success

Sample: {"community.docker": "1.6.1", "community.general": "3.1.0"}

new_roles

dictionary

New roles installed by this module.

Returned: success

Sample: {"ansistrano.deploy": "3.8.0", "baztian.xfce": "v0.0.3"}

requirements_file

string

The value of the requirements_file parameter.

Returned: always

type

string

The value of the type parameter.

Returned: always

Authors

  • Alexei Znamensky (@russoz)