Skip to content

Commit

Permalink
[aws][docs] Add AnsibleAWSModule features to AWS developer guidelines (
Browse files Browse the repository at this point in the history
  • Loading branch information
ryansb authored Apr 26, 2018
1 parent cd39b82 commit 33f3583
Showing 1 changed file with 51 additions and 1 deletion.
52 changes: 51 additions & 1 deletion lib/ansible/modules/cloud/amazon/GUIDELINES.md
Original file line number Diff line number Diff line change
@@ -43,6 +43,30 @@ Few other changes are required. One possible issue that you might encounter is t
does not inherit methods from AnsibleModule by default, but most useful methods
are included. If you do find an issue, please raise a bug report.

When porting, keep in mind that AnsibleAWSModule also will add the default ec2
argument spec by default. In pre-port modules, you should see common arguments
specfied with:

```
def main():
argument_spec = ec2_argument_spec()
argument_spec.update(dict(
state=dict(default='present', choices=['present', 'absent', 'enabled', 'disabled']),
name=dict(default='default'),
# ... and so on ...
))
module = AnsibleModule(argument_spec=argument_spec, ...)
# can be replaced with
def main():
argument_spec = dict(
state=dict(default='present', choices=['present', 'absent', 'enabled', 'disabled']),
name=dict(default='default'),
# ... and so on ...
)
module = AnsibleAWSModule(argument_spec=argument_spec, ...)
```

## Bug fixing

Bug fixes to code that relies on boto will still be accepted. When possible, the code should be
@@ -350,6 +374,32 @@ def describe_some_resource(client, module):
module.fail_json_aws(e, msg="Could not describe resource %s" % name)
```

To make use of AWSRetry easier, it can now be wrapped around a client returned
by `AnsibleAWSModule`. any call from a client. To add retries to a client,
create a client:

```
module.client('ec2', retry_decorator=AWSRetry.jittered_backoff(retries=10))
```

Any calls from that client can be made to use the decorator passed at call-time
using the `aws_retry` argument. By default, no retries are used.

```
ec2 = module.client('ec2', retry_decorator=AWSRetry.jittered_backoff(retries=10))
ec2.describe_instances(InstanceIds=['i-123456789'], aws_retry=True)
# equivalent with normal AWSRetry
@AWSRetry.jittered_backoff(retries=10)
def describe_instances(client, **kwargs):
return ec2.describe_instances(**kwargs)
describe_instances(module.client('ec2'), InstanceIds=['i-123456789'])
```

The call will be retried the specified number of times, so the calling functions
don't need to be wrapped in the backoff decorator.

### Returning Values

When you make a call using boto3, you will probably get back some useful information that you
@@ -439,7 +489,7 @@ Ansible format, this function will convert the keys to snake_case.
keys not to convert (this is usually useful for the `tags` dict, whose child keys should remain with
case preserved)

Another optional parameter is `reversible`. By default, `HTTPEndpoint` is converted to `http_endpoint`,
Another optional parameter is `reversible`. By default, `HTTPEndpoint` is converted to `http_endpoint`,
which would then be converted by `snake_dict_to_camel_dict` to `HttpEndpoint`.
Passing `reversible=True` converts HTTPEndpoint to `h_t_t_p_endpoint` which converts back to `HTTPEndpoint`.

0 comments on commit 33f3583

Please sign in to comment.