Hi everyone!
It seems like there has been a lot of discussion about consolidating things and reducing fragmentation in the community this year. In keeping with that theme, I’ve got some plans that I want to share with you.
Upcoming changes
The Ansible community team is going to modify URL redirects for plugins and module pages in Ansible 2.3, 2.4, 2.5, 2.6, 2.7, and 2.10 package docs.
We plan to merge the PR with these changes and consolidate the redirects after Cfgmgmtcamp takes place in February 2025. We’ll update this post with exact dates closer to the time.
Impact to community users
These changes affect only URLs to documentation for unmaintained and end-of-life (EOL) versions of the Ansible package.
The change for the user experience is that EOL pages for plugins and modules will redirect to a single revamped docs.ansible.com/collections.html page instead of the corresponding page under the collections subdirectory. Here are some specific examples:
https://docs.ansible.com/ansible/2.6/doas_module.html currently redirects to https://docs.ansible.com/ansible/latest/collections/community/general/doas_become.html
https://docs.ansible.com/ansible/2.4/lineinfile_module.html currently redirects to https://docs.ansible.com/ansible/latest/collections/ansible/builtin/lineinfile_module.html
After we make the changes to the redirects, both ansible/2.6/doas_module.html and ansible/2.4/lineinfile_module.html will redirect to a new docs.ansible.com/collections.html page.
This will also apply to some links in external sites that point to URLs such as https://docs.ansible.com/ansible/latest/modules/k8s_module.html
Instead of redirecting to ansible/latest/collections/community/kubernetes/k8s_module.html users will be redirected to the new collections.html page.
Wait. Doesn’t this change make things worse for users?
At first glance, you might be right in thinking that, yes, redirecting everything to the same page is not such a nice user experience. When you get redirected to that collections.html page, you need to do some work to find the page you’re looking for instead of being taken there directly.
However, there is a trade-off here that we think justifies the inconvenience. Let me explain.
Everything you need to know about redirects, but didn’t want to ask
The structure of content on docs.ansible.com has changed over the course of multiple releases. Before the split to collections and the Ansible package, pages for plugins and modules had a structure like this:
/ansible/2.3/copy_module.html
/ansible/2.3/ec2_group_facts_module.html
/ansible/2.3/find_module.html
/ansible/2.3/firewalld_module.html
Then it changed to a structure like this:
/ansible/2.5/modules/copy_module.html
/ansible/2.5/modules/ec2_group_facts_module.html
/ansible/2.5/modules/find_module.html
/ansible/2.5/modules/firewalld_module.html
And plugins were added and put into a structure like this:
/ansible/2.5/plugins/cache/redis.html
/ansible/2.5/plugins/callback/foreman.html
Then finally there were collections and the structure changed again to something like this:
/ansible/2.10/collections/ansible/builtin/copy_module.html
/ansible/2.10/collections/amazon/aws/ec2_group_facts_module.html
/ansible/2.10/collections/ansible/builtin/find_module.html
/ansible/2.10/collections/ansible/posix/firewalld_module.html
/ansible/2.10/collections/community/general/redis_cache.html
/ansible/2.10/collections/theforeman/foreman/foreman_callback.html
For each of those versions, the community docs folks created an .htaccess configuration file with redirect rules that would make sure anyone looking for those pages would get pointed to the latest collection instead.
You can find all the .htaccess configuration files in the ansible/docsite repository as follows:
- ansible/2.3/.htaccess
- ansible/2.4/.htaccess
- ansible/2.5/.htaccess
- ansible/2.6/.htaccess
- ansible/2.9/.htaccess
- ansible/11/.htaccess
Note that the ansible/11/.htaccess file is for any URLs in links from external sites that I mentioned earlier. For example, links to ansible/latest/modules/ get redirected to ansible/latest/collections/.
Benefits of making this change
If you look through all those .htaccess files, you’ll notice there are more than 24 thousand redirect rules in total. Yeah, it’s not 24k lines of code, but it’s still a lot of rules. And that comes with a cost that can be broken into two things:
- Lots of maintenance between releases. With each release of the Ansible package, collections get moved around and are either deprecated or removed. If we want to be serious about preventing 404s that degrade SEO authority for
docs.ansible.comand to provide a good user experience, someone needs to update and validate the redirect rules.
Let’s look at the rule for that ansible/latest/modules/k8s_module.html path mentioned earlier. You can see the current rule here:
That module has moved and the target URL for the redirect returns a 404: https://docs.ansible.com/ansible/latest/collections/community/kubernetes/k8s_module.html
The redirect rule needs to be updated, so the target URL is this one: kubernetes.core.k8s module – Manage Kubernetes (K8s) objects — Ansible Community Documentation
- Keeping thousands of redirect rules defined in
.htaccessfiles means we’re tied to Red Hat managed infrastructure for hostingdocs.ansible.com. There’s nothing wrong with that, necessarily. It’s great that Red Hat takes on the financial cost and maintenance burden for that infrastructure to support the community. However, it limits the ability of community maintainers from handling docs publishing and getting full visibility and access to infrastructure. At the moment, only certain Red Hat employees can publish content todocs.ansible.comand make changes to the server-side. This sort of locked down environment strangles progress towards a more open hosting platform that offers lots more features.
We’ve been working on migrating docs.ansible.com to Read The Docs hosting and have talked about it on the forum for a while now. At the moment we have all the Red Hat managed projects, and some community projects, building under the ansible namespace at: https://ansible.readthedocs.io/
With a limit of 100 redirects per project we can’t recreate all those redirects on Read The Docs and migrate the docs.ansible.com subdomain.
So, to summarize the benefits of consolidating these redirect rules, we free ourselves from a massive maintenance overhead and make it possible to migrate to a platform with features like cross-project search and greater community access.
How do we plan to consolidate redirects?
We will remove all the .htaccess files in the ansible subdirectory of the ansible/docsite repository.
We will replace all the individual redirect rules with consolidated ones such as this:
RedirectMatch permanent "^/ansible/(devel|latest)/(plugins|modules)/(.+)\.html$" "/collections.html"
This rule matches URLs with ansible/devel/plugins and ansible/latest/plugins in the path and redirects them to docs.ansible.com/collections.html.
You can view the PR, and all of the conversation, with the consolidated rules here: https://github.com/ansible/docsite/pull/261
We are also updating the collections.html page to include some helpful links to make it easier for folks to find their way to the appropriate collection. You can find a PR preview build of that page here: collections.html preview build
Have all these consolidated redirects been tested?
Yes, we’ve tested these consolidated redirects thoroughly. You’re welcome to view our findings in this issue comment.
You can find more about the tests and the script used to check all the urls in this README
Call to Action: Give us your feedback
As always, we want to hear from you. Please reply to this post if you have any questions, suggestions, or comments. Feel free to also comment on the docsite PR directly. We’d appreciate any insights you might have or ways to improve our approach. Thanks!