From e7c92a6bc6e95ae3333bdb364ef904f19cf43c00 Mon Sep 17 00:00:00 2001 From: Michael DeHaan Date: Mon, 1 Dec 2014 15:14:57 -0500 Subject: [PATCH] More EC2 doc tweaks --- cloud/amazon/ec2_ami.py | 22 ++++------- cloud/amazon/ec2_ami_search.py | 3 +- cloud/amazon/ec2_asg.py | 13 ++++--- cloud/amazon/ec2_eip.py | 4 +- cloud/amazon/ec2_elb.py | 10 ++--- cloud/amazon/ec2_elb_lb.py | 5 ++- cloud/amazon/ec2_group.py | 3 +- cloud/amazon/ec2_key.py | 14 +++---- cloud/amazon/ec2_lc.py | 2 +- cloud/amazon/ec2_snapshot.py | 9 ++--- cloud/amazon/ec2_tag.py | 6 +-- cloud/amazon/ec2_vol.py | 32 +++++----------- cloud/amazon/ec2_vpc.py | 9 ++--- cloud/amazon/elasticache.py | 9 ++--- cloud/amazon/rds.py | 57 +++++++++++++-------------- cloud/amazon/rds_param_group.py | 19 ++++----- cloud/amazon/rds_subnet_group.py | 9 ++--- cloud/amazon/route53.py | 66 ++++++++++++++++---------------- cloud/amazon/s3.py | 23 ++++------- 19 files changed, 140 insertions(+), 175 deletions(-) diff --git a/cloud/amazon/ec2_ami.py b/cloud/amazon/ec2_ami.py index 3baf70a438f..c50e5a88048 100644 --- a/cloud/amazon/ec2_ami.py +++ b/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 diff --git a/cloud/amazon/ec2_ami_search.py b/cloud/amazon/ec2_ami_search.py index 25875de39bd..70664cf5f8d 100644 --- a/cloud/amazon/ec2_ami_search.py +++ b/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 . + 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. diff --git a/cloud/amazon/ec2_asg.py b/cloud/amazon/ec2_asg.py index 2b060ccca37..da922530770 100644 --- a/cloud/amazon/ec2_asg.py +++ b/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(): diff --git a/cloud/amazon/ec2_eip.py b/cloud/amazon/ec2_eip.py index cff83e482b3..fd0e8d04568 100644 --- a/cloud/amazon/ec2_eip.py +++ b/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 }}" diff --git a/cloud/amazon/ec2_elb.py b/cloud/amazon/ec2_elb.py index 42cb1819025..52f8c4a4bf9 100644 --- a/cloud/amazon/ec2_elb.py +++ b/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' diff --git a/cloud/amazon/ec2_elb_lb.py b/cloud/amazon/ec2_elb_lb.py index 462fbbcc797..6235770eb38 100644 --- a/cloud/amazon/ec2_elb_lb.py +++ b/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" diff --git a/cloud/amazon/ec2_group.py b/cloud/amazon/ec2_group.py index 822147468a2..7d081a29620 100644 --- a/cloud/amazon/ec2_group.py +++ b/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 diff --git a/cloud/amazon/ec2_key.py b/cloud/amazon/ec2_key.py index 9c8274f764a..9f548496c4a 100644 --- a/cloud/amazon/ec2_key.py +++ b/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 ''' diff --git a/cloud/amazon/ec2_lc.py b/cloud/amazon/ec2_lc.py index f75dfe6d938..8fbdcea3e66 100644 --- a/cloud/amazon/ec2_lc.py +++ b/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 ''' diff --git a/cloud/amazon/ec2_snapshot.py b/cloud/amazon/ec2_snapshot.py index 4c21ae6ff7b..eb77840e638 100644 --- a/cloud/amazon/ec2_snapshot.py +++ b/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: diff --git a/cloud/amazon/ec2_tag.py b/cloud/amazon/ec2_tag.py index 4a33112189a..ab4b87bfa84 100644 --- a/cloud/amazon/ec2_tag.py +++ b/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: diff --git a/cloud/amazon/ec2_vol.py b/cloud/amazon/ec2_vol.py index 0e662a77bdd..f9523ba3ecc 100644 --- a/cloud/amazon/ec2_vol.py +++ b/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 diff --git a/cloud/amazon/ec2_vpc.py b/cloud/amazon/ec2_vpc.py index e4dc9a65f7d..00528f27849 100644 --- a/cloud/amazon/ec2_vpc.py +++ b/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 diff --git a/cloud/amazon/elasticache.py b/cloud/amazon/elasticache.py index 8c82f2fcc20..c1846f525a8 100644 --- a/cloud/amazon/elasticache.py +++ b/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 diff --git a/cloud/amazon/rds.py b/cloud/amazon/rds.py index ba3f1e38d39..d6fd1622161 100644 --- a/cloud/amazon/rds.py +++ b/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 diff --git a/cloud/amazon/rds_param_group.py b/cloud/amazon/rds_param_group.py index 39f9432057a..d1559ac78ae 100644 --- a/cloud/amazon/rds_param_group.py +++ b/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 diff --git a/cloud/amazon/rds_subnet_group.py b/cloud/amazon/rds_subnet_group.py index 552c94f188a..bba6cd86872 100644 --- a/cloud/amazon/rds_subnet_group.py +++ b/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 diff --git a/cloud/amazon/route53.py b/cloud/amazon/route53.py index b3878e0580e..9958b221031 100644 --- a/cloud/amazon/route53.py +++ b/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"' ''' diff --git a/cloud/amazon/s3.py b/cloud/amazon/s3.py index 6438c6405e7..1db21893a4c 100644 --- a/cloud/amazon/s3.py +++ b/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 '''