[Epic] Improve execution environments' state of things

[Andersson007]

Here's another related discussion.

Goal

The goal is that our users (including contributors):

• understand EE's benefits and ways they can use it (ansible-runner, navigator, controller/tower, etc)
• can get started easily; the threshold is low even for users unfamiliar with containerization
• as a result the community is familiar with EE
• customers as part of the community have no issues with the above about EE
• the community contributes to EE in all forms
• ideal situation: EE is well-known and popular

Issues

• There's a lack of user docs.
• Those bits of official docs we have are not full and are tower oriented. Fixed
• They live in Tower's section of docs.ansible.com. Fixed
• The current location is imo unfair because EE is a broader thing as it's a way to run Ansible as a containerized app. Plus practically, it can be used besides Tower with ansible-runner and navigator, maybe with something else. Fixed

Plan

• there will be a sub-task created for each item later
• I'm putting some initial thoughts along the way to consider: it's not a final suggestion
• the order of the task below is not strict and can be changed along the way

To reach the goal above, we need to cope with the issues. The rough plan can be :

• EE: What is a definition of "Done" for the Epic? #368
• EE: how to measure the epic's success? #366
• Ansible intro installation: add EE reference #371
• Collection requirements: add requirements.txt and bindep.txt for EE purposes #372
• EE: add requirements.txt and bindep.txt to the collection_template repo #373
• Should one or more steering committee members sponsor this effort and represent it moving forward? (from the linked topic). What exactly does this imply?
• Analyze things, mentioned in the community-topic discussion.

Tasks done

• Reach out to 2-3 people who were/are involved in EE's design/development to help with reviewing stuff we'll create later.
• Examine current ansible-builder official and third-party guides, summarize. #231
• Examine current ansible-runner official and third-party guides, summarize.
• Determine location for the EE overview page and the Build and test first EE quickstart guide. #243
• Determine a new central location for the EE doc pages source code (if it's not obvious from the answer on the previous question). Can be a new repo somewhere or an existing one like ansible/ansible. I'm inclining to a separate one if possible not to spam ansible/ansible much. UPDATE: decided to re-use https://github.com/ansible/community-docs/ and create the execution_environments directory.
• Add an EE overview page. #232
• Investigate Diataxis framework #233
• Define Execution environment documentation location and structure, move the docs #239
• Determine a permanent location for the newly created docs source code to move stuff to from the temporary one.
• Besides other presentations, use Ansible builder 3.0 presentation by Matt for How-tos
• Check the new AWX docsite
• controller EE definition doc: replace copy-pasted content with a reference to the original Builder's doc #363
• Update Builder overview page. #235
• Other EE related getstarted general guides?
  • Setting up and leveraging local podman registry for EEs guide? #319
• Think of Forum teams/ groups, Matrix channel, etc. Create if needed
  • Create EE forum group #361
• EE general docs visibility
  • EE overview and getstarted guide are visible in other guides (user and dev) on docs.ansible.com #315
  • EE overview and getstarted are visible on docs.ansible.com landing page #314
  • EE link to docs.ansible.com pages #317
• Invite the community to participate via community-topics, Bullhorn, other media.
• Think of community supported EEs
• Add a builder quick-start guide (how-to format where applicable). DONE: now its homepage contains a link to the ee quick-start guide.
• EE: Evaluate the state of the epic. Updated/close sub-tasks. Open new ones. #369
• EE: Are there comprehensive contributor guidelines in ansible-navigator? #321
• Analyze EE community feedback, issue 1 #234
• Analyze EE community feedback, issue 2 #238
• Provide a community EE image #301
  • Create Run community-ee guide as a part of Get started with EE guide #328
  • Announce community-ee guide + community-ees themselves #362
• Encourage/suggest a requirements.txt per collection to aid in EE creation (from the linked topic) (was addressed in another issue)
• EE general docs visibility in tools docsites, they contain links to EE general docs
  • ansible-builder docs contain a reference to EE getting started #308
    • Improve builder's homepage readability and structure #313
  • ansible-navigator docs contain a reference to EE getting started #309
  • AWX docs contain a reference to EE getting started #311
  • ansible-navigator and EE are mentioned on the ansible CLI tools index page in seealso #316
  • Controller (former tower) docs contain a reference to EE getting started #323
  • ansible-runner docs contain a reference to Get started EE #324
• Join EE forum group invite in tools' docs. Solved: they all refer to the Getting started EE guide which refers to the forum at the top of the page
• after the announcements create a community-topic about ansible-core + set of collections + building EE is a preferred way. UPDATE: it brings unnecessary complexity at the beginning of users journey. I added a paragraph with a ref to EE guide

[cidrblock]

FWIW, some history here ansible-community/community-topics#31

BTW, If help is needed along the way here, LMK

[nitzmahone]

Glad this is happening- there's a big need for it, and doing it upstream first should help us to better articulate when and why EEs make sense... I'd helped with some minimal cleanup on the downstream EE docs content last year, but the whole thing desperately needs a fresh start with a more task- and ecosystem-oriented approach.

I'd assumed the builder team (and probably more specifically, I) was going to just have to go write this stuff to fill the vacuum, so I'd be thrilled if someone wants to run with some/all of it and just needs technical "color" and reviews.

[Andersson007]

@cidrblock @nitzmahone thank you

yes, the fresh start is our plan. we'll play with it and will try to reflect our findings in docs along the way.
I'm gonna try all mentioned in the description myself first.
we'll be pinging one or both of you for reviews so that we are sure we use it as was intended, follow best practices, etc. to brush it up enough before involving the community.
the long passage above short, i'll ping you if i have questions:)

[shanemcd]

Small nitpick with the title - saying "EE environments'" is like saying "ATM Machine" 😄

I'm quite excited to see this initiative being kicked off. Thank you!

[samccann]

Including comments from #161 :

Based on community feedback. Some/all of this may end up in the builder guide itself, but as that code is under refactor, just capturing the details here to eventually open up a cleaner issue on the builder repo:

What's missing:

• In general, verify that there are details on how to USE EEs etc.

• The GitOps part mainly, every project using EE is reinventing how to build and publish the container. Another thing is what should be included in a EE, only runtimes or also tools used to tests your playbooks/collection? Lastly, I would know how to version the EE, to me it seems you have to put the EE inside the same GIT repo as the playbooks/collection using it.

• also a unifying place where infos on EE can be found would be nice. right now you have to collect that information together from various projects (ansible-builder, ansible-runner, ansible-navigator) and you never know which other project you missed where some important information is burried
  also the only (to my knowledge) publicly documented EE base images (https://quay.io/repository/ansible/ansible-runner?tab=tags&tag=latest) are horribly outdated

Also note:
there is some refactoring / rewriting work going on with ansible-builder that will change the whole pattern of interaction with EEs. pretty sure this PR is the basis for that effort: ansible/ansible-builder#411

there are also plans to update the community EEs with a new base image and some other stuff.ansible/ansible-builder#411

there was an announcement about runner images ansible/ansible-runner#1199 and there are some community maintained images here ansible/ansible-runner#1138 (comment)

[nitzmahone]

Just to update some of those items:

• Ansible Builder 3.0 shipped this week. It's now pretty trivial to build functional execution environments all the way back to Ansible 2.9 on any number of vanilla base OS images, which should completely obviate the need for officially-maintained runner/builder base images ever again. If folks want to maintain public "known working combo" EEs as an easy starting point, of course they should feel free, but I don't think any of the related upstream "tool" projects will be maintaining images going forward.

• Builder's reference docs and samples have been minimally updated for the new features, but there's still plenty of cleanup and new content needed to better reflect the current reality. We were mostly focused on the EE def reference docs for the release, but a lot of the other prose remains dusty. We'll probably be doing that in the coming weeks and months (in addition to whatever participation we have in the more cross-cutting effort being proposed here).

[felixfontein]

I did try out some base images; docker.io/redhat/ubi9:latest and quay.io/rockylinux/rockylinux:9 "just worked" for me; docker.io/redhat/ubi8:latest and quay.io/centos/centos:stream8 worked when adding RUN yum install --allowerasing -y python39 python39-pip python39-wheel to additional_build_steps.prepend_base; and an Arch Linux based image didn't work at all with /output/scripts/assemble: line 165: /usr/bin/dnf: No such file or directory (which I expected, looking at the generated scripts...). So I guess the "vanilla base OS images" means "vanilla base OS images that are related to RHEL" ;-)

(If anyone is interested, I'm running some tests here: ansible-collections/community.crypto#606)

[nitzmahone]

@felixfontein Yeah, I think I've mentioned "RHEL-ish" images in a few places- we're definitely not trying to support building on any arbitrary distro anytime soon.

That said, don't forget about options->package_manager_path - eg, I've sucessfully tested on Fedora 39 with only dnf5 present (ie, I removed dnf entirely)- worked a treat, and the "official" downstream EEs are all built on ubi9-minimal with only microdnf. There's still a lot of the hardcoded package manager args in the support scripts that I'm hoping we can reduce reliance on to make it even easier to support a wider range of base distros, but support for non-RHEL-ish base images/package managers is a non-goal for the foreseeable future. It's hard enough to ensure things are working properly with just the variants there...

[felixfontein]

@nitzmahone I tried to make some minimal modifications to the scripts and the code to be able to create a Debian based EE, and it worked: ansible/ansible-builder#543

[Andersson007]

the first to docs are ready for review ansible/community-docs#60 (i'm continuing to push typo-fix and cosmetic commits but it can be reviewed)
i'm not gonna wait for the PR's merge and i'll start working on the other docs as soon as i have time.

please folks take a look ansible/community-docs#60

[Andersson007]

cc @acozine

[Andersson007]

folks ansible/community-docs#60 @Akasurde and @felixfontein reviewed it.
i applied (i think) all the suggestions and replaced runner with navigator in the first how to. Please take a look whether we can merge the docs or there are other things we can improve.

[Andersson007]

FYI: I've just updated the plan in the description considering the work done. Things are moving forward. Thanks everyone!

[Andersson007]

@felixfontein @nitzmahone @cidrblock @shanemcd

The EE Getting started set of docs are available on docs.ansible.com. I've also submitted a PR with improvements today. FYI.
We still need to do some work (which I'm doing now) IMO before broadly advertising them.

Your ideas on whether a how-to run a local podman registry would be helpful for EE users?

[samccann]

@Andersson007 - looks like there's only a couple of open PRs left for this EE epic?

[felixfontein]

I noticed a few days ago that the documentation of meta/execution-environment.yml in the ansible-builder docs is very lacking. https://github.com/ansible/ansible-builder/blob/devel/docs/collection_metadata.rst doesn't give me any information of how that file should actually look like.

(I basically figured out the file's format by looking at ansible-builder's code and by looking at other collection's meta/execution-environment.yml.)

[Andersson007]

@samccann i think we could close the epic as the main work is done (at least I don't see a lot of really "epic" stuff here) and things now go forward by inertia. UPDATE: let's wait until the EE files to collection requirements topic is resolved and then close it, ideas?

@felixfontein yes, i noticed that too while working on those PRs! It definitely needs clarifications.

• We should fix the docs. Would you like to add that sample file code? If no time, let me know, i'll do it?
• I also submitted a PR yesterday aiming to allow to specify the requirements right in meta/execution-environment.yml