Merge pull request #625 from willthames/aws_guidelines
Add GUIDELINES for AWS module development
This commit is contained in:
commit
0a22a3d708
1 changed files with 88 additions and 0 deletions
88
cloud/amazon/GUIDELINES.md
Normal file
88
cloud/amazon/GUIDELINES.md
Normal file
|
@ -0,0 +1,88 @@
|
|||
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.
|
Loading…
Reference in a new issue