`, please file a feature request. Requirements ------------ The below requirements are needed on the host that executes this module. - python >= 2.6 - boto Parameters ---------- .. raw:: html

Parameter		Choices/Defaults	Comments
assign_public_ip boolean		Choices: no yes	When provisioning within vpc, assign a public IP address. Boto library must be 2.13.0+.
aws_access_key string			AWS access key. If not set then the value of the AWS_ACCESS_KEY_ID, AWS_ACCESS_KEY or EC2_ACCESS_KEY environment variable is used. If profile is set this parameter is ignored. Passing the aws_access_key and profile options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01. aliases: ec2_access_key, access_key
aws_ca_bundle path			The location of a CA Bundle to use when validating SSL certificates. Only used for boto3 based modules. Note: The CA Bundle is read 'module' side and may need to be explicitly copied from the controller if not run locally.
aws_config dictionary			A dictionary to modify the botocore configuration. Parameters can be found at https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config. Only the 'user_agent' key is used for boto modules. See http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto for more boto configuration.
aws_secret_key string			AWS secret key. If not set then the value of the AWS_SECRET_ACCESS_KEY, AWS_SECRET_KEY, or EC2_SECRET_KEY environment variable is used. If profile is set this parameter is ignored. Passing the aws_secret_key and profile options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01. aliases: ec2_secret_key, secret_key
count integer		Default: 1	Number of instances to launch.
count_tag raw			Used with exact_count to determine how many nodes based on a specific tag criteria should be running. This can be expressed in multiple ways and is shown in the EXAMPLES section. For instance, one can request 25 servers that are tagged with `class=webserver`. The specified tag must already exist or be passed in as the instance_tags option.
debug_botocore_endpoint_logs boolean		Choices: no ← yes	Use a botocore.endpoint logger to parse the unique (rather than total) "resource:action" API calls made during a task, outputing the set to the resource_actions key in the task results. Use the aws_resource_action callback to output to total list made during a playbook. The ANSIBLE_DEBUG_BOTOCORE_LOGS environment variable may also be used.
ebs_optimized boolean		Choices: no ← yes	Whether instance is using optimized EBS volumes, see https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSOptimized.html.
ec2_url string			Url to use to connect to EC2 or your Eucalyptus cloud (by default the module will use EC2 endpoints). Ignored for modules where region is required. Must be specified for all other modules if region is not used. If not set then the value of the EC2_URL environment variable, if any, is used. aliases: aws_endpoint_url, endpoint_url
exact_count integer			An integer value which indicates how many instances that match the 'count_tag' parameter should be running. Instances are either created or terminated based on this value.
group list / elements=string			Security group (or list of groups) to use with the instance. aliases: groups
group_id list / elements=string			Security group id (or list of ids) to use with the instance.
id string			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 https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Run_Instance_Idempotency.html.
image string			ami ID to use for the instance. Required when state=present.
instance_ids list / elements=string			list of instance ids, currently used for states: absent, running, stopped aliases: instance_id
instance_initiated_shutdown_behavior string		Choices: stop ← terminate	Set whether AWS will Stop or Terminate an instance on shutdown. This parameter is ignored when using instance-store. images (which require termination on shutdown).
instance_profile_name string			Name of the IAM instance profile (i.e. what the EC2 console refers to as an "IAM Role") to use. Boto library must be 2.5.0+.
instance_tags dictionary			A hash/dictionary of tags to add to the new instance or for instances to start/stop by tag. For example `{"key":"value"}` or `{"key":"value","key2":"value2"}`.
instance_type string			Instance type to use for the instance, see https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-types.html. Required when creating a new instance. aliases: type
kernel string			Kernel eki to use for the instance.
key_name string			Key pair to use on the instance. The SSH key must already exist in AWS in order to use this argument. Keys can be created / deleted using the amazon.aws.ec2_key module. aliases: keypair
monitoring boolean		Choices: no ← yes	Enable detailed monitoring (CloudWatch) for the instance.
network_interfaces list / elements=string			A list of existing network interfaces to attach to the instance at launch. When specifying existing network interfaces, none of the assign_public_ip, private_ip, vpc_subnet_id, group, or group_id parameters may be used. (Those parameters are for creating a new network interface at launch.) aliases: network_interface
placement_group string			Placement group for the instance when using EC2 Clustered Compute.
private_ip string			The private ip address to assign the instance (from the vpc subnet).
profile string			Uses a boto profile. Only works with boto >= 2.24.0. Using profile will override aws_access_key, aws_secret_key and security_token and support for passing them at the same time as profile has been deprecated. aws_access_key, aws_secret_key and security_token will be made mutually exclusive with profile after 2022-06-01. aliases: aws_profile
ramdisk string			Ramdisk eri to use for the instance.
region string			The AWS region to use. If not specified then the value of the AWS_REGION or EC2_REGION environment variable, if any, is used. See http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region aliases: aws_region, ec2_region
security_token string			AWS STS security token. If not set then the value of the AWS_SECURITY_TOKEN or EC2_SECURITY_TOKEN environment variable is used. If profile is set this parameter is ignored. Passing the security_token and profile options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01. aliases: aws_security_token, access_token
source_dest_check boolean		Choices: no yes	Enable or Disable the Source/Destination checks (for NAT instances and Virtual Routers). When initially creating an instance the EC2 API defaults this to `True`.
spot_launch_group string			Launch group for spot requests, see https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/how-spot-instances-work.html#spot-launch-group.
spot_price string			Maximum spot price to bid. If not set, a regular on-demand instance is requested. A spot request is made with this maximum bid. When it is filled, the instance is started.
spot_type string		Choices: one-time ← persistent	The type of spot request. After being interrupted a `persistent` spot instance will be started once there is capacity to fill the request again.
spot_wait_timeout integer		Default: 600	How long to wait for the spot instance request to be fulfilled. Affects 'Request valid until' for setting spot request lifespan.
state string		Choices: absent present ← restarted running stopped	Create, terminate, start, stop or restart instances. The state 'restarted' was added in Ansible 2.2. When state=absent, instance_ids is required. When state=running, state=stopped or state=restarted then either instance_ids or instance_tags is required.
tenancy string		Choices: default ← dedicated	An instance with a tenancy of `dedicated` runs on single-tenant hardware and can only be launched into a VPC. Note that to use dedicated tenancy you MUST specify a vpc_subnet_id as well. Dedicated tenancy is not available for EC2 "micro" instances.
termination_protection boolean		Choices: no yes	Enable or Disable the Termination Protection. Defaults to `false`.
user_data string			Opaque blob of data which is made available to the EC2 instance.
validate_certs boolean		Choices: no yes ←	When set to "no", SSL certificates will not be validated for boto versions >= 2.6.0.
volumes list / elements=dictionary			A list of hash/dictionaries of volumes to add to the new instance.
	delete_on_termination boolean	Choices: no ← yes	Whether the volume should be automatically deleted when the instance is terminated.
	device_name string / required		A name for the device (For example `/dev/sda`).
	encrypted boolean	Choices: no ← yes	Whether the volume should be encrypted using the 'aws/ebs' KMS CMK.
	ephemeral string		Whether the volume should be ephemeral. Data on ephemeral volumes is lost when the instance is stopped. Mutually exclusive with the snapshot parameter.
	iops integer		The number of IOPS per second to provision for the volume. Required when volume_type=io1.
	snapshot string		The ID of an EBS snapshot to copy when creating the volume. Mutually exclusive with the ephemeral parameter.
	volume_size integer		The size of the volume (in GiB).
	volume_type string		The type of volume to create. See https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSVolumeTypes.html for more information on the available volume types.
vpc_subnet_id string			The subnet ID in which to launch the instance (VPC).
wait boolean		Choices: no ← yes	Wait for the instance to reach its desired state before returning. Does not wait for SSH, see the 'wait_for_connection' example for details.
wait_timeout integer		Default: 300	How long before wait gives up, in seconds.
zone string			AWS availability zone in which to launch the instance. aliases: aws_zone, ec2_zone

Notes ----- .. note:: - If parameters are not set within the module, the following environment variables can be used in decreasing order of precedence ``AWS_URL`` or ``EC2_URL``, ``AWS_PROFILE`` or ``AWS_DEFAULT_PROFILE``, ``AWS_ACCESS_KEY_ID`` or ``AWS_ACCESS_KEY`` or ``EC2_ACCESS_KEY``, ``AWS_SECRET_ACCESS_KEY`` or ``AWS_SECRET_KEY`` or ``EC2_SECRET_KEY``, ``AWS_SECURITY_TOKEN`` or ``EC2_SECURITY_TOKEN``, ``AWS_REGION`` or ``EC2_REGION``, ``AWS_CA_BUNDLE`` - Ansible uses the boto configuration file (typically ~/.boto) if no credentials are provided. See https://boto.readthedocs.io/en/latest/boto_config_tut.html - ``AWS_REGION`` or ``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 Examples -------- .. code-block:: yaml # Note: These examples do not set authentication details, see the AWS Guide for details. # Basic provisioning example - amazon.aws.ec2: key_name: mykey instance_type: t2.micro image: ami-123456 wait: yes group: webserver count: 3 vpc_subnet_id: subnet-29e63245 assign_public_ip: yes # Advanced example with tagging and CloudWatch - amazon.aws.ec2: key_name: mykey group: databases instance_type: t2.micro image: ami-123456 wait: yes wait_timeout: 500 count: 5 instance_tags: db: postgres monitoring: yes vpc_subnet_id: subnet-29e63245 assign_public_ip: yes # Single instance with additional IOPS volume from snapshot and volume delete on termination - amazon.aws.ec2: key_name: mykey group: webserver instance_type: c3.medium image: ami-123456 wait: yes wait_timeout: 500 volumes: - device_name: /dev/sdb snapshot: snap-abcdef12 volume_type: io1 iops: 1000 volume_size: 100 delete_on_termination: true monitoring: yes vpc_subnet_id: subnet-29e63245 assign_public_ip: yes # Single instance with ssd gp2 root volume - amazon.aws.ec2: key_name: mykey group: webserver instance_type: c3.medium image: ami-123456 wait: yes wait_timeout: 500 volumes: - device_name: /dev/xvda volume_type: gp2 volume_size: 8 vpc_subnet_id: subnet-29e63245 assign_public_ip: yes count_tag: Name: dbserver exact_count: 1 # Multiple groups example - amazon.aws.ec2: key_name: 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_subnet_id: subnet-29e63245 assign_public_ip: yes # Multiple instances with additional volume from snapshot - amazon.aws.ec2: key_name: mykey group: webserver instance_type: m1.large image: ami-6e649707 wait: yes wait_timeout: 500 count: 5 volumes: - device_name: /dev/sdb snapshot: snap-abcdef12 volume_size: 10 monitoring: yes vpc_subnet_id: subnet-29e63245 assign_public_ip: yes # Dedicated tenancy example - amazon.aws.ec2: assign_public_ip: yes group_id: sg-1dc53f72 key_name: mykey image: ami-6e649707 instance_type: m1.small tenancy: dedicated vpc_subnet_id: subnet-29e63245 wait: yes # Spot instance example - amazon.aws.ec2: spot_price: 0.24 spot_wait_timeout: 600 keypair: mykey group_id: sg-1dc53f72 instance_type: m1.small image: ami-6e649707 wait: yes vpc_subnet_id: subnet-29e63245 assign_public_ip: yes spot_launch_group: report_generators instance_initiated_shutdown_behavior: terminate # Examples using pre-existing network interfaces - amazon.aws.ec2: key_name: mykey instance_type: t2.small image: ami-f005ba11 network_interface: eni-deadbeef - amazon.aws.ec2: key_name: mykey instance_type: t2.small image: ami-f005ba11 network_interfaces: ['eni-deadbeef', 'eni-5ca1ab1e'] # 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 amazon.aws.ec2: key_name: "{{ keypair }}" group: "{{ security_group }}" instance_type: "{{ instance_type }}" image: "{{ image }}" wait: true region: "{{ region }}" vpc_subnet_id: subnet-29e63245 assign_public_ip: yes register: ec2 - name: Add new instance to host group add_host: hostname: "{{ item.public_ip }}" groupname: launched loop: "{{ ec2.instances }}" - name: Wait for SSH to come up delegate_to: "{{ item.public_dns_name }}" wait_for_connection: delay: 60 timeout: 320 loop: "{{ ec2.instances }}" - name: Configure instance(s) hosts: launched become: True gather_facts: True roles: - my_awesome_role - my_awesome_test - name: Terminate instances hosts: localhost tasks: - name: Terminate instances that were previously launched amazon.aws.ec2: state: 'absent' instance_ids: '{{ ec2.instance_ids }}' # Start a few existing instances, run some tasks # and stop the instances - name: Start sandbox instances hosts: localhost gather_facts: false vars: instance_ids: - 'i-xxxxxx' - 'i-xxxxxx' - 'i-xxxxxx' region: us-east-1 tasks: - name: Start the sandbox instances amazon.aws.ec2: instance_ids: '{{ instance_ids }}' region: '{{ region }}' state: running wait: True vpc_subnet_id: subnet-29e63245 assign_public_ip: yes roles: - do_neat_stuff - do_more_neat_stuff - name: Stop sandbox instances hosts: localhost gather_facts: false vars: instance_ids: - 'i-xxxxxx' - 'i-xxxxxx' - 'i-xxxxxx' region: us-east-1 tasks: - name: Stop the sandbox instances amazon.aws.ec2: instance_ids: '{{ instance_ids }}' region: '{{ region }}' state: stopped wait: True vpc_subnet_id: subnet-29e63245 assign_public_ip: yes # # Start stopped instances specified by tag # - amazon.aws.ec2: instance_tags: Name: ExtraPower state: running # # Restart instances specified by tag # - amazon.aws.ec2: instance_tags: Name: ExtraPower state: restarted # # Enforce that 5 instances with a tag "foo" are running # (Highly recommended!) # - amazon.aws.ec2: key_name: mykey instance_type: c1.medium image: ami-40603AD1 wait: yes group: webserver instance_tags: foo: bar exact_count: 5 count_tag: foo vpc_subnet_id: subnet-29e63245 assign_public_ip: yes # # Enforce that 5 running instances named "database" with a "dbtype" of "postgres" # - amazon.aws.ec2: key_name: mykey instance_type: c1.medium image: ami-40603AD1 wait: yes group: webserver instance_tags: Name: database dbtype: postgres exact_count: 5 count_tag: Name: database dbtype: postgres vpc_subnet_id: subnet-29e63245 assign_public_ip: yes # # count_tag complex argument examples # # instances with tag foo - amazon.aws.ec2: count_tag: foo: # instances with tag foo=bar - amazon.aws.ec2: count_tag: foo: bar # instances with tags foo=bar & baz - amazon.aws.ec2: count_tag: foo: bar baz: # instances with tags foo & bar & baz=bang - amazon.aws.ec2: count_tag: - foo - bar - baz: bang Status ------ Authors ~~~~~~~ - Tim Gerla (@tgerla) - Lester Wade (@lwade) - Seth Vidal (@skvidal)