Documentation

ec2_ami_find - Searches for AMIs to obtain the AMI ID and other information

New in version 2.0.

Synopsis

  • Returns list of matching AMIs with AMI ID, along with other useful information
  • Can search AMIs with different owners
  • Can search by matching tag(s), by AMI name and/or other criteria
  • Results can be sorted and sliced

Options

parameter required default choices comments
ami_id
 no
An AMI ID to match.
ami_tags
 no
A hash/dictionary of tags to match for the AMI.
architecture
 no
An architecture type to match (e.g. x86_64).
hypervisor
 no
A hypervisor type type to match (e.g. xen).
is_public
 no
  • yes
  • no
Whether or not the image(s) are public.
name
 no
An AMI name to match.
no_result_action
 no success
  • success
  • fail
What to do when no results are found.
'success' reports success and returns an empty array
'fail' causes the module to report failure
owner
 no
Search AMIs owned by the specified owner
Can specify an AWS account ID, or one of the special IDs 'self', 'amazon' or 'aws-marketplace'
If not specified, all EC2 AMIs in the specified region will be searched.
You can include wildcards in many of the search options. An asterisk (*) matches zero or more characters, and a question mark (?) matches exactly one character. You can escape special characters using a backslash (\) before the character. For example, a value of \*amazon\?\ searches for the literal string *amazon?\.
platform
 no
Platform type to match.
product_code
(added in 2.3)
 no
Marketplace product code to match.
region
 yes
The AWS region to use.

aliases: aws_region, ec2_region
sort
 no
  • name
  • description
  • tag
  • architecture
  • block_device_mapping
  • creationDate
  • hypervisor
  • is_public
  • location
  • owner_id
  • platform
  • root_device_name
  • root_device_type
  • state
  • virtualization_type
Optional attribute which with to sort the results.
If specifying 'tag', the 'tag_name' parameter is required.
Starting at version 2.1, additional sort choices of architecture, block_device_mapping, creationDate, hypervisor, is_public, location, owner_id, platform, root_device_name, root_device_type, state, and virtualization_type are supported.
sort_end
 no
Which result to end with (when sorting).
Corresponds to Python slice notation.
sort_order
 no ascending
  • ascending
  • descending
Order in which to sort results.
Only used when the 'sort' parameter is specified.
sort_start
 no
Which result to start with (when sorting).
Corresponds to Python slice notation.
sort_tag
 no
Tag name with which to sort results.
Required when specifying 'sort=tag'.
state
 no available
AMI state to match.
virtualization_type
 no
Virtualization type to match (e.g. hvm).

Examples

# Note: These examples do not set authentication details, see the AWS Guide for details.

# Search for the AMI tagged "project:website"
- ec2_ami_find:
    owner: self
    ami_tags:
      project: website
    no_result_action: fail
  register: ami_find

# Search for the latest Ubuntu 14.04 AMI
- ec2_ami_find:
    name: "ubuntu/images/ebs/ubuntu-trusty-14.04-amd64-server-*"
    owner: 099720109477
    sort: name
    sort_order: descending
    sort_end: 1
  register: ami_find

# Launch an EC2 instance
- ec2:
    image: "{{ ami_find.results[0].ami_id }}"
    instance_type: m3.medium
    key_name: mykey
    wait: yes

Return Values

Common return values are documented here Return Values, the following are the fields unique to this module:

name description returned type sample
root_device_type
root device type of image
 when AMI found string ebs
description
description of image
 when AMI found string test-server01
block_device_mapping
block device mapping associated with image
 when AMI found dict { '/dev/xvda': { 'delete_on_termination': true, 'encrypted': false, 'size': 8, 'snapshot_id': 'snap-ca0330b8', 'volume_type': 'gp2' }
is_public
whether image is public
 when AMI found bool False
creationDate
creation date of image
 when AMI found string 2015-10-15T22:43:44.000Z
root_device_name
root device name of image
 when AMI found string /dev/xvda
ami_id
id of found amazon image
 when AMI found string ami-e9095e8c
name
ami name of image
 when AMI found string test-server01-20151015-234343
hypervisor
type of hypervisor
 when AMI found string xen
tags
tags assigned to image
 when AMI found dict { 'Environment': 'devel', 'Name': 'test-server01', 'Role': 'web' }
location
location of image
 when AMI found string 435210894375/test-server01-20151015-234343
platform
platform of image
 when AMI found string None
state
state of image
 when AMI found string available
architecture
architecture of image
 when AMI found string x86_64
virtualization_type
image virtualization type
 when AMI found string hvm
owner_id
owner of image
 when AMI found string 435210894375


Notes

Note

  • This module is not backwards compatible with the previous version of the ec2_search_ami module which worked only for Ubuntu AMIs listed on cloud-images.ubuntu.com.
  • See the example below for a suggestion of how to search by distro/release.

Status

This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.

For help in developing on modules, should you be so inclined, please read Community Information & Contributing, Testing Ansible and Developing Modules.