From 785384bbc85196b9dd6699e03f19f92b9d1fedc4 Mon Sep 17 00:00:00 2001 From: Mark Chappell Date: Fri, 24 Jun 2022 09:38:39 +0200 Subject: [PATCH] Module naming guidelines (#881) Module naming guidelines SUMMARY Originally discussed in #610 Here's an initial attempt at some module naming (and module scoping) guidelines. Assuming we adopt this, I recommend is that: we can do the renames as part of 5.0.0, but this isn't a must and wouldn't be considered a blocker to 5.0.0 unless otherwise agreed. any modules moving from community.aws to amazon.aws would be renamed if appropriate as part of the move. we do not specify a deprecation date at this time, but leave a comment in the redirect that any deprecation cycle should not start before 2024-09-01 (to avoid potential migration fatigue issues), ISSUE TYPE Docs Pull Request COMPONENT NAME docs/docsite/rst/dev_guidelines.rst ADDITIONAL INFORMATION fixes: #610 Reviewed-by: Joseph Torcasso Reviewed-by: Jill R Reviewed-by: Markus Bergholz (cherry picked from commit 289e98702ef8258935167d5017b3ac040d93f30b) --- docs/docsite/rst/dev_guidelines.rst | 57 +++++++++++++++++++++++------ 1 file changed, 46 insertions(+), 11 deletions(-) diff --git a/docs/docsite/rst/dev_guidelines.rst b/docs/docsite/rst/dev_guidelines.rst index 3575db40940..0965ad05ec6 100644 --- a/docs/docsite/rst/dev_guidelines.rst +++ b/docs/docsite/rst/dev_guidelines.rst @@ -108,24 +108,59 @@ used by boto3) Creating new AWS modules ======================== -Use boto3 and AnsibleAWSModule -------------------------------- +When writing a new module it is important to think about the scope of the module. In general, try +to do one thing and do it well. -All new AWS modules must use boto3 and ``AnsibleAWSModule``. +Where the Amazon APIs provide a distinction between dependent resources, such as S3 buckets and S3 +objects, this is often a good divider between modules. Additionally, resources which have a +many-to-many relationship with another resource, such as IAM managed policies and IAM roles, are +often best managed by two separate modules. -``AnsibleAWSModule`` greatly simplifies exception handling and library -management, reducing the amount of boilerplate code. If you cannot -use ``AnsibleAWSModule`` as a base, you must document the reason and request an exception to this rule. +While it's possible to write an ``s3`` module which manages all things related to S3, thoroughly +testing and maintaining such a module is difficult. Similarly, while it would be possible to +write a module that manages the base EC2 security group resource, and a second module to manage the +rules on the security group, this would be contrary to what users of the module might anticipate. + +There is no hard and fast right answer, but it's important to think about it, and Amazon have often +done this work for you when designing their APIs. 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 of a major component of AWS (for example, VPC or ELB), that's fine, but -don't create new ones independently. +Module names should include the name of the resource being managed and be prefixed with the AWS API +that the module is based on. Where examples of a prefix don't already exist a good rule of thumb is +to use whatever client name you use with boto3 as a starting point. + +Unless something is a well known abbreviation of a major component of AWS (for example, VPC or ELB) +avoid further abbreviating names and don't create new abbreviations independently. + +Where an AWS API primarily manages a single resource, the module managing this resource can be +named as just the name of the API. However, consider using ``instance`` or ``cluster`` for clarity +if Amazon refers to them using these names. + +Examples: -Unless the name of your service is quite unique, please consider using ``aws_`` as a prefix. For example ``aws_lambda``. +- ``ec2_instance`` +- ``s3_object`` (previously named ``aws_s3``, but is primarily for manipulating S3 objects) +- ``elb_classic_lb`` (previously ``ec2_elb_lb``, but is part of the ELB API, not EC2) +- ``networkfirewall_rule_group`` +- ``networkfirewall`` (while this could be called ``networkfirewall_firewall`` the second firewall is redundant and the API is focused around creating these firewall resources) + +Note: Prior to the collections being split from Ansible Core, it was common to use ``aws_`` as a +prefix to disambiguate services with a generic name, such as ``aws_secret``. This is no longer +necessary, and the ``aws_`` prefix is reserved for services with a very broad effect where +referencing the AWS API might cause confusion. For example, ``aws_region_info``, which +connects to EC2 but provides global information about the regions enabled in an account for all +services. + +Use boto3 and AnsibleAWSModule +------------------------------- + +All new AWS modules must use boto3/botocore and ``AnsibleAWSModule``. + +``AnsibleAWSModule`` greatly simplifies exception handling and library +management, reducing the amount of boilerplate code. If you cannot +use ``AnsibleAWSModule`` as a base, you must document the reason and request an exception to this rule. Importing botocore and boto3 ----------------------------