In the past few weeks I’ve been working on alai which is a tool that helps manage the collections an Ansible project needs. It is heavily inspired by uv, so if you’ve used uv for Python, then alai should hopefully feel right at home.
A note upfront, alai was made with the help of AI tools. It hasn’t just been
thrown over the fence, I’ve put in a lot of time to think about the general
architecture, CLI user experience, and more. I understand that for some
people this turns them off a project which is a totally respectable
position.
This is also not an official Ansible/Red Hat product. It is something I’ve been working on in my own time and has no support or official connection to Red Hat. Do not expect support for this at any time as part of any contract/agreement with Red Hat.
Why another tool?
https://galaxy.ansible.com/ and ansible-galaxy are the defacto server and client tools that people use today for managing collections with Ansible but they leave a few gaps that alai has tried to fill.
The biggest one is speed, Galaxy just isn’t designed to be fast and by creating our own index format we can dramatically reduce the time it takes for installing a collection. For example community.general takes nearly 15 seconds with ansible-galaxy, on a good day, but with alai it drops down to 1-2 seconds.
Adding more collections will slow down ansible-galaxy even further due to the number of API requests that need to be made to the server.
Not only that, with caching and other optimisations, other projects can automatically reuse artifacts that another project has already downloaded trimming down the time even more.
Some of the other benefits that alai brings to the table are:
- Lock file support: Makes it dead simple to recreate an environment with the exact same collection versions, dependencies included.
- Project scoped collections: Collections specified in a project mean you no longer have system wide collections or hidden dependencies overriding the collections your playbook sees. This keeps things truly isolated from any system changes and dependency hell
- No Ansible requirement: A single tool can setup your environment without actually requiring Ansible to be present or installed
- Collection development: You no longer need to clone a local collection to
ansible_collections/ns/name/to use it with Ansible. There are some known bugs withansible-testwith this mode that I’m hoping to improve going forward. - Plugin locator: With
alai find ..., you can easily find collections that contain a plugin based on the name or other wildcard matches.
I’ve also tried to create some other CLI tools like:
- alai-doc: TUI for reading plugin documentation.
- alai-index: CLI for managing your own index.
Trying it out
alai is published on PyPI as alai-sh. The
easiest way to install it is through uv as a tool.
$ uv tool install alai-sh
$ alai --version
alai 0.1.0
Using uv tool keeps alai in its own environment isolated from everything else. Once installed as a tool alai can be run just like any other command.
An alai.toml marks the project and its root, so the first step when using alai is to create one beside your playbook or in your collection root:
$ touch alai.toml
$ alai add ansible.posix 'community.general>=10,<12'
Resolved 2 collections in 522ms
Prepared 2 collections in 1.21s
Installed 2 collections in 41ms
+ ansible.posix==2.2.2
+ community.general==11.4.9
You should commit alai.toml and alai.lock but ignore collections/ as alai manages that directory. Anyone who clones the project can then get the exact same dependencies with alai sync.
To ensure Ansible can see the collections you have in your project, run all Ansible commands with alai run ...:
$ alai run ansible-playbook site.yml -i inventory.ini
A few other commands worth knowing:
| Task | Command |
|---|---|
| Add a collection only the tests need | alai add --group test ansible.utils |
| Remove a collection | alai remove cisco.ios |
| Upgrade one collection, or everything | alai lock -P cisco.ios, alai lock -U |
| Install a collection outside the lock | alai collection install ansible.posix |
The migration guide covers some of the common use cases and how to use them with alai instead.
Things to know
- alai is considered in preview. The interface, CLI commands, etc can change.
- alai runs on Linux and macOS, no Windows support because Ansible itself cannot run on Windows.
- Collections come from an index. The default index (
https://index.alai.sh/) is a mirror of Galaxy that syncs regularly. You can run your own index with alai-index.
Links
- Documentation: https://docs.alai.sh/
- Source: https://github.com/alai-sh/alai
- Roadmap: https://docs.alai.sh/roadmap/
- Issues and ideas: https://github.com/alai-sh/alai/issues
The roadmap links to issues for what I’m thinking about next, such as requirements.yml support, building and publishing collections, and managing ansible itself. Comments on those issues are very welcome, and so is any feedback here.