Ansible Supported Collections, Versioning, and Release Strategy

Updated -

The following knowledgebase article provides supportability guidance for Ansible content that is fully supported as part of the Ansible Automation Platform subscription. These Ansible Content Collections are a subset of the larger certified Collection library housed on Ansible Automation Hub. Guidance is provided for support life cycles of content, versioning strategies, and differentiating feature releases (FR) from product maintenance releases (MR) as part of the subscription.

List of Red Hat Supported Maintained Ansible Collections

The following list of Ansible Collections are distributed and fully supported as part of the Ansible Automation Platform with updates distributed as part of Ansible Automation Hub:

Entity Collection Name Description First Supported FR Supported MRs
Amazon amazon.aws Amazon AWS 1.0.0 TBD
Ansible ansible.netcommon Ansible Netcommon 1.0.0 TBD
Ansible ansible.posix Ansible Posix 1.0.0 TBD
Ansible ansible.tower Ansible Tower 1.0.0 TBD
Arista arista.eos Arista EOS 1.0.0 TBD
Cisco cisco.asa Cisco ASA 1.0.0 TBD
Cisco cisco.ios Cisco IOS 1.0.0 TBD
Cisco cisco.iosxr Cisco IOS XR 1.0.0 TBD
Cisco cisco.nxos Cisco NX-OS 1.0.0 TBD
FRR frr.frr Free Range Routing 1.0.0 TBD
IBM ibm.qradar QRadar SIEM 1.0.0 TBD
Juniper Networks junipernetworks.junos JunOS 1.0.0 TBD
Kubernetes kubernetes.core Kubernetes Collection for Ansible. 1.1.1 TBD
OpenvSwitch openvswitch.openvswitch OpenvSwitch 1.0.0 TBD
Splunk splunk.es Enterprise Security SIEM 1.0.0 TBD
VyOS vyos.vyos VyOs 1.0.0 TBD

Release Rationale and Contributing

The following approach below strikes a balance between two historically competing goals by content developers:

  1. Ansible content developers desire to rapidly release new functionality and version collection releases based on a standards-based version specification without any support implication tied to the version number.

  2. Ansible content users desire to identify a production grade collection release that will receive bug and security fixes without breaking changes. Such a version should have a well defined support duration and the availability of such versions should overlap allowing for a window of transition.

With Ansible collections subsystem as fully supported for content, most content (modules, plugins, etc.) no longer needs to be stored in a single GitHub repository. Given that the content is now no longer in a single upstream repository, versioning is no longer the responsibility of Ansible, but now the responsibility of the content authors and maintainers. Furthermore, collections may be released at predictable intervals and cadences, while others may only be released if required. That being said, Ansible-maintained collections still welcome community contributions, but the criteria for inclusion may be higher than other community workgroups. Refer to the Ansible Community Guide's section on "Contributing to Ansible-maintained Collections" for more information on how to contribute upstream.

Collection Versioning Strategy

Each supported collection maintained by Ansible follows Semantic Versioning 2.0.0 (https://semver.org/), for example:
Given a version number MAJOR.MINOR.PATCH, the following is incremented:

  1. MAJOR version: when making incompatible API changes (see Feature Release scenarios below for examples)

  2. MINOR version: when adding features or functionality in a backwards compatible manner, or updating testing matrix and/or metadata (deprecation)

  3. PATCH version: when adding backwards compatible bug fixes or security fixes (strict).

Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

The first version of a generally available supported collection on Ansible Automation Hub shall be version 1.0.0. NOTE: By default, all newly created collections may begin with a smaller default version of 0.1.0, and therefore a version of 1.0.0 should be explicitly stated by the collection maintainer.

Supportability Metadata for Collections

Previously (prior to collections), supportability metadata was located in the module itself. Now that supportability is now at the collection-level, and new construct had to be created. Therefore, the /meta/runtime.yml file is utilized. This file contains information about deprecation, minimum/tested Ansible versions, and redirection rules for backwards compatibility in older Ansible releases.

NOTE: There is no longer any metadata associated with tagging collections as supported, certified, or community as was done in previous Ansible releases (2.9 and older). All content on Ansible Automation Hub is deemed certified with additional clarification for which entity fully supports the content. This knowledgebase entry details all Ansible-maintained content that is fully supported as part of the Ansible Automation Platform subscription. The larger set of certified content is detailed at the following knowledgebase article: https://access.redhat.com/articles/3642632.

Release Types

  • Feature Releases (FRs): (aka latest release) Feature releases are periodic in nature. For supported collections, the target release cadence for minor and major releases is 4 weeks. Feature release with a patch change can happen as needed. Feature releases are only supported until the next feature release is available.

  • Maintenance Releases (MRs): When an existing feature release of supported content is identified as a maintenance release, it will be supported with bug and security fixes for 24 months. Maintenance Releases are intended for customers with a desire to use a stable version of a collection for up to 24 months. Maintenance release will receive bug and security fixes for 24 month after identified. Maintenance Release will not receive new functionality or breaking changes.

  • Betas/Pre-releases: These releases are designed to satisfy developer workflow requirements and are not intended to be used in production environments.

Feature Release (FR) Scenarios

New content is added to an existing collection

Assuming the current release is 1.0.0, and a new module is ready to be added to the collection, the minor version would be incremented to 1.1.0. The change in the MINOR version indicates an additive change was made while maintaining backward compatibility for existing content within the collection.

New feature to existing plugin or role within a collection (backwards compatible)

Assuming the current release is 1.0.0, and new features for an existing module are ready for release . We would increment the MINOR version to 1.1.0. The change in the MINOR version indicates an additive change was made while maintaining backward compatibility for existing content within the collection.

Bug fix or security fix to existing content within a collection

Assuming the current release is 1.0.0 and a bug is fixed prior to the next minor release, the PATCH version would be incremented to 1.0.1. The patch indicates only a bug was fixed within a current version. The PATCH release does not contain new content, nor was functionality removed. Bug fixes may be included in a MINOR or MAJOR feature release if the timing allows, eliminating the need for a PATCH dedicated to the fix.

Breaking change to any content within a collection

Assuming the current release is 1.0.0, and a breaking change (API or module) is introduced for a user or developer. The MAJOR version would be incremented to 2.0.0.

Examples of breaking changes within a collection may include but are not limited to:

  • Argspec changes for a module that require either inventory structure or playbook changes.

  • A change in the shape of either the inbound or returned payload of a filter plugin.

  • Changes to a connection plugin that require additional inventory parameters or ansible.cfg entries.

  • New functionality added to a module that changes the outcome of that module as released in previous versions.

  • The removal of plugins from a collection.

Content removed from a collection

Deleting a module or API is a breaking change. Please see the ‘Breaking change (any) section for how to version this.

A typographical error was fixed in the documentation for a collection

A correction to the README would be considered a bug fix and the PATCH incremented. See ‘Bug fix’ above.

Documentation added/removed/modified within a collection

Only the PATCH version should be increased for a release that contains changes limited to revised documentation.

Maintenance Release (MR) Scenarios

The support plan for product and supported collections needs to be available to Ansible customers.
Every ~18 months an existing Feature Release version will be identified as a Maintenance Release. An MR version of a collection will only receive bug and security fixes.

  • The supported ansible-base version of an MR collection release will not change. Care needs to be taken to ensure a MR does not require an unsupported version of ansible-base. If faced with this situation, a MR release may need to be identified prior to the 18 month target.

  • MR collection versions will not receive new functionality, unless required for a bug or security fix.

  • The asserted host or downstream device’s supported version claimed by an MR collection version will not change.

  • A MR collection release will be supported for 2 years. This allows for a maximum 6 month window for a customer to transition between MR versions of a collection.

  • MR collection releases are only guaranteed to be available on Automation hub.

  • An MR collection version is identified by a unique, non changing MAJOR.MINOR. This leaves the PATCH available for security and bug related fixes.

  • When a customer identifies a MR collection version is locked to an unsupported or now unavailable dependency, this will be addressed on a case by case basis, with the general approach being to encourage the customer to use a later version of the collection.

Alphas, Betas and Other Pre-GA Releases

If there are pre-release or Beta versions of collections needing versioning, please utilize the hyphen in the version when leading up to a release as specified by the semver specification. For example: 2.0.0-rc.1 would precede the final 2.0.0 version. 0.1.3-1 would precede the 0.1.3 release.