A command-line tool for managing Ansible content.
Note: Mazer is most useful when used with a version of Ansible that understands mazer installed content. Currently that means ansible 2.8 and later.
Mazer will be deprecated with the release of Ansible 2.9. The functionality developed in Mazer will migrate to the ansible-galaxy command line tool. See PR 57106 for details.
Mazer is experimental, and currently only available for tech-preview. Use with lots of caution! It is not intended for use in
production environments, nor is it currently intended to replace the ansible-galaxy command-line tool.
If you're installing Ansible content in a production environment, or need assistance with Ansible, please visit the Ansible project, or the Ansible docs site.
- Install content from Galaxy artifacts containing collections of Ansible roles, modules and plugins ('mazer install')
- Generate artifacts from local content that can then be published to the Galaxy server ('mazer build')
- Provide versioned management of installed content
- Integrate with popular testing tools like Ansible Lint and Molecule
For additional documentation on mazer, view the Mazer topic on Ansible Galaxy Docs
To install the collection testing.ansible_testing_content from Galaxy:
$ mazer install testing.ansible_testing_content
The above will download the collection artifact from Galaxy, and install the contents to ~/.ansible/collections/ansible_collections/testing/ansible_testing_content/
/home/adrian/.ansible/collections/ansible_collections
└── testing
├── ansible_testing_content
│ ├── FILES.json
│ ├── LICENSE
│ ├── MANIFEST.json
│ ├── meta
│ ├── plugins
│ │ ├── action
│ │ │ └── add_host.py
│ │ ├── filter
│ │ │ ├── json_query.py
│ │ │ ├── mathstuff.py
│ │ │ └── newfilter.py
│ │ ├── lookup
│ │ │ ├── fileglob.py
│ │ │ ├── k8s.py
│ │ │ ├── newlookup.py
│ │ │ └── openshift.py
│ │ ├── modules
│ │ │ ├── elasticsearch_plugin.py
│ │ │ ├── kibana_plugin.py
│ │ │ ├── module_in_bash.sh
│ │ │ ├── mysql_db.py
...
$ mazer install --collections-path ~/my-ansible-content alikins.collection_inspect
The above will download the collection alikins.collection_inspect form Galaxy and install the contents to ~/my-ansible-content/alikins/collection_inspect.
To enable development of collections, it is possible to install a local checkout of a collection in 'editable' mode.
Instead of copying a collection into ~/.ansible/collections/ansible_collections, this mode will create a symlink from ~/.ansible/collections/ansible_collections/my_namespace/my_colllection to the directory where the collection being worked on lives.
ie, if ~/src/collections/my_new_collection is being worked on, to install the collection in editable mode under the namespace 'my_namespace':
$ mazer install --namespace my_namespace --editable ~/src/collections/my_new_collection
This will result in 'my_namespace.my_new_collection' being "installed". The above command symlinks ~/.ansble/collections/ansible_collections/my_namespace/my_new_collection to ~/src/collections/my_new_collection.
The install option '--editable' or the short '-e' can be used.
Note that '--namespace' option is required.
Mazer supports specifying a list of collections to be installed from a file (a 'collections lockfile').
To install collections specified in a lockfile, use the '--lockfile' option of the 'install' subcommand:
$ mazer install --lockfile collections_lockfile.yml
To create a collections lockfile representing the currently installed collections:
$ mazer list --lockfile
To create a lockfile that matches current versions exactly, add the '--frozen' flag:
$ mazer list --lockfile --frozen
To reproduce an existing installed collection path, redirect the 'list --lockfile' output to a file and use that file with 'install --collections-lock':
$ mazer list --lockfile > collections_lockfile.yml
$ mazer install --collections-path /tmp/somenewplace --lockfile collections_lockfile.yml
The contents of collections lock file is a yaml file, containing a dictionary.
The dictionary is the same format as the 'dependencies' dict in galaxy.yml.
The keys are collection labels (the namespace and the name dot separated ala 'alikins.collection_inspect').
The values are a version spec string. For ex, * or "==1.0.0".
Example contents of a collections lockfile:
alikins.collection_inspect: "*"
alikins.collection_ntp: "*"Example contents of a collections lockfile specifying version specs:
alikins.collection_inspect: "1.0.0"
alikins.collection_ntp: ">0.0.1,!=0.0.2"Example contents of a collections lockfile specifying exact "frozen" versions:
alikins.collection_inspect: "1.0.0"
alikins.collection_ntp: "2.3.4"In the future, galaxy will support importing and ansible content collection artifacts. The artifacts are collection archives with the addition of a MANIFEST.json providing a manifest of the content (files) in the archive as well as additional metadata.
For example, to build the test 'hello' collection included in mazer source code in tests/ansible_galaxy/collection_examples/hello/
$ # From a source tree checkout of mazer
$ cd tests/ansible_galaxy/collection_examples/hello/
$ mazer build
$ mazer migrate_role --role roles/some_trad_role/ --output-dir collections/roles/some_trad_role --namespace some_ns --version=1.2.3
The above command will create an ansible content collection artifact at tests/ansible_galaxy/collection_examples/hello/releases/v11.11.11.tar.gz
mazer is configured by a 'mazer.yml' config file in ~/.ansible.
# The galaxy rest api server mazer will communicate with.
server:
# The http or https URL of the Galaxy server used by default.
# REST requests will be made to https://galaxy.ansible.com/api/v2
# in this example.
#
# default: https://galaxy.ansible.com
#
url: https://galaxy.ansible.com
# if ignore_certs is true, https requests will not verify the
# https server certificate is signed a known CA.
#
# default: False (https connections do verify certificates)
#
ignore_certs: false
# This is the API key used when the Galaxy API needs to authenticate
# a request. For example, for the POST request made when using the
# 'publish' sub command to upload collection artifacts.
# 'api_key' here is equilivent to the cli '--api-key'
#
# The default value is unset or None.
#
# The API key can be found at https://galaxy.ansible.com/me/preferences
api_key: da39a3ee5e6b4b0d3255bfef95601890afd80709
# When installing content like ansible collection globally (using the '-g/--global' flag),
# mazer will install into sub directories of this path.
#
# default: /usr/share/ansible/collections
#
global_collections_path: /usr/share/ansible/collections
# When installing content like ansible collections, mazer will install into
# sub directories of this path.
#
# default: ~/.ansible/collections
#
collections_path: ~/.ansible/collections
# The version of the config file format.
# This should never need to be changed manually.
version: 1The source code for mazer lives at https://github.com/ansible/mazer
$ git clone https://github.com/ansible/mazer.git
$ cd mazer
$ python setup.py install
Or install the requirements via pip:
$ pip install -r requirements.txt
pip install mazer
pip install -v git+ssh://git@github.com/ansible/mazer.git
The versions of ansible that support mazer content have a config option for setting the content path. If the install ansible has this config option, mazer content will work.
To verify that, run the command 'ansible-config list | grep COLLECTIONS_PATH'. If 'COLLECTIONS_PATH' is found the correct branch of ansible is installed.
$ ansible-config list | grep COLLECTIONS_PATH
COLLECTIONS_PATH:
To run mazer from a source checkout, without installing, use the setup.py 'develop' command:
python setup.py develop
mazer uses pytest for unit tests.
To install test requirements, use pip to install the requirements in requirements_test.txt:
pip install -r requirements_test.txt
To run unit tests
via `tox` for default platforms (python 2.6, 2.7, 3.6):
$ tox
via 'pytest' directly
$ pytest tests/
When installing content from an Ansible Galaxy server, requires Galaxy v3.0+.
To see what we're working on, and where we're headed, view the roadmap.
To keep up with the latest changes, view the changelog.
Issues welcome! If you find a bug, or have a feature idea, please let us know by opening an issue.
You can also reach out to us on irc.freenode.net in the #ansible-galaxy channel.
The name Mazer comes from a character from Ender's Game, Mazer Rackham, that Wikipedia describes as "the half-Māori captain who singlehandedly stopped the Second Invasion by realizing that the Buggers are a hive mind. Due to his inability to pass on his knowledge, he was forced to spend fifty years at relativistic speeds (eight years to Rackham) so that he could train the next commander — Ender Wiggin."
A mazer is also a hardwood drinking vessel.