ansible / ansible.builtin / v2.9.0 / module / ec2 create, terminate, start or stop an instance in ec2 | "added in version" 0.9 of ansible.builtin" Authors: Tim Gerla (@tgerla), Lester Wade (@lwade), Seth Vidal (@skvidal) stableinterface | supported by coreansible.builtin.ec2 (v2.9.0) — module
pip
Install with pip install ansible==2.9.0
Creates or terminates ec2 instances.
# Note: These examples do not set authentication details, see the AWS Guide for details. # Basic provisioning example - 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 - 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 - 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 - 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 - 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 - 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 - local_action: module: 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 - 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 - ec2: key_name: mykey instance_type: t2.small image: ami-f005ba11 network_interface: eni-deadbeef
- 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 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 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 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 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 # - local_action: module: ec2 instance_tags: Name: ExtraPower state: running
# # Restart instances specified by tag # - local_action: module: ec2 instance_tags: Name: ExtraPower state: restarted
# # Enforce that 5 instances with a tag "foo" are running # (Highly recommended!) # - 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" # - 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 - ec2: count_tag: foo:
# instances with tag foo=bar - ec2: count_tag: foo: bar
# instances with tags foo=bar & baz - ec2: count_tag: foo: bar baz:
# instances with tags foo & bar & baz=bang - ec2: count_tag: - foo - bar - baz: bang
id: description: - 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 U(https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Run_Instance_Idempotency.html). type: str version_added: '1.1' version_added_collection: ansible.builtin wait: default: 'no' description: - Wait for the instance to reach its desired state before returning. - Does not wait for SSH, see 'wait_for_connection' example for details. type: bool zone: aliases: - aws_zone - ec2_zone description: - AWS availability zone in which to launch the instance. type: str version_added: '1.2' version_added_collection: ansible.builtin count: default: 1 description: - Number of instances to launch. type: int group: aliases: - groups description: - Security group (or list of groups) to use with the instance. type: list image: description: - I(ami) ID to use for the instance. required: true type: str state: choices: - absent - present - restarted - running - stopped default: present description: - Create, terminate, start, stop or restart instances. The state 'restarted' was added in Ansible 2.2. - When 'absent', I(instance_ids) is required. - When 'running', 'stopped' and 'restarted', I(instance_ids) or I(instance_tags) is required. type: str version_added: '1.3' version_added_collection: ansible.builtin kernel: description: - Kernel I(eki) to use for the instance. type: str region: aliases: - aws_region - ec2_region description: - The AWS region to use. Must be specified if ec2_url is not used. - If not specified then the value of the C(AWS_REGION) or C(EC2_REGION) environment variable, if any, is used. - See U(https://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region). type: str version_added: '1.2' version_added_collection: ansible.builtin ec2_url: aliases: - aws_endpoint_url - endpoint_url description: - 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. type: str profile: aliases: - aws_profile description: - Using I(profile) will override I(aws_access_key), I(aws_secret_key) and I(security_token) and support for passing them at the same time as I(profile) has been deprecated. - I(aws_access_key), I(aws_secret_key) and I(security_token) will be made mutually exclusive with I(profile) after 2022-06-01. type: str ramdisk: description: - Ramdisk I(eri) to use for the instance. type: str tenancy: choices: - default - dedicated default: default description: - 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 I(vpc_subnet_id) as well. - Dedicated tenancy is not available for EC2 "micro" instances. type: str version_added: '1.9' version_added_collection: ansible.builtin volumes: description: - a list of hash/dictionaries of volumes to add to the new instance; '[{"key":"value", "key":"value"}]'; keys allowed are - device_name (str; required), delete_on_termination (bool; False), ephemeral (str), encrypted (bool; False), snapshot (str), volume_type (str), volume_size (int, GiB), iops (int) - iops must be set when volume_type='io1', ephemeral and snapshot are mutually exclusive. type: list version_added: '1.5' version_added_collection: ansible.builtin group_id: description: - Security group id (or list of ids) to use with the instance. type: list version_added: '1.1' version_added_collection: ansible.builtin key_name: aliases: - keypair description: - key pair to use on the instance. The SSH key must exist on AWS in order to use this argument. If you want to generate keys from Ansible, take a look at `ec2_key` module. type: str count_tag: description: - 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. version_added: '1.5' version_added_collection: ansible.builtin spot_type: choices: - one-time - persistent default: one-time description: - Type of spot request; one of "one-time" or "persistent". Defaults to "one-time" if not supplied. type: str version_added: '2.0' version_added_collection: ansible.builtin user_data: description: - Opaque blob of data which is made available to the EC2 instance. type: str version_added: '0.9' version_added_collection: ansible.builtin aws_config: description: - A dictionary to modify the botocore configuration. - Parameters can be found at U(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 U(http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto) for more boto configuration. type: dict monitoring: default: 'no' description: - Enable detailed monitoring (CloudWatch) for instance. type: bool version_added: '1.1' version_added_collection: ansible.builtin private_ip: description: - The private ip address to assign the instance (from the vpc subnet). type: str version_added: '1.2' version_added_collection: ansible.builtin spot_price: description: - 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. type: str version_added: '1.5' version_added_collection: ansible.builtin exact_count: description: - 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. type: int version_added: '1.5' version_added_collection: ansible.builtin instance_ids: aliases: - instance_id description: - 'list of instance ids, currently used for states: absent, running, stopped' type: list version_added: '1.3' version_added_collection: ansible.builtin wait_timeout: default: 300 description: - How long before wait gives up, in seconds. type: int aws_ca_bundle: description: - The location of a CA Bundle to use when validating SSL certificates. - Not used by boto 2 based modules. - 'Note: The CA Bundle is read ''module'' side and may need to be explicitly copied from the controller if not run locally.' type: path ebs_optimized: default: 'no' description: - whether instance is using optimized EBS volumes, see U(https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSOptimized.html). type: bool version_added: '1.6' version_added_collection: ansible.builtin instance_tags: description: - A hash/dictionary of tags to add to the new instance or for starting/stopping instance by tag; '{"key":"value"}' and '{"key":"value","key":"value"}'. type: dict version_added: '1.0' version_added_collection: ansible.builtin instance_type: description: - Instance type to use for the instance, see U(https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-types.html). required: true type: str vpc_subnet_id: description: - the subnet ID in which to launch the instance (VPC). type: str version_added: '1.1' version_added_collection: ansible.builtin aws_access_key: aliases: - ec2_access_key - access_key description: - C(AWS access key). If not set then the value of the C(AWS_ACCESS_KEY_ID), C(AWS_ACCESS_KEY) or C(EC2_ACCESS_KEY) environment variable is used. - If I(profile) is set this parameter is ignored. - Passing the I(aws_access_key) and I(profile) options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01. type: str aws_secret_key: aliases: - ec2_secret_key - secret_key description: - C(AWS secret key). If not set then the value of the C(AWS_SECRET_ACCESS_KEY), C(AWS_SECRET_KEY), or C(EC2_SECRET_KEY) environment variable is used. - If I(profile) is set this parameter is ignored. - Passing the I(aws_secret_key) and I(profile) options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01. type: str security_token: aliases: - aws_session_token - session_token - aws_security_token - access_token description: - C(AWS STS security token). If not set then the value of the C(AWS_SECURITY_TOKEN) or C(EC2_SECURITY_TOKEN) environment variable is used. - If I(profile) is set this parameter is ignored. - Passing the I(security_token) and I(profile) options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01. - Aliases I(aws_session_token) and I(session_token) have been added in version 3.2.0. type: str validate_certs: default: true description: - When set to "no", SSL certificates will not be validated for communication with the AWS APIs. type: bool placement_group: description: - Placement group for the instance when using EC2 Clustered Compute. type: str version_added: '1.3' version_added_collection: ansible.builtin assign_public_ip: description: - When provisioning within vpc, assign a public IP address. Boto library must be 2.13.0+. type: bool version_added: '1.5' version_added_collection: ansible.builtin source_dest_check: description: - 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. type: bool version_added: '1.6' version_added_collection: ansible.builtin spot_launch_group: description: - Launch group for spot request, see U(https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/how-spot-instances-work.html#spot-launch-group). type: str version_added: '2.1' version_added_collection: ansible.builtin spot_wait_timeout: default: 600 description: - How long to wait for the spot instance request to be fulfilled. Affects 'Request valid until' for setting spot request lifespan. type: int version_added: '1.5' version_added_collection: ansible.builtin network_interfaces: aliases: - network_interface description: - 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.) type: list version_added: '2.0' version_added_collection: ansible.builtin instance_profile_name: description: - 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+. type: str version_added: '1.3' version_added_collection: ansible.builtin termination_protection: default: 'no' description: - Enable or Disable the Termination Protection. type: bool version_added: '2.0' version_added_collection: ansible.builtin debug_botocore_endpoint_logs: default: 'no' description: - 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. type: bool instance_initiated_shutdown_behavior: choices: - stop - terminate default: stop description: - 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). type: str version_added: '2.2' version_added_collection: ansible.builtin