More EC2 doc tweaks

lib/ansible/modules/cloud/amazon/ec2_ami.py

@@ -18,9 +18,9 @@ DOCUMENTATION = '''
 ---
 module: ec2_ami
 version_added: "1.3"
-short_description: create or destroy an image in ec2, return imageid
+short_description: create or destroy an image in ec2
 description:
-     - Creates or deletes ec2 images. This module has a dependency on python-boto >= 2.5
+     - Creates or deletes ec2 images. 
 options:
   instance_id:
     description:
@@ -89,13 +89,10 @@ extends_documentation_fragment: aws
 '''
 
 # Thank you to iAcquire for sponsoring development of this module.
-# 
-# See http://alestic.com/2011/06/ec2-ami-security for more information about ensuring the security of your AMI.
 
 EXAMPLES = '''
 # Basic AMI Creation
-- local_action:
-    module: ec2_ami
+- ec2_ami:
     aws_access_key: xxxxxxxxxxxxxxxxxxxxxxx
     aws_secret_key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
     instance_id: i-xxxxxx
@@ -104,8 +101,7 @@ EXAMPLES = '''
   register: instance
 
 # Basic AMI Creation, without waiting
-- local_action:
-    module: ec2_ami
+- ec2_ami:
     aws_access_key: xxxxxxxxxxxxxxxxxxxxxxx
     aws_secret_key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
     region: xxxxxx
@@ -115,22 +111,20 @@ EXAMPLES = '''
   register: instance
 
 # Deregister/Delete AMI
-- local_action:
-    module: ec2_ami
+- ec2_ami:
     aws_access_key: xxxxxxxxxxxxxxxxxxxxxxx
     aws_secret_key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
     region: xxxxxx
-    image_id: ${instance.image_id}
+    image_id: "{{ instance.image_id }}"
     delete_snapshot: True
     state: absent
 
 # Deregister AMI
-- local_action:
-    module: ec2_ami
+- ec2_ami:
     aws_access_key: xxxxxxxxxxxxxxxxxxxxxxx
     aws_secret_key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
     region: xxxxxx
-    image_id: ${instance.image_id}
+    image_id: "{{ instance.image_id }}"
     delete_snapshot: False
     state: absent
 

lib/ansible/modules/cloud/amazon/ec2_ami_search.py

@@ -16,10 +16,11 @@
 #
 # You should have received a copy of the GNU General Public License
 # along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+
 DOCUMENTATION = '''
 ---
 module: ec2_ami_search
-short_description: Retrieve AWS AMI for a given operating system.
+short_description: Retrieve AWS AMI information for a given operating system.
 version_added: "1.6"
 description:
   - Look up the most recent AMI on AWS for a given operating system.

lib/ansible/modules/cloud/amazon/ec2_asg.py

@@ -119,21 +119,23 @@ extends_documentation_fragment: aws
 """
 
 EXAMPLES = '''
-A basic example of configuration:
+# Basic configuration
 
 - ec2_asg:
     name: special
-    load_balancers: 'lb1,lb2'
-    availability_zones: 'eu-west-1a,eu-west-1b'
+    load_balancers: [ 'lb1', 'lb2' ]
+    availability_zones: [ 'eu-west-1a', 'eu-west-1b' ]
     launch_config_name: 'lc-1'
     min_size: 1
     max_size: 10
     desired_capacity: 5
-    vpc_zone_identifier: 'subnet-abcd1234,subnet-1a2b3c4d'
+    vpc_zone_identifier: [ 'subnet-abcd1234', 'subnet-1a2b3c4d' ]
     tags:
       - environment: production
         propagate_at_launch: no
 
+# Rolling ASG Updates
+
 Below is an example of how to assign a new launch config to an ASG and terminate old instances.  
 
 All instances in "myasg" that do not have the launch configuration named "my_new_lc" will be terminated in 
@@ -415,9 +417,10 @@ def replace(connection, module):
     max_size =  module.params.get('max_size')
     min_size =  module.params.get('min_size')
     desired_capacity =  module.params.get('desired_capacity')
+
+    # FIXME: we need some more docs about this feature
     replace_instances = module.params.get('replace_instances')
     
-    
     # wait for instance list to be populated on a newly provisioned ASG
     instance_wait = time.time() + 30
     while instance_wait > time.time():

lib/ansible/modules/cloud/amazon/ec2_eip.py

@@ -69,13 +69,13 @@ EXAMPLES = '''
   ec2_eip: instance_id=i-1212f003
 
 - name: allocate a new elastic IP without associating it to anything
-  ec2_eip:
+  action: ec2_eip
   register: eip
 - name: output the IP
   debug: msg="Allocated IP is {{ eip.public_ip }}"
 
 - name: provision new instances with ec2
-  ec2: keypair=mykey instance_type=c1.medium image=emi-40603AD1 wait=yes group=webserver count=3
+  ec2: keypair=mykey instance_type=c1.medium image=ami-40603AD1 wait=yes group=webserver count=3
   register: ec2
 - name: associate new elastic IPs with each of the instances
   ec2_eip: "instance_id={{ item }}"

lib/ansible/modules/cloud/amazon/ec2_elb.py

@@ -80,18 +80,18 @@ EXAMPLES = """
 # basic pre_task and post_task example
 pre_tasks:
   - name: Gathering ec2 facts
-    ec2_facts:
+    action: ec2_facts
   - name: Instance De-register
-    local_action: ec2_elb
-    args:
+    local_action:
+      module: ec2_elb
       instance_id: "{{ ansible_ec2_instance_id }}"
       state: 'absent'
 roles:
   - myrole
 post_tasks:
   - name: Instance Register
-    local_action: ec2_elb
-    args:
+    local_action: 
+      module: ec2_elb
       instance_id: "{{ ansible_ec2_instance_id }}"
       ec2_elbs: "{{ item }}"
       state: 'present'

lib/ansible/modules/cloud/amazon/ec2_elb_lb.py

@@ -115,7 +115,8 @@ EXAMPLES = """
 # Note: None of these examples set aws_access_key, aws_secret_key, or region.
 # It is assumed that their matching environment variables are set.
 
-# Basic provisioning example
+# Basic provisioning example (non-VPC)
+
 - local_action:
     module: ec2_elb_lb
     name: "test-please-delete"
@@ -134,8 +135,8 @@ EXAMPLES = """
         # ssl certificate required for https or ssl
         ssl_certificate_id: "arn:aws:iam::123456789012:server-certificate/company/servercerts/ProdServerCert"
 
+# Internal ELB example
 
-# Basic VPC provisioning example
 - local_action:
     module: ec2_elb_lb
     name: "test-vpc"

lib/ansible/modules/cloud/amazon/ec2_group.py

@@ -70,8 +70,7 @@ notes:
 
 EXAMPLES = '''
 - name: example ec2 group
-  local_action:
-    module: ec2_group
+  ec2_group:
     name: example
     description: an example EC2 group
     vpc_id: 12345

lib/ansible/modules/cloud/amazon/ec2_key.py

@@ -56,15 +56,13 @@ EXAMPLES = '''
 # Creates a new ec2 key pair named `example` if not present, returns generated
 # private key
 - name: example ec2 key
-  local_action:
-    module: ec2_key
+  ec2_key:
     name: example
 
 # Creates a new ec2 key pair named `example` if not present using provided key
-# material
+# material.  This could use the 'file' lookup plugin to pull this off disk.
 - name: example2 ec2 key
-  local_action:
-    module: ec2_key
+  ec2_key:
     name: example2
     key_material: 'ssh-rsa AAAAxyz...== me@example.com'
     state: present
@@ -72,16 +70,14 @@ EXAMPLES = '''
 # Creates a new ec2 key pair named `example` if not present using provided key
 # material
 - name: example3 ec2 key
-  local_action:
-    module: ec2_key
+  ec2_key:
     name: example3
     key_material: "{{ item }}"
   with_file: /path/to/public_key.id_rsa.pub
 
 # Removes ec2 key pair by name
 - name: remove example key
-  local_action:
-    module: ec2_key
+  ec2_key:
     name: example
     state: absent
 '''

lib/ansible/modules/cloud/amazon/ec2_lc.py

@@ -125,7 +125,7 @@ EXAMPLES = '''
     name: special
     image_id: ami-XXX
     key_name: default
-    security_groups: 'group,group2'
+    security_groups: ['group', 'group2' ]
     instance_type: t1.micro
 
 '''

lib/ansible/modules/cloud/amazon/ec2_snapshot.py

@@ -68,21 +68,18 @@ extends_documentation_fragment: aws
 
 EXAMPLES = '''
 # Simple snapshot of volume using volume_id
-- local_action: 
-    module: ec2_snapshot 
+- ec2_snapshot:
     volume_id: vol-abcdef12   
     description: snapshot of /data from DB123 taken 2013/11/28 12:18:32
 
 # Snapshot of volume mounted on device_name attached to instance_id
-- local_action: 
-    module: ec2_snapshot 
+- ec2_snapshot:
     instance_id: i-12345678
     device_name: /dev/sdb1
     description: snapshot of /data from DB123 taken 2013/11/28 12:18:32
 
 # Snapshot of volume with tagging
-- local_action: 
-    module: ec2_snapshot 
+- ec2_snapshot:
     instance_id: i-12345678
     device_name: /dev/sdb1
     snapshot_tags:

lib/ansible/modules/cloud/amazon/ec2_tag.py

@@ -50,7 +50,7 @@ EXAMPLES = '''
 # Basic example of adding tag(s)
 tasks:
 - name: tag a resource
-  local_action: ec2_tag resource=vol-XXXXXX region=eu-west-1 state=present
+  ec2_tag: resource=vol-XXXXXX region=eu-west-1 state=present
   args:
     tags:
       Name: ubervol
@@ -59,11 +59,11 @@ tasks:
 # Playbook example of adding tag(s) to spawned instances
 tasks:
 - name: launch some instances
-  local_action: ec2 keypair={{ keypair }} group={{ security_group }} instance_type={{ instance_type }} image={{ image_id }} wait=true region=eu-west-1
+  ec2: keypair={{ keypair }} group={{ security_group }} instance_type={{ instance_type }} image={{ image_id }} wait=true region=eu-west-1
   register: ec2
 
 - name: tag my launched instances
-  local_action: ec2_tag resource={{ item.id }} region=eu-west-1 state=present
+  ec2_tag: resource={{ item.id }} region=eu-west-1 state=present
   with_items: ec2.instances
   args:
     tags:

lib/ansible/modules/cloud/amazon/ec2_vol.py

@@ -105,36 +105,31 @@ extends_documentation_fragment: aws
 
 EXAMPLES = '''
 # Simple attachment action
-- local_action: 
-    module: ec2_vol 
+- ec2_vol: 
     instance: XXXXXX 
     volume_size: 5 
     device_name: sdd
 
 # Example using custom iops params   
-- local_action: 
-    module: ec2_vol 
+- ec2_vol:
     instance: XXXXXX 
     volume_size: 5 
     iops: 200
     device_name: sdd
 
 # Example using snapshot id
-- local_action:
-    module: ec2_vol
+- ec2_vol:
     instance: XXXXXX
     snapshot: "{{ snapshot }}"
 
 # Playbook example combined with instance launch 
-- local_action: 
-    module: ec2 
+- ec2:
     keypair: "{{ keypair }}"
     image: "{{ image }}"
     wait: yes 
     count: 3
     register: ec2
-- local_action: 
-    module: ec2_vol 
+- ec2_vol:
     instance: "{{ item.id }} " 
     volume_size: 5
     with_items: ec2.instances
@@ -144,8 +139,7 @@ EXAMPLES = '''
 #   * Nothing will happen if the volume is already attached.
 #   * Volume must exist in the same zone.
 
-- local_action: 
-    module: ec2 
+- ec2:
     keypair: "{{ keypair }}"
     image: "{{ image }}"
     zone: YYYYYY
@@ -154,8 +148,7 @@ EXAMPLES = '''
     count: 1
     register: ec2
 
-- local_action: 
-    module: ec2_vol 
+- ec2_vol:
     instance: "{{ item.id }}" 
     name: my_existing_volume_Name_tag
     device_name: /dev/xvdf
@@ -163,23 +156,16 @@ EXAMPLES = '''
     register: ec2_vol
 
 # Remove a volume
-- local_action:
-    module: ec2_vol
+- ec2_vol:
     id: vol-XXXXXXXX
     state: absent
 
 # List volumes for an instance
-- local_action:
-    module: ec2_vol
+- ec2_vol:
     instance: i-XXXXXX
     state: list
 '''
 
-# Note: this module needs to be made idempotent. Possible solution is to use resource tags with the volumes.
-# if state=present and it doesn't exist, create, tag and attach. 
-# Check for state by looking for volume attachment with tag (and against block device mapping?).
-# Would personally like to revisit this in May when Eucalyptus also has tagging support (3.3).
-
 import sys
 import time
 

lib/ansible/modules/cloud/amazon/ec2_vpc.py

@@ -130,16 +130,14 @@ EXAMPLES = '''
 # It is assumed that their matching environment variables are set.
 
 # Basic creation example:
-      local_action:
-        module: ec2_vpc
+      ec2_vpc:
         state: present
         cidr_block: 172.23.0.0/16
         resource_tags: { "Environment":"Development" }
         region: us-west-2
 # Full creation example with subnets and optional availability zones.
 # The absence or presence of subnets deletes or creates them respectively.
-      local_action:
-        module: ec2_vpc
+      ec2_vpc:
         state: present
         cidr_block: 172.22.0.0/16
         resource_tags: { "Environment":"Development" }
@@ -170,8 +168,7 @@ EXAMPLES = '''
       register: vpc
 
 # Removal of a VPC by id
-      local_action:
-        module: ec2_vpc
+      ec2_vpc:
         state: absent
         vpc_id: vpc-aaaaaaa
         region: us-west-2

lib/ansible/modules/cloud/amazon/elasticache.py

@@ -111,8 +111,7 @@ EXAMPLES = """
 # It is assumed that their matching environment variables are set.
 
 # Basic example
-- local_action:
-    module: elasticache
+- elasticache:
     name: "test-please-delete"
     state: present
     engine: memcached
@@ -126,14 +125,12 @@ EXAMPLES = """
 
 
 # Ensure cache cluster is gone
-- local_action:
-    module: elasticache
+- elasticache:
     name: "test-please-delete"
     state: absent
 
 # Reboot cache cluster
-- local_action:
-    module: elasticache
+- elasticache:
     name: "test-please-delete"
     state: rebooted
 

lib/ansible/modules/cloud/amazon/rds.py

@@ -224,44 +224,45 @@ requirements: [ "boto" ]
 author: Bruce Pennypacker
 '''
 
+# FIXME: the command stuff needs a 'state' like alias to make things consistent -- MPD
+
 EXAMPLES = '''
 # Basic mysql provisioning example
-- rds: >
-      command=create
-      instance_name=new_database
-      db_engine=MySQL
-      size=10
-      instance_type=db.m1.small
-      username=mysql_admin
-      password=1nsecure
+- rds:
+    command: create
+    instance_name: new_database
+    db_engine: MySQL
+    size: 10
+    instance_type: db.m1.small
+    username: mysql_admin
+    password: 1nsecure
 
 # Create a read-only replica and wait for it to become available
-- rds: >
-      command=replicate
-      instance_name=new_database_replica
-      source_instance=new_database
-      wait=yes
-      wait_timeout=600
+- rds: 
+    command: replicate
+    instance_name: new_database_replica
+    source_instance: new_database
+    wait: yes
+    wait_timeout: 600
 
 # Delete an instance, but create a snapshot before doing so
-- rds: >
-      command=delete
-      instance_name=new_database
-      snapshot=new_database_snapshot
+- rds:
+    command: delete
+    instance_name: new_database
+    snapshot: new_database_snapshot
 
 # Get facts about an instance
-- rds: >
-      command=facts
-      instance_name=new_database
-      register: new_database_facts
+- rds:
+    command: facts
+    instance_name: new_database
+    register: new_database_facts
 
 # Rename an instance and wait for the change to take effect
-- rds: >
-      command=modify
-      instance_name=new_database
-      new_instance_name=renamed_database
-      wait=yes
-    
+- rds:
+    command: modify
+    instance_name: new_database
+    new_instance_name: renamed_database
+    wait: yes
 '''
 
 import sys

lib/ansible/modules/cloud/amazon/rds_param_group.py

@@ -85,17 +85,18 @@ author: Scott Anderson
 
 EXAMPLES = '''
 # Add or change a parameter group, in this case setting auto_increment_increment to 42 * 1024
-- rds_param_group: >
-      state=present
-      name=norwegian_blue
-      description=My Fancy Ex Parrot Group
-      engine=mysql5.6
-      params='{"auto_increment_increment": "42K"}'
+- rds_param_group:
+      state: present
+      name: norwegian_blue
+      description: 'My Fancy Ex Parrot Group'
+      engine: 'mysql5.6'
+      params: 
+          auto_increment_increment: "42K"
 
 # Remove a parameter group
-- rds_param_group: >
-      state=absent
-      name=norwegian_blue
+- rds_param_group:
+      state: absent
+      name: norwegian_blue
 '''
 
 import sys

lib/ansible/modules/cloud/amazon/rds_subnet_group.py

@@ -71,8 +71,7 @@ author: Scott Anderson
 
 EXAMPLES = '''
 # Add or change a subnet group
-- local_action:
-    module: rds_subnet_group
+- rds_subnet_group
     state: present
     name: norwegian-blue
     description: My Fancy Ex Parrot Subnet Group
@@ -81,9 +80,9 @@ EXAMPLES = '''
       - subnet-bbbbbbbb
 
 # Remove a parameter group
-- rds_param_group: >
-      state=absent
-      name=norwegian-blue
+- rds_param_group:
+    state: absent
+    name: norwegian-blue
 '''
 
 import sys

lib/ansible/modules/cloud/amazon/route53.py

@@ -88,51 +88,53 @@ requirements: [ "boto" ]
 author: Bruce Pennypacker
 '''
 
+# FIXME: the command stuff should have a more state like configuration alias -- MPD
+
 EXAMPLES = '''
 # Add new.foo.com as an A record with 3 IPs
-- route53: >
-      command=create
-      zone=foo.com
-      record=new.foo.com
-      type=A
-      ttl=7200
-      value=1.1.1.1,2.2.2.2,3.3.3.3
+- route53:
+      command: create
+      zone: foo.com
+      record: new.foo.com
+      type: A
+      ttl: 7200
+      value: 1.1.1.1,2.2.2.2,3.3.3.3
 
 # Retrieve the details for new.foo.com
-- route53: >
-      command=get
-      zone=foo.com
-      record=new.foo.com
-      type=A
+- route53:
+      command: get
+      zone: foo.com
+      record: new.foo.com
+      type: A
   register: rec
 
 # Delete new.foo.com A record using the results from the get command
-- route53: >
-      command=delete
-      zone=foo.com
-      record={{ rec.set.record }}
-      type={{ rec.set.type }}
-      value={{ rec.set.value }}
+- route53:
+      command: delete
+      zone: foo.com
+      record: "{{ rec.set.record }}"
+      type: "{{ rec.set.type }}"
+      value: "{{ rec.set.value }}"
 
 # Add an AAAA record.  Note that because there are colons in the value
 # that the entire parameter list must be quoted:
-- route53: >
-      command=create
-      zone=foo.com
-      record=localhost.foo.com
-      type=AAAA
-      ttl=7200
-      value="::1"
+- route53:
+      command: "create"
+      zone: "foo.com"
+      record: "localhost.foo.com"
+      type: "AAAA"
+      ttl: "7200"
+      value: "::1"
 
 # Add a TXT record. Note that TXT and SPF records must be surrounded
 # by quotes when sent to Route 53:
-- route53: >
-      command=create
-      zone=foo.com
-      record=localhost.foo.com
-      type=TXT
-      ttl=7200
-      value="\"bar\""
+- route53:
+      command: "create"
+      zone: "foo.com"
+      record: "localhost.foo.com"
+      type: "TXT"
+      ttl: "7200"
+      value: '"bar"'
 
 
 '''

lib/ansible/modules/cloud/amazon/s3.py

@@ -103,28 +103,19 @@ author: Lester Wade, Ralph Tice
 EXAMPLES = '''
 # Simple PUT operation
 - s3: bucket=mybucket object=/my/desired/key.txt src=/usr/local/myfile.txt mode=put
+
 # Simple GET operation
 - s3: bucket=mybucket object=/my/desired/key.txt dest=/usr/local/myfile.txt mode=get
-# GET/download and overwrite local file (trust remote)
-- s3: bucket=mybucket object=/my/desired/key.txt dest=/usr/local/myfile.txt mode=get 
-# GET/download and do not overwrite local file (trust remote)
-- s3: bucket=mybucket object=/my/desired/key.txt dest=/usr/local/myfile.txt mode=get force=false
-# PUT/upload and overwrite remote file (trust local)
-- s3: bucket=mybucket object=/my/desired/key.txt src=/usr/local/myfile.txt mode=put
+
 # PUT/upload with metadata
-- s3: bucket=mybucket object=/my/desired/key.txt src=/usr/local/myfile.txt mode=put metadata='Content-Encoding=gzip'
-# PUT/upload with multiple metadata
 - s3: bucket=mybucket object=/my/desired/key.txt src=/usr/local/myfile.txt mode=put metadata='Content-Encoding=gzip,Cache-Control=no-cache'
-# PUT/upload and do not overwrite remote file (trust local)
-- s3: bucket=mybucket object=/my/desired/key.txt src=/usr/local/myfile.txt mode=put force=false
-# Download an object as a string to use else where in your playbook
-- s3: bucket=mybucket object=/my/desired/key.txt src=/usr/local/myfile.txt mode=getstr
+
 # Create an empty bucket
 - s3: bucket=mybucket mode=create
-# Create a bucket with key as directory
-- s3: bucket=mybucket object=/my/directory/path mode=create
-# Create an empty bucket in the EU region
-- s3: bucket=mybucket mode=create region=eu-west-1
+
+# Create a bucket with key as directory, in the EU region
+- s3: bucket=mybucket object=/my/directory/path mode=create region=eu-west-1
+
 # Delete a bucket and all contents
 - s3: bucket=mybucket mode=delete
 '''