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

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 plaform 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, Helping Testing PRs and Developing Modules.