ANSIBLE.EC2(3)                  ANSIBLE MODULES                 ANSIBLE.EC2(3)



NAME
       ec2 - create or terminate an instance in ec2, return instanceid

DESCRIPTION
       Creates or terminates ec2 instances. When created optionally waits for
       it to be 'running'. This module has a dependency on python-boto >= 2.5

OPTIONS
       aws_access_key
              AWS access key. If not set then the value of the AWS_ACCESS_KEY
              environment variable is used.

       aws_secret_key
              AWS secret key. If not set then the value of the AWS_SECRET_KEY
              environment variable is used.

       count  number of instances to launch (default: yes

       ec2_url
              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

       group  security group (or list of groups) to use with the instance

       group_id
              security group id (or list of ids) to use with the
              instance(Added in Ansible version 1.1.)


       id     identifier for this instance or set of instances, so that the
              module will be idempotent with respect to EC2 instances. This
              identifier is valid for at least 24 hours after the termination
              of the instance, and should not be reused for another call later
              on. For details, see the description of client token at
              http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Run_Instance_Idempotency.html.

       image  emi (or ami) to use for the instance(required)

       instance_ids
              list of instance ids, currently only used when
              state='absent'(Added in Ansible version 1.3.)


       instance_profile_name
              Name of the IAM instance profile to use. Boto library must be
              2.5.0+(Added in Ansible version 1.3.)


       instance_tags
              a hash/dictionary of tags to add to the new instance;
              '{"key":"value"}' and '{"key":"value","key":"value"}'(Added in
              Ansible version 1.0.)


       instance_type
              instance type to use for the instance(required)

       kernel kernel eki to use for the instance

       key_name
              key pair to use on the instance(required)

       monitoring
              enable detailed monitoring (CloudWatch) for instance(Added in
              Ansible version 1.1.)


       placement_group
              placement group for the instance when using EC2 Clustered
              Compute(Added in Ansible version 1.3.)


       private_ip
              the private ip address to assign the instance (from the vpc
              subnet)(Added in Ansible version 1.2.)


       ramdisk
              ramdisk eri to use for the instance

       region The AWS region to use.  Must be specified if ec2_url is not
              used. If not specified then the value of the EC2_REGION
              environment variable, if any, is used.(Added in Ansible version
              1.2.)


       state  create or terminate instances (default: present)(Added in
              Ansible version 1.3.)


       user_data
              opaque blob of data which is made available to the ec2
              instance(Added in Ansible version 0.9.)


       vpc_subnet_id
              the subnet ID in which to launch the instance (VPC)(Added in
              Ansible version 1.1.)


       wait   wait for the instance to be in state 'running' before returning
              Choices: yes,no. (default: no)

       wait_timeout
              how long before wait gives up, in seconds (default: 300)

       zone   AWS availability zone in which to launch the instance(Added in
              Ansible version 1.2.)

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
       - local_action:
           module: ec2
           keypair: mykey
           instance_type: c1.medium
           image: emi-40603AD1
           wait: yes
           group: webserver
           count: 3

       # Advanced example with tagging and CloudWatch
       - local_action:
           module: ec2
           keypair: mykey
           group: databases
           instance_type: m1.large
           image: ami-6e649707
           wait: yes
           wait_timeout: 500
           count: 5
           instance_tags: '{"db":"postgres"}'
           monitoring=yes

       # Multiple groups example
       local_action:
           module: ec2
           keypair: mykey
           group: ['databases', 'internal-services', 'sshable', 'and-so-forth']
           instance_type: m1.large
           image: ami-6e649707
           wait: yes
           wait_timeout: 500
           count: 5
           instance_tags: '{"db":"postgres"}'
           monitoring=yes

       # VPC example
       - local_action:
           module: ec2
           keypair: mykey
           group_id: sg-1dc53f72
           instance_type: m1.small
           image: ami-6e649707
           wait: yes
           vpc_subnet_id: subnet-29e63245


       # Launch instances, runs some tasks
       # and then terminate them


       - name: Create a sandbox instance
         hosts: localhost
         gather_facts: False
         vars:
           keypair: my_keypair
           instance_type: m1.small
           security_group: my_securitygroup
           image: my_ami_id
           region: us-east-1
         tasks:
           - name: Launch instance
             local_action: ec2 keypair={{ keypair }} group={{ security_group }} instance_type={{ instance_type }} image={{ image }} wait=true region={{ region }}
             register: ec2
           - name: Add new instance to host group
             local_action: add_host hostname={{ item.public_ip }} groupname=launched
             with_items: ec2.instances
           - name: Wait for SSH to come up
             local_action: wait_for host={{ item.public_dns_name }} port=22 delay=60 timeout=320 state=started
             with_items: ec2.instances

       - name: Configure instance(s)
         hosts: launched
         sudo: True
         gather_facts: True
         roles:
           - my_awesome_role
           - my_awesome_test

       - name: Terminate instances
         hosts: localhost
         connection: local
         tasks:
           - name: Terminate instances that were previously launched
             local_action:
               module: ec2
               state: 'absent'
               instance_ids: {{ec2.instance_ids}}




AUTHOR
       Seth Vidal, Tim Gerla, Lester Wade

SEE ALSO
       ansible(1), http://ansible.github.com/modules.html#ec2



1.4.5                             2014-02-12                    ANSIBLE.EC2(3)
