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.