* aws module Guidelines - rewrite - add AWS WG - add fail_json_aws - more modern
practices and fix some spelling
* aws module Guidelines - minor further changes with agressive fill to 99 width
* aws module Guidelines - formatting fix as per gundalow request
* aws module Guidelines - mark more keywords and code with backquotes
* AWS module guidelines - fixes from ryansb review + minor other changes
You should wrap any boto call in a try block. If an exception is thrown, it is up to you decide how to handle it
You should wrap any boto call in a try block. If an exception is thrown, it is up to you decide how
but usually calling fail_json with the error or helpful message and traceback will suffice.
to handle it but usually calling fail_json with the error or helpful message and traceback will
suffice.
#### boto
#### boto
@ -166,11 +180,64 @@ except BotoServerError as e:
**camel_dict_to_snake_dict(e.message))
**camel_dict_to_snake_dict(e.message))
```
```
#### boto3
### Exception Handling for boto3 and botocore
You should wrap any boto3 or botocore call in a try block. If an exception is thrown, then there
are a number of possibilities for handling it.
* use aws_module.fail_json_aws() to report the module failure in a standard way
* retry using AWSRetry
* use fail_json() to report the failure without using `ansible.module_utils.aws.core`
* 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](http://botocore.readthedocs.org/en/latest/client_upgrades.html#error-handling).
#### using fail_json_aws()
_fail_json_aws() is a new method and may be subject to change. You can use it in modules which are
being contributed back to Ansible, however if you are publishing your module separately please
don't use it before the start of 2018 / Ansible 2.4_
In the AnsibleAWSModule there is a special method, `module.fail_json.aws()` for nice reporting of
exceptions. Call this on your exception and it will report the error together with a traceback for
use in Ansible verbose mode.
```python
from ansible.module_utils.aws.core import HAS_BOTO3, AnsibleAWSModule
# Set up module parameters
...
# Connect to AWS
...
# Make a call to AWS
try:
result = connection.aws_call()
except Exception as e:
module.fail_json_aws(e, msg="trying to do aws_call")
```
Note that it should normally be acceptable to catch all normal exceptions here, however if you
expect anything other than botocore exceptions you should test everything works as expected.
If you need to perform an action based on the error boto3 returned, use the error code.
For more information on botocore exception handling see [http://botocore.readthedocs.org/en/latest/client_upgrades.html#error-handling]
```python
# Make a call to AWS
try:
result = connection.aws_call()
except ClientError, e:
if e.response['Error']['Code'] == 'NoSuchEntity':
return None
else:
module.fail_json_aws(e, msg="trying to do aws_call")
```
Boto3 provides lots of useful info when an exception is thrown so pass this to the user along with the message.
#### using fail_json() and avoiding ansible.module_utils.aws.core
Boto3 provides lots of useful information when an exception is thrown so pass this to the user
along with the message.
```python
```python
# Import ClientError from botocore
# Import ClientError from botocore
@ -207,17 +274,16 @@ except ClientError as e:
### Returning Values
### Returning Values
When you make a call using boto3, you will probably get back some useful information that you should return in the module.
When you make a call using boto3, you will probably get back some useful information that you
should return in the module. As well as information related to the call itself, you will also have
As well as information related to the call itself, you will also have some response metadata. It is OK to return this to
some response metadata. It is OK to return this to the user as well as they may find it useful.
the user as well as they may find it useful.
Boto3 returns all values CamelCased. Ansible follows Python standards for variable names and uses snake_case. There is a
Boto3 returns all values CamelCased. Ansible follows Python standards for variable names and uses
helper function in module_utils/ec2.py called `camel_dict_to_snake_dict` that allows you to easily convert the boto3
snake_case. There is a helper function in module_utils/ec2.py called `camel_dict_to_snake_dict`
response to snake_case.
that allows you to easily convert the boto3 response to snake_case.
You should use this helper function and avoid changing the names of values returned by Boto3. E.g. if boto3 returns a
You should use this helper function and avoid changing the names of values returned by Boto3.
value called 'SecretAccessKey' do not change it to 'AccessKey'.
E.g. if boto3 returns a value called 'SecretAccessKey' do not change it to 'AccessKey'.
mikedlr
7 years ago
committed by