W3cubDocs

/Ansible

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

Requirements (on host that executes module)

  • python >= 2.6
  • boto

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.
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 Common Return Values, the following are the fields unique to this module:

name description returned type sample
root_device_type rood 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 dictionary of block devices { '/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 rood 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 dictionary of tags { '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.

Note

See the example below for a suggestion of how to search by distro/release.

This is a Core Module

For more information on what this means please read Core Modules

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

© 2012–2016 Michael DeHaan
© 2016 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/ec2_ami_find_module.html