cmueller/ansible
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

updated guidelines to reflect boto3 preference

Browse source
This commit is contained in:
Brian Coca 2017-02-21 20:22:47 -05:00 committed by Brian Coca
parent 75d7c70e70
commit 4bdaf6a4f0
1 changed files with 10 additions and 18 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

28
lib/ansible/modules/cloud/amazon/GUIDELINES.md
View file

@ -4,16 +4,11 @@
Since Ansible 2.0, it is a requirement that all new AWS modules are written to use boto3. Since Ansible 2.0, it is a requirement that all new AWS modules are written to use boto3.
Prior to 2.0, modules may of been written in boto or boto3. Modules written using boto can continue to be extended using boto. Prior to 2.0, modules may of been written in boto or boto3. The effort to port all modules to boto3 has begun.
Backward compatibility of older modules must be maintained.
## Bug fixing ## Bug fixing
If you are writing a bugfix for a module that uses boto, you should continue to use boto to maintain backward compatibility. When possible the code should be ported to use boto3, bug fixes to code that relies on boto will still be accepted.
If you are adding new functionality to an existing module that uses boto but the new functionality requires boto3, you
must maintain backward compatibility of the module and ensure the module still works without boto3.
## Naming your module ## Naming your module
@ -29,13 +24,13 @@ AWS, that's fine, but don't create new ones independently
## Adding new features ## Adding new features
Try and keep backward compatibility with relatively recent Try and keep backward compatibility with relatively recent
versions of boto. That means that if want to implement some versions of boto3. That means that if want to implement some
functionality that uses a new feature of boto, it should only functionality that uses a new feature of boto3, it should only
fail if that feature actually needs to be run, with a message fail if that feature actually needs to be run, with a message
saying which version of boto is needed. saying which version of boto3 is needed.
Use feature testing (e.g. `hasattr('boto.module', 'shiny_new_method')`) Use feature testing (e.g. `hasattr('boto3.module', 'shiny_new_method')`)
to check whether boto supports a feature rather than version checking to check whether boto3 supports a feature rather than version checking
e.g. from the `ec2` module: e.g. from the `ec2` module:
```python ```python
@ -85,8 +80,7 @@ def main():
#### boto and boto3 combined #### boto and boto3 combined
If you want to add boto3 functionality to a module written using boto, you must maintain backward compatibility. Ensure that you clearly document if a new parameter requires requires a specific version. Import boto3 at the top of the
Ensure that you clearly document if a new parameter requires boto3. Import boto3 at the top of the
module as normal and then use the HAS_BOTO3 bool when necessary, before the new feature. module as normal and then use the HAS_BOTO3 bool when necessary, before the new feature.
```python ```python
@ -111,11 +105,9 @@ if my_new_feauture_Parameter_is_set:
### Connecting to AWS ### Connecting to AWS
To connect to AWS, you should use `get_aws_connection_info` and then To connect to AWS, you should use `get_aws_connection_info` and then `boto3_conn`.
`boto3_conn` (or `connect_to_aws` for boto).
These functions handle some of the more esoteric connection options, such as security tokens and These functions handle some of the more esoteric connection options, such as security tokens and boto profiles.
boto profiles.
Some boto services require that the region is specified. You should check for the region parameter if required. Some boto services require that the region is specified. You should check for the region parameter if required.