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.
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
ami_id	id of found amazon image	when AMI found	string	ami-e9095e8c
architecture	architecture of image	when AMI found	string	x86_64
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' }
creationDate	creation date of image	when AMI found	string	2015-10-15T22:43:44.000Z
description	description of image	when AMI found	string	test-server01
hypervisor	type of hypervisor	when AMI found	string	xen
is_public	whether image is public	when AMI found	bool	False
location	location of image	when AMI found	string	435210894375/test-server01-20151015-234343
name	ami name of image	when AMI found	string	test-server01-20151015-234343
owner_id	owner of image	when AMI found	string	435210894375
platform	platform of image	when AMI found	string	None
root_device_name	root device name of image	when AMI found	string	/dev/xvda
root_device_type	root device type of image	when AMI found	string	ebs
state	state of image	when AMI found	string	available
tags	tags assigned to image	when AMI found	dict	{ 'Environment': 'devel', 'Name': 'test-server01', 'Role': 'web' }
virtualization_type	image virtualization type	when AMI found	string	hvm

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.

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

Docs

Docs4dev

Title here

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

Synopsis

Requirements (on host that executes module)

Options

Examples

Return Values

Notes

Status