.. meta:: :description: Create, update or delete an AWS EC2 instance. .. _ec2_instance_module: ec2_instance -- Manage EC2 instances ==================================== Create, update or delete an AWS EC2 instance. Examples -------- .. code-block:: yaml+jinja - name: Launch an EC2 instance in a specific subnet ec2_instance: name: first-instance type: a1.medium ami: ami-0343ab73df9eb1496 key_pair: my-keypair subnet: subnet-870717cd register: my_instance - name: Update EC2 instance configuration ec2_instance: id: "{{ my_instance.object.id }}" on_instance_initiated_shutdown: terminate monitoring: detailed - name: Launch another EC2 instance ec2_instance: name: second-instance type: t2.micro ami: ami-0343ab73df9eb1496 key_pair: my-keypair network_interface: eni-2j66sa32jfs2f2d tags: env: staging - name: Terminate an EC2 instance ec2_instance: id: "{{ my_instance.object.id }}" state: absent See Also -------- .. seealso:: - :ref:`ec2_instance_info_module` - :ref:`ec2_network_interface_module` Parameters ---------- ami (optional) ID of the Amazon Machine Image used to launch the instance. This parameter is required when creating a new instance. In the absence of *id* and *network_interface*, the value of this parameter will be used in conjunction with *name* and *subnet* to identify the instance. | **type**: str auth (optional) Parameters for authenticating with the AWS service. Each of them may be defined via environment variables. | **type**: dict access_key (optional) The AWS access key ID. If not set, the value of the AWS_ACCESS_KEY environment variable will be checked. Mutually exclusive with *profile*. | **type**: str profile (optional) The name of the AWS profile configured with ``aws configure``. Can be used instead of explicitly specifying your access credentials and region. Use ``default`` to use the default profile. Mutually exclusive with *access_key* and *secret_key*. | **type**: str region (optional) The name of the AWS region. If not set, the value of the AWS_REGION environment variable will be checked. If you set a *profile* that specifies a default region, that region is used and you can omit this parameter. Use this parameter to override the profile's default region. | **type**: str secret_key (optional) The AWS secret access key. If not set, the value of the AWS_SECRET_KEY environment variable will be checked. Mutually exclusive with *profile*. | **type**: str url (optional) The URL to the AWS service related to the resource. By default, this is automatically determined through the region parameter. If not set explicitly, the value of the AWS__URL environment variable will be used. The services currently supported are EC2 and S3. | **type**: str availability_zone (optional) ID of the availability zone in which to create the instance. This parameter is required when creating an instance if neither *subnet* nor *network_interface* are specified. If ``subnet`` is provided, this parameter is ignored. If ``id`` is not provided, at least one of *subnet*, *availability_zone* is required. | **type**: str clear_tags (optional) Whether to clear any existing tags on the resource that are not explicitly stated in *tags*. By default, existing tags are kept on the resource. When this parameter is set to ``true``, any pre-existing tags on the resource (including the name tag) are removed. To clear all tags except the name tag, make sure to provide the *name* parameter. | **type**: bool id (optional) ID of the resource to perform the task on. If specified, this parameter is used to identify the resource. Omit this parameter when you are first creating the resource. | **type**: str key_pair (optional) Name of the key pair to be used when connecting to the instance. This parameter is required when creating an instance. | **type**: str monitoring (optional) CloudWatch monitoring mode for the instance. If you omit this parameter when creating a new instance, the default value ``basic`` will be used. | **type**: str | **choices**: basic, detailed name (optional) Name tag for the EC2 instance. This parameter is required when creating a new instance. In the absence of *id* and *network_interface*, the value of this parameter will be used in conjunction with *ami* and *subnet* to identify the instance. | **type**: str network_interface (optional) ID of an existing ENI to attach to the instance as the primary network interface (at device index 0). This parameter is required when creating an instance if you don't provide *subnet* or *availability_zone*. If *network_interface* points to an ENI that is already attached as a primary network interface for an instance, the module uses it to uniquely identify the instance. If this parameter is provided, the instance will be created in the subnet of the network interface. If this parameter is omitted when creating an instance, a default primary network interface will be automatically created and attached, and you can optionally set *security_groups* to configure it. Note that the *network_interface* cannot be modified after instance is launched. Use :ref:`steampunk.aws.ec2_network_interface ` to attach any additional ENIs to the instance. This parameter is mutually exclusive with *security_groups*, *subnet* and *availability_zone*. | **type**: str on_instance_initiated_shutdown (optional) Default behavior for instance-initiated shutdown. If you omit this parameter when creating a new instance, the default value ``stop`` will be used. | **type**: str | **choices**: stop, terminate security_groups (optional) IDs of security groups that will be associated with the default primary network interface. If omitted, the VPC's default security group will be used. Use this parameter if you wish to configure the default primary network interface that will be created automatically when a new instance is launched. To modify security groups of the default network interface created for you on instance launch, use :ref:`steampunk.aws.ec2_network_interface `. This parameter is mutually exclusive with *network_interface*. | **type**: list state (optional) The desired state of the EC2 instance. When creating a new instance, the default behavior of the module is to wait until the instance is in running state on AWS. Set *wait_state* to ``false`` to modify this behavior. Note that terminated instances are treated as absent. | **type**: str | **default**: present | **choices**: present, absent subnet (optional) ID of the subnet where the instance will be launched from. This parameter is required when creating an instance if neither *availability_zone* nor *network_interface* are specified. If omitted, the instance will be created in the default subnet for the availability zone specified in ``availability_zone`` of the default VPC for *auth.region*. | **type**: str tags (optional) Metadata for the AWS resource as key/value pairs. Keys and values are case-sensitive. | **type**: dict tenancy (optional) The instance tenancy setting. If omitted, the VPC's default instance tenancy setting will be used. You cannot modify this setting after an instance is launched. | **type**: str | **choices**: default, dedicated type (optional) Type of the EC2 instance. This parameter is required when creating a new instance. Currently it is not possible to modify the instance type after an instance is launched. | **type**: str wait_state (optional) Whether the module should wait (block) until *state* is reached. For newly created instances - if *state* is ``present`` and this parameter is set, the module ensures a running instance. Otherwise it ensures an instance that exists on AWS, but is not necessarily in running state. Note that this parameter has no effect when you're updating an existing instance. If *state* is ``absent`` and this parameter is set, the module initiates instance termination and continues. Otherwise it waits until the instance is terminated. | **type**: bool | **default**: True Return Values ------------- object (success and I(state)=C(present)), complex, An object representing the EC2 Instance. id (always), str, i-841b9271gd ID of the EC2 instance. launched_at (always), str, 2020-04-15T08:08:40+00:00 The time when instance was launched. type (always), str, a1.xsmall EC2 instance type. ami (always), str, ami-0343ab73df9eb1496 ID of the AMI used to launched the instance. vpc (always), str, vpc-129385ns2s2 ID of the VPC containing the instance. subnet (always), str, subnet-14hs85ns83hg ID of the subnet containing the instance. availability_zone (always), str, az-use-1 ID of the availability zone for the instance. security_groups (always), list, ['sg-27fhs72gs922f'] IDs of security groups associated with the instance. network_interface (always), str, eni-2dfr38df335 ID of the instance's primary network interface. secondary_network_interfaces (always), list, [] IDs of the secondary network interfaces attached to the instance. key_pair (always), str, my-key-pair Name of the key pair to be used when connecting to the instance. tenancy (always), str, default The instance tenancy setting. monitoring (always), str, detailed CloudWatch monitoring mode for the instance. on_instance_initiated_shutdown (always), str, terminate The behavior when shut down is initiated from the instance. state (always), str, running State of the EC2 instance as reported by AWS.