steampunk / steampunk.aws / 0.9.0 / module / ec2_instance Manage EC2 instances Authors: Manca Bizjak (@mancabizjak), Aljaz Kosir (@aljazkosir), Saso Stanovnik (@sstanovnik), Miha Dolinar (@mdolinar), Tadej Borovsak (@tadeboro) preview | supported by XLAB Steampunksteampunk.aws.ec2_instance (0.9.0) — module
Install with ansible-galaxy collection install steampunk.aws:==0.9.0
collections: - name: steampunk.aws version: 0.9.0
Create, update or delete an AWS EC2 instance.
- 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
id: description: - 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 ami: description: - ID of the Amazon Machine Image used to launch the instance. - This parameter is required when creating a new instance. - In the absence of I(id) and I(network_interface), the value of this parameter will be used in conjunction with I(name) and I(subnet) to identify the instance. type: str auth: description: - Parameters for authenticating with the AWS service. Each of them may be defined via environment variables. suboptions: access_key: description: - The AWS access key ID. If not set, the value of the AWS_ACCESS_KEY environment variable will be checked. - Mutually exclusive with I(profile). required: false type: str profile: description: - The name of the AWS profile configured with C(aws configure). - Can be used instead of explicitly specifying your access credentials and region. - Use C(default) to use the default profile. - Mutually exclusive with I(access_key) and I(secret_key). required: false type: str region: description: - The name of the AWS region. - If not set, the value of the AWS_REGION environment variable will be checked. - If you set a I(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: description: - The AWS secret access key. If not set, the value of the AWS_SECRET_KEY environment variable will be checked. - Mutually exclusive with I(profile). required: false type: str url: description: - 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_<SERVICE>_URL environment variable will be used. - The services currently supported are EC2 and S3. required: false type: str type: dict name: description: - Name tag for the EC2 instance. - This parameter is required when creating a new instance. - In the absence of I(id) and I(network_interface), the value of this parameter will be used in conjunction with I(ami) and I(subnet) to identify the instance. type: str tags: description: - Metadata for the AWS resource as key/value pairs. - Keys and values are case-sensitive. type: dict type: description: - 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 state: choices: - present - absent default: present description: - 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 I(wait_state) to C(false) to modify this behavior. - Note that terminated instances are treated as absent. type: str subnet: description: - ID of the subnet where the instance will be launched from. - This parameter is required when creating an instance if neither I(availability_zone) nor I(network_interface) are specified. - If omitted, the instance will be created in the default subnet for the availability zone specified in C(availability_zone) of the default VPC for I(auth.region). type: str tenancy: choices: - default - dedicated description: - 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 key_pair: description: - Name of the key pair to be used when connecting to the instance. - This parameter is required when creating an instance. type: str clear_tags: default: false description: - Whether to clear any existing tags on the resource that are not explicitly stated in I(tags). - By default, existing tags are kept on the resource. - When this parameter is set to C(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 I(name) parameter. type: bool monitoring: choices: - basic - detailed description: - CloudWatch monitoring mode for the instance. - If you omit this parameter when creating a new instance, the default value C(basic) will be used. type: str wait_state: default: true description: - Whether the module should wait (block) until I(state) is reached. - For newly created instances - if I(state) is C(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 I(state) is C(absent) and this parameter is set, the module initiates instance termination and continues. Otherwise it waits until the instance is terminated. type: bool security_groups: description: - 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 M(steampunk.aws.ec2_network_interface). - This parameter is mutually exclusive with I(network_interface). elements: str type: list availability_zone: description: - ID of the availability zone in which to create the instance. - This parameter is required when creating an instance if neither I(subnet) nor I(network_interface) are specified. - If C(subnet) is provided, this parameter is ignored. - If C(id) is not provided, at least one of I(subnet), I(availability_zone) is required. type: str network_interface: description: - 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 I(subnet) or I(availability_zone). If I(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 I(security_groups) to configure it. - Note that the I(network_interface) cannot be modified after instance is launched. Use M(steampunk.aws.ec2_network_interface) to attach any additional ENIs to the instance. - This parameter is mutually exclusive with I(security_groups), I(subnet) and I(availability_zone). type: str on_instance_initiated_shutdown: choices: - stop - terminate description: - Default behavior for instance-initiated shutdown. - If you omit this parameter when creating a new instance, the default value C(stop) will be used. type: str
object: contains: ami: description: ID of the AMI used to launched the instance. returned: always sample: ami-0343ab73df9eb1496 type: str availability_zone: description: ID of the availability zone for the instance. returned: always sample: az-use-1 type: str id: description: ID of the EC2 instance. returned: always sample: i-841b9271gd type: str key_pair: description: Name of the key pair to be used when connecting to the instance. returned: always sample: my-key-pair type: str launched_at: description: The time when instance was launched. returned: always sample: '2020-04-15T08:08:40+00:00' type: str monitoring: description: CloudWatch monitoring mode for the instance. returned: always sample: detailed type: str network_interface: description: ID of the instance's primary network interface. returned: always sample: eni-2dfr38df335 type: str on_instance_initiated_shutdown: description: The behavior when shut down is initiated from the instance. returned: always sample: terminate type: str secondary_network_interfaces: description: IDs of the secondary network interfaces attached to the instance. returned: always sample: [] type: list security_groups: description: IDs of security groups associated with the instance. returned: always sample: - sg-27fhs72gs922f type: list state: description: State of the EC2 instance as reported by AWS. returned: always sample: running type: str subnet: description: ID of the subnet containing the instance. returned: always sample: subnet-14hs85ns83hg type: str tenancy: description: The instance tenancy setting. returned: always sample: default type: str type: description: EC2 instance type. returned: always sample: a1.xsmall type: str vpc: description: ID of the VPC containing the instance. returned: always sample: vpc-129385ns2s2 type: str description: - An object representing the EC2 Instance. returned: success and I(state)=C(present) type: complex