Moved AWS modules over to common module fragments

Created common module doc fragment, and applied to all modules that use ec2_connect or connect_to_aws as they definitely share the common doc fragments
2024-09-14 20:13:21 +02:00 · 2014-04-09 16:43:55 +10:00 · 2014-04-09 16:43:55 +10:00 · 509561f658
commit 509561f658
parent 5ce6c86595
13 changed files with 88 additions and 340 deletions
--- a/lib/ansible/utils/module_docs_fragments/aws.py
+++ b/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
+"""
--- a/library/cloud/ec2
+++ b/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 = '''
--- a/library/cloud/ec2_ami
+++ b/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.
--- a/library/cloud/ec2_asg
+++ b/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 = '''
--- a/library/cloud/ec2_eip
+++ b/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
--- a/library/cloud/ec2_group
+++ b/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
--- a/library/cloud/ec2_key
+++ b/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
 '''

--- a/library/cloud/ec2_lc
+++ b/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 = '''
--- a/library/cloud/ec2_metric_alarm
+++ b/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 = '''
--- a/library/cloud/ec2_scaling_policy
+++ b/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 = '''
--- a/library/cloud/ec2_snapshot
+++ b/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 = '''
--- a/library/cloud/ec2_tag
+++ b/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 = '''
--- a/library/cloud/ec2_vol
+++ b/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 = '''