mirror of https://github.com/ansible/ansible.git
You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
89 lines
2.3 KiB
Markdown
89 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.
|