Skip to main content

Ansible roles management

Project description

Ansible roles management

The goal of this tool is to manage installation and upgrade of Ansible roles and collections using git tags and branches.

This tool uses the requirements.yml configuration file used by Ansible Galaxy. The syntax is unchanged and the ansible-galaxy tool can be used by people not involved in playbooks development. Version 1 of the requirements file with only a list of roles is still supported, but if you need collections then you need to convert it to version 2 (containing a list of 'roles' and a list of 'collections').

Support for collections is limited to installing a full repo with all included collections. This means all included collections (if many) will be enabled and you cannot select to enable just some of them. The name of the collection must contain the namespace to be installed in the proper path (as defined in Ansible documentation). For example:

  - name: kubernetes.core
    type: git
    version: stable-2.2

will install it at <collections_path>/ansible_collections/kubernetes/core/ with collections_path defined in your ansible.cfg or using Ansible default.

This tool assumes a role/collection version follows semantic versioning and is labelled with a git tag of the form vX.Y or vX.Y.Z (examples: v1.0 or v2.3.1). In fact the v is optional but recommended for clarity.

Roles managed manually, bare, or in a bad shape are ignored (with proper warning).


You can install it using PyPI:

pip install ansible-roles-ctl

Or you can run it in-place since it has very few dependencies (you only need the ansible-roles-ctl script, is only used in the build process).

You need the following dependencies:

  • Ansible (probably starting from 2.7)
  • GitPython (package 'python3-git' on Debian systems, or using pip)
  • argcomplete >= 1.9.2 (package 'python3-argcomplete' on Debian systems, or using pip)


Command completion is done using argcomplete. It needs to be enabled first to work. The easiest way is to use the activate-global-python-argcomplete3 script as root. Other methods are described on the argcomplete website.


Syntax is as follow:

ansible-roles-ctl [global options] [subcommand] [subcommand options]

You can use -h/--help option to list all available options at command and subcommand level, as well as all available subcommands.

Follows documentation about the various subcommands.


ansible-roles-ctl status

This subcommand display a status report about all required roles/collections.

You can limit output to a selection of roles/collections:

ansible-roles-ctl status mailman3 httpd

The -c/--changelog option displays changelog entries if available.


ansible-roles-ctl install

This subcommand install all roles/collections listed in the requirements.

You can limit this action to a selection of roles/collections:

ansible-roles-ctl install bind9 postfix


ansible-roles-ctl update

This subcommand update all roles/collections listed in the requirements to the latest version.

You can limit this action to a selection of roles/collections:

ansible-roles-ctl update bind9 postfix

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ansible-roles-ctl-2.0.0.tar.gz (26.8 kB view hashes)

Uploaded source

Built Distribution

ansible_roles_ctl-2.0.0-py3-none-any.whl (26.4 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page