diff --git a/cloud/amazon/GUIDELINES.md b/cloud/amazon/GUIDELINES.md index dbfd3ee1285..b8ca836b79a 100644 --- a/cloud/amazon/GUIDELINES.md +++ b/cloud/amazon/GUIDELINES.md @@ -211,6 +211,28 @@ except ClientError, e: module.fail_json(msg=e.message, **camel_dict_to_snake_dict(e.response)) ``` +### Returning Values + +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 some response metadata. It is OK to return this to +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 +helper function in module_utils/ec2.py called `camel_dict_to_snake_dict` 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 +value called 'SecretAccessKey' do not change it to 'AccessKey'. + +```python +# Make a call to AWS +result = connection.aws_call() + +# Return the result to the user +module.exit_json(changed=True, **camel_dict_to_snake_dict(result)) +``` + ### Helper functions Along with the connection functions in Ansible ec2.py module_utils, there are some other useful functions detailed below.