6b8c462d66
Starting point for a reference when doing pull request reviews. If something doesn't meet the guidelines we can point people at them. If something is bad but is not mentioned in the guidelines, we should add it here.
88 lines
2.3 KiB
Markdown
88 lines
2.3 KiB
Markdown
Guidelines for AWS modules
|
|
--------------------------
|
|
|
|
Naming your module
|
|
==================
|
|
|
|
Base the name of the module on the part of AWS that
|
|
you actually use. (A good rule of thumb is to take
|
|
whatever module you use with boto as a starting point).
|
|
|
|
Don't further abbreviate names - if something is a well
|
|
known abbreviation due to it being a major component of
|
|
AWS, that's fine, but don't create new ones independently
|
|
(e.g. VPC, ELB, etc. are fine)
|
|
|
|
Using boto
|
|
==========
|
|
|
|
Wrap the `import` statements in a try block and fail the
|
|
module later on if the import fails
|
|
|
|
```
|
|
try:
|
|
import boto
|
|
import boto.module.that.you.use
|
|
HAS_BOTO = True
|
|
except ImportError:
|
|
HAS_BOTO = False
|
|
|
|
<lots of code here>
|
|
|
|
def main():
|
|
argument_spec = ec2_argument_spec()
|
|
argument_spec.update(
|
|
dict(
|
|
module_specific_parameter=dict(),
|
|
)
|
|
)
|
|
|
|
module = AnsibleModule(
|
|
argument_spec=argument_spec,
|
|
)
|
|
if not HAS_BOTO:
|
|
module.fail_json(msg='boto required for this module')
|
|
```
|
|
|
|
|
|
Try and keep backward compatibility with relatively recent
|
|
versions of boto. That means that if want to implement some
|
|
functionality that uses a new feature of boto, it should only
|
|
fail if that feature actually needs to be run, with a message
|
|
saying which version of boto is needed.
|
|
|
|
Use feature testing (e.g. `hasattr('boto.module', 'shiny_new_method')`)
|
|
to check whether boto supports a feature rather than version checking
|
|
|
|
e.g. from the `ec2` module:
|
|
```
|
|
if boto_supports_profile_name_arg(ec2):
|
|
params['instance_profile_name'] = instance_profile_name
|
|
else:
|
|
if instance_profile_name is not None:
|
|
module.fail_json(
|
|
msg="instance_profile_name parameter requires Boto version 2.5.0 or higher")
|
|
```
|
|
|
|
|
|
Connecting to AWS
|
|
=================
|
|
|
|
For EC2 you can just use
|
|
|
|
```
|
|
ec2 = ec2_connect(module)
|
|
```
|
|
|
|
For other modules, you should use `get_aws_connection_info` and then
|
|
`connect_to_aws`. To connect to an example `xyz` service:
|
|
|
|
```
|
|
region, ec2_url, aws_connect_params = get_aws_connection_info(module)
|
|
xyz = connect_to_aws(boto.xyz, region, **aws_connect_params)
|
|
```
|
|
|
|
The reason for using `get_aws_connection_info` and `connect_to_aws`
|
|
(and even `ec2_connect` uses those under the hood) rather than doing it
|
|
yourself is that they handle some of the more esoteric connection
|
|
options such as security tokens and boto profiles.
|