diff --git a/lib/ansible/modules/cloud/amazon/GUIDELINES.md b/lib/ansible/modules/cloud/amazon/GUIDELINES.md index 3c32126d53..0b3ffa41f7 100644 --- a/lib/ansible/modules/cloud/amazon/GUIDELINES.md +++ b/lib/ansible/modules/cloud/amazon/GUIDELINES.md @@ -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`.