Merge pull request #6913 from willthames/aws_module_doc_fragments

Use common module document fragments for AWS modules

lib/ansible/utils/module_docs_fragments/aws.py

@@ -0,0 +1,76 @@
+# (c) 2014, Will Thames <will@thames.id.au>
+#
+# This file is part of Ansible
+#
+# Ansible is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Ansible is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+
+
+class ModuleDocFragment(object):
+
+    # AWS only documentation fragment
+    DOCUMENTATION = """
+options:
+  ec2_url:
+    description:
+      - Url to use to connect to EC2 or your Eucalyptus cloud (by default the module will use EC2 endpoints).  Must be specified if region is not used. If not set then the value of the EC2_URL environment variable, if any, is used
+    required: false
+    default: null
+    aliases: []
+  aws_secret_key:
+    description:
+      - AWS secret key. If not set then the value of the AWS_SECRET_KEY environment variable is used. 
+    required: false
+    default: null
+    aliases: [ 'ec2_secret_key', 'secret_key' ]
+  aws_access_key:
+    description:
+      - AWS access key. If not set then the value of the AWS_ACCESS_KEY environment variable is used.
+    required: false
+    default: null
+    aliases: [ 'ec2_access_key', 'access_key' ]
+  validate_certs:
+    description:
+      - When set to "no", SSL certificates will not be validated for boto versions >= 2.6.0.
+    required: false
+    default: "yes"
+    choices: ["yes", "no"]
+    aliases: []
+    version_added: "1.5"
+  profile:
+    description:
+      - uses a boto profile. Only works with boto >= 2.24.0
+    required: false
+    default: null
+    aliases: []
+    version_added: "1.6"
+  security_token:
+    description:
+      - security token to authenticate against AWS
+    required: false
+    default: null
+    aliases: []
+    version_added: "1.6"
+requirements:
+  - boto
+notes:
+  - The following environment variables can be used C(AWS_ACCESS_KEY) or 
+    C(EC2_ACCESS_KEY) or C(AWS_ACCESS_KEY_ID),
+    C(AWS_SECRET_KEY) or C(EC2_SECRET_KEY) or C(AWS_SECRET_ACCESS_KEY), 
+    C(AWS_REGION) or C(EC2_REGION), C(AWS_SECURITY_TOKEN)
+  - Ansible uses the boto configuration file (typically ~/.boto) if no
+    credentials are provided. See http://boto.readthedocs.org/en/latest/boto_config_tut.html 
+  - C(AWS_REGION) or C(EC2_REGION) can be typically be used to specify the 
+    AWS region, when required, but
+    this can also be configured in the boto config file
+"""

library/cloud/ec2

@@ -110,24 +110,6 @@ options:
       - how long to wait for the spot instance request to be fulfilled
     default: 600
     aliases: []
-  ec2_url:
-    description:
-      - Url to use to connect to EC2 or your Eucalyptus cloud (by default the module will use EC2 endpoints).  Must be specified if region is not used. If not set then the value of the EC2_URL environment variable, if any, is used
-    required: false
-    default: null
-    aliases: []
-  aws_secret_key:
-    description:
-      - AWS secret key. If not set then the value of the AWS_SECRET_KEY environment variable is used. 
-    required: false
-    default: null
-    aliases: [ 'ec2_secret_key', 'secret_key' ]
-  aws_access_key:
-    description:
-      - AWS access key. If not set then the value of the AWS_ACCESS_KEY environment variable is used.
-    required: false
-    default: null
-    aliases: [ 'ec2_access_key', 'access_key' ]
   count:
     description:
       - number of instances to launch
@@ -237,31 +219,9 @@ options:
     required: false
     default: null
     aliases: []
-  validate_certs:
-    description:
-      - When set to "no", SSL certificates will not be validated for boto versions >= 2.6.0.
-    required: false
-    default: "yes"
-    choices: ["yes", "no"]
-    aliases: []
-    version_added: "1.5"
-  profile:
-    description:
-      - uses a boto profile. Only works with boto >= 2.24.0
-    required: false
-    default: null
-    aliases: []
-    version_added: "1.6"
-  security_token:
-    description:
-      - security token to authenticate against AWS
-    required: false
-    default: null
-    aliases: []
-    version_added: "1.6"
 
-requirements: [ "boto" ]
 author: Seth Vidal, Tim Gerla, Lester Wade
+extends_documentation_fragment: aws
 '''
 
 EXAMPLES = '''

library/cloud/ec2_ami

@@ -22,24 +22,6 @@ short_description: create or destroy an image in ec2, return imageid
 description:
      - Creates or deletes ec2 images. This module has a dependency on python-boto >= 2.5
 options:
-  ec2_url:
-    description:
-      - Url to use to connect to EC2 or your Eucalyptus cloud (by default the module will use EC2 endpoints).  Must be specified if region is not used. If not set then the value of the EC2_URL environment variable, if any, is used
-    required: false
-    default: null
-    aliases: []
-  aws_secret_key:
-    description:
-      - AWS secret key. If not set then the value of the AWS_SECRET_KEY environment variable is used. 
-    required: false
-    default: null
-    aliases: [ 'ec2_secret_key', 'secret_key' ]
-  aws_access_key:
-    description:
-      - AWS access key. If not set then the value of the AWS_ACCESS_KEY environment variable is used.
-    required: false
-    default: null
-    aliases: ['ec2_access_key', 'access_key' ]
   instance_id:
     description:
       - instance id of the image to create
@@ -101,31 +83,9 @@ options:
     required: false
     default: null
     aliases: []
-  validate_certs:
-    description:
-      - When set to "no", SSL certificates will not be validated for boto versions >= 2.6.0.
-    required: false
-    default: "yes"
-    choices: ["yes", "no"]
-    aliases: []
-    version_added: "1.5"
-  profile:
-    description:
-      - uses a boto profile. Only works with boto >= 2.24.0
-    required: false
-    default: null
-    aliases: []
-    version_added: "1.6"
-  security_token:
-    description:
-      - security token to authenticate against AWS
-    required: false
-    default: null
-    aliases: []
-    version_added: "1.6"
 
-requirements: [ "boto" ]
 author: Evan Duffield <eduffield@iacquire.com>
+extends_documentation_fragment: aws
 '''
 
 # Thank you to iAcquire for sponsoring development of this module.

library/cloud/ec2_asg

@@ -22,7 +22,6 @@ description:
   - Can create or delete AWS Autoscaling Groups
   - Works with the ec2_lc module to manage Launch Configurations
 version_added: "1.6"
-requirements: [ "boto" ]
 author: Gareth Rushgrove
 options:
   state:
@@ -58,18 +57,6 @@ options:
     description:
       - Desired number of instances in group
     required: false
-  aws_secret_key:
-    description:
-      - AWS secret key. If not set then the value of the AWS_SECRET_KEY environment variable is used.
-    required: false
-    default: None
-    aliases: ['ec2_secret_key', 'secret_key' ]
-  aws_access_key:
-    description:
-      - AWS access key. If not set then the value of the AWS_ACCESS_KEY environment variable is used.
-    required: false
-    default: None
-    aliases: ['ec2_access_key', 'access_key' ]
   region:
     description:
       - The AWS region to use. If not specified then the value of the EC2_REGION environment variable, if any, is used.
@@ -80,6 +67,7 @@ options:
       - List of VPC subnets to use
     required: false
     default: None
+extends_documentation_fragment: aws
 """
 
 EXAMPLES = '''

library/cloud/ec2_eip

@@ -23,24 +23,6 @@ options:
     required: false
     choices: ['present', 'absent']
     default: present
-  ec2_url:
-    description:
-      - URL to use to connect to EC2-compatible cloud (by default the module will use EC2 endpoints)
-    required: false
-    default: null
-    aliases: [ EC2_URL ]
-  ec2_access_key:
-    description:
-      - EC2 access key. If not specified then the EC2_ACCESS_KEY environment variable is used.
-    required: false
-    default: null
-    aliases: [ EC2_ACCESS_KEY ]
-  ec2_secret_key:
-    description:
-      - EC2 secret key. If not specified then the EC2_SECRET_KEY environment variable is used.
-    required: false
-    default: null
-    aliases: [ EC2_SECRET_KEY ]
   region:
     description:
       - the EC2 region to use
@@ -53,28 +35,6 @@ options:
     required: false
     default: false
     version_added: "1.4"
-  validate_certs:
-    description:
-      - When set to "no", SSL certificates will not be validated for boto versions >= 2.6.0.
-    required: false
-    default: "yes"
-    choices: ["yes", "no"]
-    aliases: []
-    version_added: "1.5"
-  profile:
-    description:
-      - uses a boto profile. Only works with boto >= 2.24.0
-    required: false
-    default: null
-    aliases: []
-    version_added: "1.6"
-  security_token:
-    description:
-      - security token to authenticate against AWS
-    required: false
-    default: null
-    aliases: []
-    version_added: "1.6"
   reuse_existing_ip_allowed:
     description:
       - Reuse an EIP that is not associated to an instance (when available), instead of allocating a new one.
@@ -82,7 +42,7 @@ options:
     default: false
     version_added: "1.6"
 
-requirements: [ "boto" ]
+extends_documentation_fragment: aws
 author: Lorin Hochstein <lorin@nimbisservices.com>
 notes:
    - This module will return C(public_ip) on success, which will contain the

library/cloud/ec2_group

@@ -37,24 +37,6 @@ options:
     required: false
     default: null
     aliases: []
-  ec2_url:
-    description:
-      - Url to use to connect to EC2 or your Eucalyptus cloud (by default the module will use EC2 endpoints)
-    required: false
-    default: null
-    aliases: []
-  ec2_secret_key:
-    description:
-      - EC2 secret key
-    required: false
-    default: null
-    aliases: ['aws_secret_key']
-  ec2_access_key:
-    description:
-      - EC2 access key
-    required: false
-    default: null
-    aliases: ['aws_access_key']
   state:
     version_added: "1.4"
     description:
@@ -62,30 +44,8 @@ options:
     required: false
     default: 'present'
     aliases: []
-  validate_certs:
-    description:
-      - When set to "no", SSL certificates will not be validated for boto versions >= 2.6.0.
-    required: false
-    default: "yes"
-    choices: ["yes", "no"]
-    aliases: []
-    version_added: "1.5"
-  profile:
-    description:
-      - uses a boto profile. Only works with boto >= 2.24.0
-    required: false
-    default: null
-    aliases: []
-    version_added: "1.6"
-  security_token:
-    description:
-      - security token to authenticate against AWS
-    required: false
-    default: null
-    aliases: []
-    version_added: "1.6"
 
-requirements: [ "boto" ]
+extends_documentation_fragment: aws
 
 notes:
   - If a rule declares a group_name and that group doesn't exist, it will be

library/cloud/ec2_key

@@ -24,52 +24,12 @@ options:
     required: false
     default: null
     aliases: []
-  ec2_url:
-    description:
-      - Url to use to connect to EC2 or your Eucalyptus cloud (by default the module will use EC2 endpoints)
-    required: false
-    default: null
-    aliases: []
-  ec2_secret_key:
-    description:
-      - EC2 secret key
-    required: false
-    default: null
-    aliases: ['aws_secret_key', 'secret_key']
-  ec2_access_key:
-    description:
-      - EC2 access key
-    required: false
-    default: null
-    aliases: ['aws_access_key', 'access_key']
   state:
     description:
       - create or delete keypair
     required: false
     default: 'present'
     aliases: []
-  validate_certs:
-    description:
-      - When set to "no", SSL certificates will not be validated for boto versions >= 2.6.0.
-    required: false
-    default: "yes"
-    choices: ["yes", "no"]
-    aliases: []
-    version_added: "1.5"
-  profile:
-    description:
-      - uses a boto profile. Only works with boto >= 2.24.0
-    required: false
-    default: null
-    aliases: []
-    version_added: "1.6"
-  security_token:
-    description:
-      - security token to authenticate against AWS
-    required: false
-    default: null
-    aliases: []
-    version_added: "1.6"
   wait:
     description:
       - Wait for the specified action to complete before returning.
@@ -85,7 +45,7 @@ options:
     aliases: []
     version_added: "1.6"
 
-requirements: [ "boto" ]
+extends_documentation_fragment: aws
 author: Vincent Viallet
 '''
 

library/cloud/ec2_lc

@@ -22,7 +22,6 @@ description:
   - Can create or delete AwS Autoscaling Configurations
   - Works with the ec2_asg module to manage Autoscaling Groups
 version_added: "1.6"
-requirements: [ "boto" ]
 author: Gareth Rushgrove
 options:
   state:
@@ -46,18 +45,6 @@ options:
     description:
       - A list of security groups into which instances should be found
     required: false
-  aws_secret_key:
-    description:
-      - AWS secret key. If not set then the value of the AWS_SECRET_KEY environment variable is used.
-    required: false
-    default: None
-    aliases: ['ec2_secret_key', 'secret_key' ]
-  aws_access_key:
-    description:
-      - AWS access key. If not set then the value of the AWS_ACCESS_KEY environment variable is used.
-    required: false
-    default: None
-    aliases: ['ec2_access_key', 'access_key' ]
   region:
     description:
       - The AWS region to use. If not specified then the value of the EC2_REGION environment variable, if any, is used.
@@ -75,6 +62,7 @@ options:
     required: false
     default: null
     aliases: []
+extends_documentation_fragment: aws
 """
 
 EXAMPLES = '''

library/cloud/ec2_metric_alarm

@@ -21,7 +21,6 @@ description:
  - Can create or delete AWS metric alarms
  - Metrics you wish to alarm on must already exist
 version_added: "1.6"
-requirements: [ "boto" ]
 author: Zacharie Eakin
 options:
     state:
@@ -91,6 +90,7 @@ options:
         description:
           - A list of the names of action(s) to take when the alarm is in the 'ok' status
         required: false
+extends_documentation_fragment: aws
 """
 
 EXAMPLES = '''

library/cloud/ec2_scaling_policy

@@ -7,7 +7,6 @@ description:
   - Can create or delete scaling policies for autoscaling groups
   - Referenced autoscaling groups must already exist
 version_added: "1.6"
-requirements: [ "boto" ]
 author: Zacharie Eakin
 options:
   state:
@@ -40,6 +39,7 @@ options:
     description:
       - The minimum period of time between which autoscaling actions can take place
     required: false
+extends_documentation_fragment: aws
 """
 
 EXAMPLES = '''

library/cloud/ec2_snapshot

@@ -22,24 +22,6 @@ description:
     - creates an EC2 snapshot from an existing EBS volume
 version_added: "1.5"
 options:
-  ec2_secret_key:
-    description:
-      - AWS secret key. If not set then the value of the AWS_SECRET_KEY environment variable is used. 
-    required: false
-    default: None
-    aliases: ['aws_secret_key', 'secret_key' ]
-  ec2_access_key:
-    description:
-      - AWS access key. If not set then the value of the AWS_ACCESS_KEY environment variable is used.
-    required: false
-    default: None
-    aliases: ['aws_access_key', 'access_key' ]
-  ec2_url:
-    description:
-      - Url to use to connect to EC2 or your Eucalyptus cloud (by default the module will use EC2 endpoints).  Must be specified if region is not used. If not set then the value of the EC2_URL environment variable, if any, is used
-    required: false
-    default: null
-    aliases: []
   region:
     description:
       - The AWS region to use. If not specified then the value of the EC2_REGION environment variable, if any, is used.
@@ -70,23 +52,9 @@ options:
     required: false
     default: null
     aliases: []
-  profile:
-    description:
-      - uses a boto profile. Only works with boto >= 2.24.0
-    required: false
-    default: null
-    aliases: []
-    version_added: "1.6"
-  security_token:
-    description:
-      - security token to authenticate against AWS
-    required: false
-    default: null
-    aliases: []
-    version_added: "1.6"
 
-requirements: [ "boto" ]
 author: Will Thames
+extends_documentation_fragment: aws
 '''
 
 EXAMPLES = '''

library/cloud/ec2_tag

@@ -41,49 +41,9 @@ options:
     required: false
     default: null
     aliases: ['aws_region', 'ec2_region']
-  aws_secret_key:
-    description:
-      - AWS secret key. If not set then the value of the AWS_SECRET_KEY environment variable is used. 
-    required: false
-    default: None
-    aliases: ['ec2_secret_key', 'secret_key' ]
-  aws_access_key:
-    description:
-      - AWS access key. If not set then the value of the AWS_ACCESS_KEY environment variable is used.
-    required: false
-    default: None
-    aliases: ['ec2_access_key', 'access_key' ]
-  ec2_url:
-    description:
-      - Url to use to connect to EC2 or your Eucalyptus cloud (by default the module will use EC2 endpoints).  Must be specified if region is not used. If not set then the value of the EC2_URL environment variable, if any, is used.
-    required: false
-    default: null
-    aliases: []
-  validate_certs:
-    description:
-      - When set to "no", SSL certificates will not be validated for boto versions >= 2.6.0.
-    required: false
-    default: "yes"
-    choices: ["yes", "no"]
-    aliases: []
-    version_added: "1.5"
-  profile:
-    description:
-      - uses a boto profile. Only works with boto >= 2.24.0
-    required: false
-    default: null
-    aliases: []
-    version_added: "1.6"
-  security_token:
-    description:
-      - security token to authenticate against AWS
-    required: false
-    default: null
-    aliases: []
-    version_added: "1.6"
 
-requirements: [ "boto" ]
 author: Lester Wade
+extends_documentation_fragment: aws
 '''
 
 EXAMPLES = '''

library/cloud/ec2_vol

@@ -22,24 +22,6 @@ description:
     - creates an EBS volume and optionally attaches it to an instance.  If both an instance ID and a device name is given and the instance has a device at the device name, then no volume is created and no attachment is made.  This module has a dependency on python-boto.
 version_added: "1.1"
 options:
-  aws_secret_key:
-    description:
-      - AWS secret key. If not set then the value of the AWS_SECRET_KEY environment variable is used. 
-    required: false
-    default: None
-    aliases: ['ec2_secret_key', 'secret_key' ]
-  aws_access_key:
-    description:
-      - AWS access key. If not set then the value of the AWS_ACCESS_KEY environment variable is used.
-    required: false
-    default: None
-    aliases: ['ec2_access_key', 'access_key' ]
-  ec2_url:
-    description:
-      - Url to use to connect to EC2 or your Eucalyptus cloud (by default the module will use EC2 endpoints).  Must be specified if region is not used. If not set then the value of the EC2_URL environment variable, if any, is used
-    required: false
-    default: null
-    aliases: []
   instance:
     description:
       - instance ID if you wish to attach the volume. 
@@ -105,20 +87,6 @@ options:
     choices: ["yes", "no"]
     aliases: []
     version_added: "1.5"
-  profile:
-    description:
-      - uses a boto profile. Only works with boto >= 2.24.0
-    required: false
-    default: null
-    aliases: []
-    version_added: "1.6"
-  security_token:
-    description:
-      - security token to authenticate against AWS
-    required: false
-    default: null
-    aliases: []
-    version_added: "1.6"
   state:
     description: 
       - whether to ensure the volume is present or absent
@@ -126,8 +94,8 @@ options:
     default: present
     choices: ['absent', 'present']
     version_added: "1.6"
-requirements: [ "boto" ]
 author: Lester Wade
+extends_documentation_fragment: aws
 '''
 
 EXAMPLES = '''