ansible.builtin._ec2_ami_find (v2.6.20) — module

Install Ansible via pip

Install with pip install ansible==2.6.20

Description

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

• python >= 2.6
• boto

Usage examples

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

# 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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

# 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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

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

Inputs

    
name:
    description:
    - An AMI name to match.

sort:
    choices:
    - name
    - description
    - tag
    - architecture
    - block_device_mapping
    - creationDate
    - hypervisor
    - is_public
    - location
    - owner_id
    - platform
    - root_device_name
    - root_device_type
    - state
    - virtualization_type
    description:
    - 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.

owner:
    description:
    - 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?\.

state:
    default: available
    description:
    - AMI state to match.

ami_id:
    description:
    - An AMI ID to match.

region:
    aliases:
    - aws_region
    - ec2_region
    description:
    - The AWS region to use.
    required: true

profile:
    aliases:
    - aws_profile
    description:
    - The I(profile) option is mutually exclusive with the I(aws_access_key), I(aws_secret_key)
      and I(security_token) options.
    type: str

ami_tags:
    description:
    - A hash/dictionary of tags to match for the AMI.

platform:
    description:
    - Platform type to match.

sort_end:
    description:
    - Which result to end with (when sorting).
    - Corresponds to Python slice notation.

sort_tag:
    description:
    - Tag name with which to sort results.
    - Required when specifying 'sort=tag'.

is_public:
    description:
    - Whether or not the image(s) are public.
    type: bool

aws_config:
    description:
    - A dictionary to modify the botocore configuration.
    - Parameters can be found at U(https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config).
    type: dict

hypervisor:
    description:
    - A hypervisor type type to match (e.g. xen).

sort_order:
    choices:
    - ascending
    - descending
    default: ascending
    description:
    - Order in which to sort results.
    - Only used when the 'sort' parameter is specified.

sort_start:
    description:
    - Which result to start with (when sorting).
    - Corresponds to Python slice notation.

architecture:
    description:
    - An architecture type to match (e.g. x86_64).

endpoint_url:
    aliases:
    - ec2_url
    - aws_endpoint_url
    - s3_url
    description:
    - URL to use to connect to EC2 or your Eucalyptus cloud (by default the module will
      use EC2 endpoints). Ignored for modules where region is required. Must be specified
      for all other modules if region is not used. If not set then the value of the EC2_URL
      environment variable, if any, is used.
    type: str

product_code:
    description:
    - Marketplace product code to match.
    version_added: '2.3'
    version_added_collection: ansible.builtin

aws_ca_bundle:
    description:
    - The location of a CA Bundle to use when validating SSL certificates.
    - 'Note: The CA Bundle is read ''module'' side and may need to be explicitly copied
      from the controller if not run locally.'
    type: path

aws_access_key:
    aliases:
    - ec2_access_key
    - access_key
    description:
    - C(AWS access key). If not set then the value of the C(AWS_ACCESS_KEY_ID), C(AWS_ACCESS_KEY)
      or C(EC2_ACCESS_KEY) environment variable is used.
    - The I(aws_access_key) and I(profile) options are mutually exclusive.
    type: str

aws_secret_key:
    aliases:
    - ec2_secret_key
    - secret_key
    description:
    - C(AWS secret key). If not set then the value of the C(AWS_SECRET_ACCESS_KEY), C(AWS_SECRET_KEY),
      or C(EC2_SECRET_KEY) environment variable is used.
    - The I(aws_secret_key) and I(profile) options are mutually exclusive.
    type: str

security_token:
    aliases:
    - aws_session_token
    - session_token
    - aws_security_token
    - access_token
    description:
    - C(AWS STS security token). If not set then the value of the C(AWS_SECURITY_TOKEN)
      or C(EC2_SECURITY_TOKEN) environment variable is used.
    - The I(security_token) and I(profile) options are mutually exclusive.
    - Aliases I(aws_session_token) and I(session_token) have been added in version 3.2.0.
    type: str

validate_certs:
    default: true
    description:
    - When set to "no", SSL certificates will not be validated for communication with
      the AWS APIs.
    type: bool

no_result_action:
    choices:
    - success
    - fail
    default: success
    description:
    - What to do when no results are found.
    - '''success'' reports success and returns an empty array'
    - '''fail'' causes the module to report failure'

root_device_type:
    description:
    - Root device type to match (e.g. ebs, instance-store).
    version_added: '2.5'
    version_added_collection: ansible.builtin

virtualization_type:
    description:
    - Virtualization type to match (e.g. hvm).

debug_botocore_endpoint_logs:
    default: 'no'
    description:
    - Use a botocore.endpoint logger to parse the unique (rather than total) "resource:action"
      API calls made during a task, outputing the set to the resource_actions key in the
      task results. Use the aws_resource_action callback to output to total list made
      during a playbook. The ANSIBLE_DEBUG_BOTOCORE_LOGS environment variable may also
      be used.
    type: bool

Outputs

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