steampunk.aws.ec2_instance (0.9.0) — module

Install collection

Install with ansible-galaxy collection install steampunk.aws:==0.9.0

Add to requirements.yml

  collections:
    - name: steampunk.aws
      version: 0.9.0

Description

Create, update or delete an AWS EC2 instance.

Usage examples

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- 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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- name: Update EC2 instance configuration
  ec2_instance:
    id: "{{ my_instance.object.id }}"
    on_instance_initiated_shutdown: terminate
    monitoring: detailed

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- 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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- name: Terminate an EC2 instance
  ec2_instance:
    id: "{{ my_instance.object.id }}"
    state: absent

Inputs

    
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

Outputs

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

See also

• ec2_instance_info
• ec2_network_interface