Ansible docs install trimmed down to 'pip'

[samccann]

Summary

Recent doc changes have trimmed the Ansible installation to use pip as the standard install. This simplifies the approach for new users to a common tool.

The question for the community - do we need to bring back any of the other package install options on a separate 'other installation options' page? We don't want to have the full list we used to have because it frequently got outdated and the community team and core don't have the expertise to keep it valid. Our options are:

1. Provide a 'shell' page where community members can open a PR to add a different install option, with boilerplate text to say we cannot guarantee the accuracy of the content.
2. Provide a couple of installs that the community team commits to keeping updated as packages/distros change etc
3. Provide links to distros that have their own install docs 'somewhere else' the presumably stay accurate for that distro.
4. Leave it with just pip and we get out of the business of maintaining docs or supporting any other install option for Ansible/ansible-core.

Thoughts/comments welcome on any of these options or other ideas!

[mariolenz]

At the spur of the moment, I should say don't document how to install ansible on specific distros (there are so many...) using their specific package management. It's their job to document how to install a package in general / ansible specifically.

However, you might want to make it clearer that the documentation in Ansible installation is outside the usual package management of distributions. And, if people don't want this, refer them generally to the documentation of the distro they use.

[briantist]

Option 4 aligns with the recommended way to install, and is the least burdensome, but the issue with not having anything at all for distro installs (option 4) is that no matter how bad of an idea it is people will still want to do it, and they will not find it in the docs, and they will ask (via issues or in chat or whatever) and not having a good answer for frequently asked questions is generally not a good experience.

So I like option 3, but the main issue for option 3 is dead links; keeping the links to the instructions alive is less work than keeping working install instructions alive, but it's still work. I think that 3 is a good option if we can provide high-quality, maintained links with stable URLs.

If there are folks out there maintaining those external pages who can provide some level of commitment to that, then I'd be all for linking to those external instructions.

I also like @mariolenz 's suggestion to more explicitly say upfront that the recommended way to install Ansible is through pip and that other installation methods may be available but will be unsupported (then proceed with various unsupported links for convenience).

---

In short I'd vote for option 3 with caveats, of if that's not possible, then option 4 with more explicit messaging about why distro / other install options are not on this page.

[MarkusTeufelberger]

While distributions might also provide ansible packages (e.g. something like https://packages.ubuntu.com/focal/ansible), these are not maintained by the project. If the project provides distro packages (e.g. https://launchpad.net/~ansible/+archive/ubuntu/ansible), they should be kept up-to-date and they should be documented.

Installing via pip or pip3 is a really really bad idea on an actual production machine and if any installation method gets removed, it should be actually the pip one in my opinion since nobody should actually use that outside of actually developing Ansible itself. Pip might install packages but it definitely doesn't manage them well.

[mariolenz]

I also like @mariolenz 's suggestion to more explicitly say upfront that the recommended way to install Ansible is through pip and that other installation methods may be available but will be unsupported (then proceed with various unsupported links for convenience).

@briantist I didn't say anything about installation through pip should be the recommended or preferred way. In fact, there might be good reasons to use the package provided by your distro. I wouldn't want to tell people installing via pip is always the better option. I just think that a) Ansible shouldn't document this (that's the job of the distribution in question) an b) make clear that using pip means installing stuff outside the usual package management of distributions.

If the project provides distro packages (e.g. https://launchpad.net/~ansible/+archive/ubuntu/ansible), they should be kept up-to-date and they should be documented.

@MarkusTeufelberge Well, yes. My point is: This should be documented within the distro.

Installing via pip or pip3 is a really really bad idea on an actual production machine and if any installation method gets removed, it should be actually the pip one in my opinion since nobody should actually use that outside of actually developing Ansible itself.

I don't see why using pip should be a bad idea. I guess there are good reasons both to do it and not to do it. For example, using pip you might get bugfixes and new features sooner than you would get them in your distribution. On the other hand, you might get new bugs that will never get into your distribution because they'll get fixed before your distribution updates the package. It's a tradeoff, and people have to decide for themselves.

BTW: The people actually developing Ansible / collections generally work directly on the source code, the don't need PyPI packages ;-)

Pip might install packages but it definitely doesn't manage them well.

I'm not sure what you mean. With pip you can install, remove and update (Python) packages. That's what a package manager is about IMHO. If you think that pip "doesn't manage them well", maybe you should tell the people maintaining it.

[MarkusTeufelberger]

I don't see why using pip should be a bad idea.

I'm not sure what you mean.

Ansible does not pin its dependencies down by design (https://github.com/ansible/ansible/blob/devel/requirements.txt) so whenever you run pip install ansible you'll get random untested/unverified versions of jinja2, cryptography etc. installed on your system that were potentially never ever tested to actually be compatible. pip also doesn't run any kind of tests after installation, it'll just dump the files on your disk and is done.

Another issue is that there's no builtin mechanism to detect which package a certain file belongs to for example and unlike distro package managers, pip also lacks a "update all my packages to the latest stable and tested version" feature. This is by design, since there might be lots of different projects that you manage via pip in many different environments - it is designed to help you manage the dependencies of the Python code you write, not to install finished pieces of software that is supposed to be used and executed. It's like using cmake to install your web browser. It surely can be done. It surely is not the right tool for the job.

On the flip side there are tons of issues with only using distro packages too. For example you'd be stuck on Ansible 2.5.1(!) if you were using Ubuntu 18.04 LTS, even with backports enabled. Even the upcoming Ubuntu 22.04 release will ship Ansible 2.10 (https://packages.ubuntu.com/jammy/ansible - but also ansible-core 2.12, so there might be some hope left. Thanks for that version number chaos I guess... https://packages.ubuntu.com/jammy/ansible-core ) and thus cause its users a LOT of issues to even find documentation online right from its release in a few weeks from now. This is why the official PPA exists, to bridge that gap.

There might be other (better?) ways to get a working up-to-date and tested/verified installation of ansible onto your system, such as official Docker/OCI container images for example and if you feel adventurous or don't really care about something breaking and you having to manually fix something here and there (as well as being comfortable with the tooling - not everyone is a Python developer!) pip might be good enough. I definitely wouldn't strip down the documentation to only point towards pip though, since it is for the reasons mentioned above only really useful for someone who doesn't care about automatic stable updates if new patch releases are coming out and who is somewhat versed in the Python ecosystem and the command line in general.

[acozine]

Maybe add a Note on the docs for "install with pip" that explains the risks and links out to some of the major package managers? The docs have already been stripped down to only describe pip install - that's in the devel docs today and will be in latest when the new version is released.

[jamescassell]

I'd vote for 1 or 2. Pip is inappropriate for many corporate scenarios.

[tpo]

I appreciate the install page as it is now as of Apr 03, 2022. I think it hits the balance very well saying that distros might have their own packages of ansible and that the user can install those if he thinks so.

If ansible as a project commits to maintaining the pip method of installation and keeping the respective docu up to date then everything is good.

Not pinning or respectively prescribing which versions of its dependencies ansible depends on is risky, however if ansible's dependencies consider themselves mature projects with proper semantic versioning then the risk should be manageable.

While the install page looks very fine to me, I would like to address a tendency that I feel shows a little bit here: SW creators coming down on installing their SW from distro: I do not know if any of you has witnessed the times before there were distros (say working on a SunOS machine) where you had to install everything by yourself and installing some random software would take you from a half an hour to a day. We all are only able to enjoy our productivity because a huge amount of software is only an apt-get or dnf install away. Everybody's own software is the most beatiful pony in the universe, however the user wants to be able to use each pony in his own huuuuge herd with as little tending to as possible... this means no pip and stuff! Again I think the web page is just fine and allows deferring to the distros and those should take up the responsibility of making the installation and integration of their ansible own pony with the rest of the herd as painless as possible.

And finally, the reason why I'm here is #76799 the gist of which is that it's really hard to find the "latest stable" ansible release, a topic which the web page is not very explicit about except for the top yellowish text which mentions selecting the "latest stable version" via dropdown on that page.

[samccann]

implemented by ansible/ansible#77567