cmueller/ansible
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Update AWS dev guides to use collections utils and fragments (#72312)

Browse source
This commit is contained in:
Mark Chappell 2021-04-27 14:04:49 +02:00 committed by GitHub
parent ddfc648d37
commit cf08c23b4f
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 13 additions and 12 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

25
docs/docsite/rst/dev_guide/platforms/aws_guidelines.rst
View file

@ -58,7 +58,7 @@ to:
.. code-block:: python .. code-block:: python
from ansible.module_utils.aws.core import AnsibleAWSModule from ansible_collections.amazon.aws.plugins.module_utils.core import AnsibleAWSModule
... ...
module = AnsibleAWSModule(...) module = AnsibleAWSModule(...)
@ -118,7 +118,8 @@ Unless the name of your service is quite unique, please consider using ``aws_``
Importing botocore and boto3 Importing botocore and boto3
---------------------------- ----------------------------
The ``ansible.module_utils.ec2`` module and ``ansible.module_utils.core.aws`` modules both The ``ansible_collections.amazon.aws.plugins.module_utils.ec2`` module and
``ansible_collections.amazon.aws.plugins.module_utils.core`` modules both
automatically import boto3 and botocore. If boto3 is missing from the system then the variable automatically import boto3 and botocore. If boto3 is missing from the system then the variable
``HAS_BOTO3`` will be set to false. Normally, this means that modules don't need to import ``HAS_BOTO3`` will be set to false. Normally, this means that modules don't need to import
boto3 directly. There is no need to check ``HAS_BOTO3`` when using AnsibleAWSModule boto3 directly. There is no need to check ``HAS_BOTO3`` when using AnsibleAWSModule
@ -126,7 +127,7 @@ as the module does that check:
.. code-block:: python .. code-block:: python
from ansible.module_utils.aws.core import AnsibleAWSModule from ansible_collections.amazon.aws.plugins.module_utils.core import AnsibleAWSModule
try: try:
import botocore import botocore
except ImportError: except ImportError:
@ -137,7 +138,7 @@ or:
.. code-block:: python .. code-block:: python
from ansible.module_utils.basic import AnsibleModule from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.ec2 import HAS_BOTO3 from ansible_collections.amazon.aws.plugins.module_utils.ec2 import HAS_BOTO3
try: try:
import botocore import botocore
except ImportError: except ImportError:
@ -220,8 +221,8 @@ and that the more esoteric connection options are documented. For example:
# some lines omitted here # some lines omitted here
requirements: [ 'botocore', 'boto3' ] requirements: [ 'botocore', 'boto3' ]
extends_documentation_fragment: extends_documentation_fragment:
- aws - amazon.aws.aws
- ec2 - amazon.aws.ec2
''' '''
Handling exceptions Handling exceptions
@ -234,7 +235,7 @@ are a number of possibilities for handling it.
``is_boto3_error_code``. ``is_boto3_error_code``.
* Use ``aws_module.fail_json_aws()`` to report the module failure in a standard way * Use ``aws_module.fail_json_aws()`` to report the module failure in a standard way
* Retry using AWSRetry * Retry using AWSRetry
* Use ``fail_json()`` to report the failure without using ``ansible.module_utils.aws.core`` * Use ``fail_json()`` to report the failure without using ``ansible_collections.amazon.aws.plugins.module_utils.core``
* Do something custom in the case where you know how to handle the exception * Do something custom in the case where you know how to handle the exception
For more information on botocore exception handling see the `botocore error documentation <https://botocore.readthedocs.io/en/latest/client_upgrades.html#error-handling>`_. For more information on botocore exception handling see the `botocore error documentation <https://botocore.readthedocs.io/en/latest/client_upgrades.html#error-handling>`_.
@ -242,7 +243,7 @@ For more information on botocore exception handling see the `botocore error docu
Using is_boto3_error_code Using is_boto3_error_code
------------------------- -------------------------
To use ``ansible.module_utils.aws.core.is_boto3_error_code`` to catch a single To use ``ansible_collections.amazon.aws.plugins.module_utils.core.is_boto3_error_code`` to catch a single
AWS error code, call it in place of ``ClientError`` in your except clauses. In AWS error code, call it in place of ``ClientError`` in your except clauses. In
this case, *only* the ``InvalidGroup.NotFound`` error code will be caught here, this case, *only* the ``InvalidGroup.NotFound`` error code will be caught here,
and any other error will be raised for handling elsewhere in the program. and any other error will be raised for handling elsewhere in the program.
@ -268,7 +269,7 @@ amounts of exception handling to existing modules, we recommend migrating the mo
.. code-block:: python .. code-block:: python
from ansible.module_utils.aws.core import AnsibleAWSModule from ansible_collections.amazon.aws.plugins.module_utils.core import AnsibleAWSModule
# Set up module parameters # Set up module parameters
# module params code here # module params code here
@ -302,8 +303,8 @@ If you need to perform an action based on the error boto3 returned, use the erro
except botocore.exceptions.BotoCoreError as e: except botocore.exceptions.BotoCoreError as e:
module.fail_json_aws(e, msg="Couldn't obtain frooble %s" % name) module.fail_json_aws(e, msg="Couldn't obtain frooble %s" % name)
using fail_json() and avoiding ansible.module_utils.aws.core using fail_json() and avoiding ansible_collections.amazon.aws.plugins.module_utils.core
------------------------------------------------------------ ---------------------------------------------------------------------------------------
Boto3 provides lots of useful information when an exception is thrown so pass this to the user Boto3 provides lots of useful information when an exception is thrown so pass this to the user
along with the message. along with the message.
@ -494,7 +495,7 @@ and returns True if they are different.
.. code-block:: python .. code-block:: python
from ansible.module_utils.ec2 import compare_policies from ansible_collections.amazon.aws.plugins.module_utils.ec2 import compare_policies
import json import json