Amazon Web Services: EC2 - Instances

Summary

This module contains actions for viewing & managing EC2 instances.

Actions

aws.ec2.instances.

add_to_security_group

Add an instance to a security group.

Minimum Plugin Version: 2.2.0

Input

• aws_client: an AWSClient dictionary

• region_name: the EC2 region name

• instance_id: the instance ID

• security_group_id: the security group ID

Output

Nothing is outputted by this action.

Example

- aws.ec2.instances.add_to_security_group:
    region_name: eu-west-2
  load:
    instance_id: instance.id
    security_group_id: security_group.id
    aws_client: aws_secrets

aws.ec2.instances.

get_all

Get all instances.

Minimum Plugin Version: 2.0.0

Input

• aws_client: an AWSClient dictionary

• region_name: the EC2 region name

• vpc_id: the VPC ID to look in (defaults to all VPCs for the supplied region)

Output

A list of EC2Instance dictionaries.

Example

- aws.ec2.instances.get_all:
    region_name: eu-west-2
  load:
    aws_client: aws_secrets
  save: all_instances

aws.ec2.instances.

get_by_id

Get an instance with a specific instance ID.

Minimum Plugin Version: 2.0.0

Input

• aws_client: an AWSClient dictionary

• region_name: the EC2 region name

• instance_id: the instance ID to search for

Output

A single EC2Instance dictionary.

Example

- aws.ec2.instances.get_by_id:
    region_name: eu-west-2
    instance_id: i-0e88060c12d5d7e71
  load:
    aws_client: aws_secrets
  save: instance

aws.ec2.instances.

get_by_name

Get instances with a specific name.

Minimum Plugin Version: 2.0.0

Instance Naming

Instances don't have a name attribute, so this action searches for the Name tag instead.

This tag is set automatically when you name an instance in the AWS console.

Unlike security groups, multiple instances can exist with the same name.

Input

• aws_client: an AWSClient dictionary

• region_name: the EC2 region name

• name: the instance name to search for

• vpc_id: the VPC ID to look in (defaults to all VPCs for the supplied region)

Output

A list of EC2Instance dictionaries.

Example

- aws.ec2.instances.get_by_name:
    region_name: eu-west-2
    name: Ubuntu Server
  load:
    aws_client: aws_secrets
  save: ubuntu_server_instances

aws.ec2.instances.

get_by_tags

Get instances with all the supplied tag values.

Minimum Plugin Version: 2.3.0

Input

• aws_client: an AWSClient dictionary

• region_name: the EC2 region name

• tags: a dictionary of tag names & values to use in the search

• vpc_id: the VPC ID to look in (defaults to all VPCs for the supplied region)

Output

A list of EC2Instance dictionaries.

Case Sensitivity

Tags are case sensitive & must match the names & values configured in EC2.

Example

- aws.ec2.instances.get_by_tags:
    region_name: eu-west-2
    tags:
      environment: development
      team: engineering
  load:
    aws_client: aws_secrets
  save: development_instances

aws.ec2.instances.

get_running

Get running instances.

Minimum Plugin Version: 2.0.0

Input

• aws_client: an AWSClient dictionary

• region_name: the EC2 region name

• vpc_id: the VPC ID to look in (defaults to all VPCs for the supplied region)

Output

A list of EC2Instance dictionaries.

Example

- aws.ec2.instances.get_running:
    region_name: eu-west-2
  load:
    aws_client: aws_secrets
  save: running_instances

aws.ec2.instances.

get_stopped

Get stopped instances.

This includes all hibernating instances.

Minimum Plugin Version: 2.0.0

Input

• aws_client: an AWSClient dictionary

• region_name: the EC2 region name

• vpc_id: the VPC ID to look in (defaults to all VPCs for the supplied region)

Output

A list of EC2Instance dictionaries.

Example

- aws.ec2.instances.get_stopped:
    region_name: eu-west-2
  load:
    aws_client: aws_secrets
  save: stopped_instances

aws.ec2.instances.

get_untagged

Get untagged instances.

Minimum Plugin Version: 2.0.0

Input

• aws_client: an AWSClient dictionary

• region_name: the EC2 region name

• vpc_id: the VPC ID to look in (defaults to all VPCs for the supplied region)

Output

A list of EC2Instance dictionaries.

Example

- aws.ec2.instances.get_untagged:
    region_name: eu-west-2
  load:
    aws_client: aws_secrets
  save: untagged_instances

aws.ec2.instances.

input_table

Display a list of instances in a table, & allow the task operator to make a selection.

The table will have the following columns:

• Name
• ID
• State
• Public DNS Name
• Private DNS Name
• VPC ID

Minimum Plugin Version: 2.0.0

Input

• text: the title of the table

• instances: a list of EC2Instance dictionaries to display in the table

• minimum: The minimum number of acceptable selections

• maximum: The maximum number of acceptable selections

Output

A list of EC2Instance dictionaries.

Tip

• If neither a minimum or maximum is provided, the task operator will be able to submit 0 selections.

• If minimum or maximum are provided, the operation will repeat until a valid number of selections is made.

Example

Finding instances with get_all, saving them as groups, & waiting for a single selection:

- aws.ec2.instances.get_all:
    region_name: eu-west-2
  load:
    aws_client: aws_secrets
  save: instances

- aws.ec2.instances.input_table:
    text: Choose an instance
    minimum: 1
    maximum: 1
  load:
    instances: instances
  save: selected_instance

aws.ec2.instances.

launch

Launch a new instance from an AMI.

Minimum Plugin Version: 2.2.0

Input

• aws_client: an AWSClient dictionary

• region_name: the EC2 region name

• image_id: the ID of the AMI to launch the new instance from

• name: a name for the new instance (defaults to empty)

• instance_type: the instance type (defaults to t2.micro, see EC2 Instance Types for more information)

• key_name: the name of the key-pair to use (defaults to empty)

• subnet_id: the ID of the subnet to launch the instance in (defaults to the default VPC subnet)

Output

A single EC2Instance dictionary containing the new instance.

Example

- aws.ec2.instances.launch:
    region_name: eu-west-2
    image_id: ami-0a669382ea0feb73a
    instance_type: t2.micro
    key_name: linux-key-pair
    name: new-instance
  load:
    aws_client: aws_secrets
  save: new_instance

aws.ec2.instances.

output_table

Display a list of instances in a table.

The table will have the following columns:

• Name
• ID
• State
• Public DNS Name
• Private DNS Name
• VPC ID

Minimum Plugin Version: 2.0.0

Input

• text: the title of the table

• instances: a single or list of EC2Instance dictionaries

Output

Nothing is outputted by this action.

Single Instance

Finding an instance with get_by_id, saving it as instance, & displaying it:

- aws.ec2.instances.get_by_id:
    region_name: eu-west-2
    instance_id: i-0e88060c12d5d7e71
  load:
    aws_client: aws_secrets
  save: instance

- aws.ec2.instances.output_table:
    text: Instance i-0e88060c12d5d7e71
  load:
    instances: instance

Multiple Instances

Finding all instances with get_all, saving them as instances, & displaying them:

- aws.ec2.instances.get_all:
    region_name: eu-west-2
  load:
    aws_client: aws_secrets
  save: instances

- aws.ec2.instances.output_table:
    text: All Instances
  load:
    instances: instances

aws.ec2.instances.

remove_from_security_group

Remove an instance from a security group.

Minimum Plugin Version: 2.2.0

Input

• aws_client: an AWSClient dictionary

• region_name: the EC2 region name

• instance_id: the instance ID

• security_group_id: the security group ID

Output

Nothing is outputted by this action.

Example

- aws.ec2.instances.remove_from_security_group:
    region_name: eu-west-2
  load:
    instance_id: instance.id
    security_group_id: security_group.id
    aws_client: aws_secrets

aws.ec2.instances.

start

Start an instance.

Minimum Plugin Version: 2.0.0

Input

• aws_client: an AWSClient dictionary

• region_name: the EC2 region name

• instance_id: the ID of the instance to start

Output

Nothing is outputted by this action.

Example

- aws.ec2.instances.start:
    region_name: eu-west-2
    instance_id: i-0e88060c12d5d7e71
  load:
    aws_client: aws_secrets

aws.ec2.instances.

stop

Stop an instance.

Minimum Plugin Version: 2.0.0

Input

• aws_client: an AWSClient dictionary

• region_name: the EC2 region name

• instance_id: the ID of the instance to stop

Output

Nothing is outputted by this action.

Example

- aws.ec2.instances.stop:
    region_name: eu-west-2
    instance_id: i-0e88060c12d5d7e71
  load:
    aws_client: aws_secrets

aws.ec2.instances.

tag

Apply one or more tags to an instance.

Minimum Plugin Version: 2.2.0

Input

• aws_client: an AWSClient dictionary

• region_name: the EC2 region name

• instance_id: the instance ID

• tags: a dictionary of tags to apply to the instance

Overwriting Tags

If any tags supplied to this action already exist on the instance, their values will be overwritten.

Output

Nothing is outputted by this action.

Example

- aws.ec2.instances.tag:
    region_name: eu-west-2
    tags:
      environment: uat
      replicated: false
  load:
    instance_id: instance.id
    aws_client: aws_secrets

aws.ec2.instances.

terminate

Terminate an instance.

Minimum Plugin Version: 2.0.0

Input

• aws_client: an AWSClient dictionary

• region_name: the EC2 region name

• instance_id: the ID of the instance to terminate

Output

Nothing is outputted by this action.

Example

- aws.ec2.instances.terminate:
    region_name: eu-west-2
    instance_id: i-0e88060c12d5d7e71
  load:
    aws_client: aws_secrets