Update AWS guides with new SDK and Python requirements (#74585)

The 2.0 collection releases will introduce new Python requirements
and a new SDK support policy
This commit is contained in:
Jill R 2021-05-14 08:35:45 -07:00 committed by GitHub
parent 173d0a8de7
commit fa15d35cb1
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 46 additions and 2 deletions

View file

@ -9,6 +9,47 @@ The Ansible AWS collection (on `Galaxy <https://galaxy.ansible.com/community/aws
.. contents::
:local:
Requirements
============
Python Compatibility
--------------------
AWS content in Ansible 2.9 and 1.x collection releases supported Python 2.7 and newer.
Starting with the 2.0 releases of both collections, Python 2.7 support will be ended in accordance with AWS' `end of Python 2.7 support <https://aws.amazon.com/blogs/developer/announcing-end-of-support-for-python-2-7-in-aws-sdk-for-python-and-aws-cli-v1/>`_. Contributions to both collections that target the 2.0 or later collection releases can be written to support Python 3.6+ syntax.
SDK Version Support
-------------------
Starting with the 2.0 releases of both collections, it is generally the policy to support the versions of botocore and boto3 that were released 12 months prior to the most recent major collection release, following semantic versioning (for example, 2.0.0, 3.0.0).
Features and functionality that require newer versions of the SDK can be contributed provided they are noted in the module documentation:
.. code-block:: yaml
DOCUMENTATION = '''
---
module: ec2_vol
options:
throughput:
description:
- Volume throughput in MB/s.
- This parameter is only valid for gp3 volumes.
- Valid range is from 125 to 1000.
- Requires at least botocore version 1.19.27.
type: int
version_added: 1.4.0
And handled using the ``botocore_at_least`` helper method:
.. code-block:: python
if module.params.get('throughput'):
if not module.botocore_at_least("1.19.27"):
module.fail_json(msg="botocore >= 1.19.27 is required to set the throughput for a volume")
Maintaining existing modules
============================
@ -154,7 +195,7 @@ Supporting Module Defaults
The existing AWS modules support using :ref:`module_defaults <module_defaults>` for common
authentication parameters. To do the same for your new module, add an entry for it in
``lib/ansible/config/module_defaults.yml``. These entries take the form of:
``meta/runtime.yml``. These entries take the form of:
.. code-block:: yaml

View file

@ -11,7 +11,10 @@ section is to explain how to put Ansible modules together (and use inventory scr
Requirements for the AWS modules are minimal.
All of the modules require and are tested against recent versions of boto, usually boto3. Check the module documentation for the minimum required version for each module. You must have the boto3 Python module installed on your control machine. You may also need the original boto package. You can install these modules from your OS distribution or using the python package installer: ``pip install boto3``.
All of the modules require and are tested against recent versions of botocore and boto3. Starting with the 2.0 AWS collection releases, it is generally the policy of the collections to support the versions of these libraries released 12 months prior to the most recent major collection revision. Individual modules may require a more recent library version to support specific features or may require the boto library, check the module documentation for the minimum required version for each module. You must have the boto3 Python module installed on your control machine. You can install these modules from your OS distribution or using the python package installer: ``pip install boto3``.
Starting with the 2.0 releases of both collections, Python 2.7 support will be ended in accordance with AWS' `end of Python 2.7 support <https://aws.amazon.com/blogs/developer/announcing-end-of-support-for-python-2-7-in-aws-sdk-for-python-and-aws-cli-v1/>`_ and Python 3.6 or greater will be required.
Whereas classically Ansible will execute tasks in its host loop against multiple remote machines, most cloud-control steps occur on your local machine with reference to the regions to control.