Should we add a section for Execution Environments?

[jeichler]

Since it's imho a relevant part of Ansible, should we add a section for EE good practices?

Things like: single purpose, versioning, version pinning of deps etc.

[ericzolf]

I'm in favour. I even have something to contribute re. versioning:

It is recommended to decouple the life-cycle of the EEs from the automation content, else each introduction of a new version becomes a small project requiring synchronization will all automation content owners, so that they can test their automation with the new EE.

A way to do this is to have each image versioned with a https://semver.org/[SemVer] of the form `MAJOR.MINOR.PATCH`.
The image must be tagged accordingly with all sub-versions, e.g. assuming a version 1.2.3:

- v1.2.3
- v1.2
- v1
- latest

In this way, each automation owner can decide on which version they base their automation, but it's also up to them to update the version they use.

NOTE: in automation controller, EEs and their tag can be selected at the organization, project or job template level, each level overwriting the previous one.

It is then important for the AAP team to define a life-cycle for their images and to make them respect, e.g.:

- by providing end-of-life dates for their EEs
- by providing release notes allowing automation teams to verify and correct their automation more pointedly.
- by identifying in controller the usage of old EE versions and ensuring their update
- by consequently removing outdated EE versions in PAH

This approach doesn't reduce the need for testing automation content against new EE versions, but it reduces the need for an heavy coordination.

CAUTION: to depend on the PATCH level makes the deployment of security updates difficult and should be restricted.
Inversely, depending on the `latest` tag can introduce unwanted incompatibilities as new EE versions are introduced.
A balance needs hence to be found between MINOR (less risk for incompatibilities) and MAJOR (less maintenance effort) dependencies.

[jeffcpullen]

Bumping this idea. This a complicated topic full of nuance and gotchas that if not considered early leads to hard dependencies that are difficult to untangle. There is not a one size fits all, but I think we can call out some gotchas and a middle of the road recommendation that will work in most situations.

Lets start with something easy ;)

Naming is always the hardest part, and there are going to be many situations where this example isn't the best fit. I still think it would be good to recommend a possible solution.

Execution Environment Naming

Here are some good practices to enable quick identification of the appropriate EE thanks to the tendency of tools to sort alphabetically.

1 - Standardized convention

Example: "the-quick-brown-fox-jumps-over-the-lazy-dog"

Execution environment names should follow a single naming convention such as Kebab-case.

2 - Identify it as an execution environment

Example: 'ee'

A consistent prefix such as 'ee' will make it simple to identify what container images were built as execution environments.

2 - Identify the organization responsible for it

Example: 'acme'

Custom execution environments that are not maintained publicly or by a vendor should be labeled up front to make the ownership plainly visible. Displaying the ownership of the EE prominently can reduce confusion over who is responsible for that EE, and who to contact if there are issues.

3 - Include a generic area of responsibility

Example: 'cloud'

This is a short name to describe the types of collections and tools that the EE is built to handle.

4 - Include specific areas of responsibility when needed

Example: 'images'

This provides an extra identifier for specific and edge use-cases. For example including build tools, out-of-date dependencies and custom code. Depending on the diversity of the organization, this may also be needed to differentiate between EE within a generic area of responsibility with different and/or conflicting dependencies.

5 - Identify the base operating system

Example 'win'

Having the base operating system included provides a quick way to identify the needed operating system, and simplifies the process of testing and deploying upgraded operating systems as they become available.

6 - Identify the python version

The version of python available will have an impact on the functionality of local and remote systems. It is very likely that different versions will be required for different use-cases. The python version should be identified to facilitate testing and release of different and newer versions.

7 - Identify the Ansible version

The version of Ansible impacts the availability of bundled content, compatibility and available features. This should be identified to facilitate the safe testing and release of newer versions.

8 - Example

• Container Type: Execution Environment
• Organization: Acme Corp.
• Generic Use Case: Networking
• Specific Use Case: Not applicable
• Base Operating System: Enterprise Linux 8
• Python Version: 3.11
• Ansible Version: 2.17

Container Name: ee-acme-network-el8-311-217

Tags

TODO