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

Install Ansible via pip

Install with pip install ansible==2.8.19

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

• boto
• python >= 2.6

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

ec2_url:
    aliases:
    - aws_endpoint_url
    - endpoint_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

profile:
    aliases:
    - aws_profile
    description:
    - Uses a boto profile. Only works with boto >= 2.24.0.
    - Using I(profile) will override I(aws_access_key), I(aws_secret_key) and I(security_token)
      and support for passing them at the same time as I(profile) has been deprecated.
    - I(aws_access_key), I(aws_secret_key) and I(security_token) will be made mutually
      exclusive with I(profile) after 2022-06-01.
    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).
    - Only the 'user_agent' key is used for boto modules. See U(http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto)
      for more boto configuration.
    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).

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.
    - Only used for boto3 based modules.
    - '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:
    - AWS access key. If not set then the value of the AWS_ACCESS_KEY_ID, AWS_ACCESS_KEY
      or EC2_ACCESS_KEY environment variable is used.
    - If I(profile) is set this parameter is ignored.
    - Passing the I(aws_access_key) and I(profile) options at the same time has been deprecated
      and the options will be made mutually exclusive after 2022-06-01.
    type: str

aws_secret_key:
    aliases:
    - ec2_secret_key
    - secret_key
    description:
    - AWS secret key. If not set then the value of the AWS_SECRET_ACCESS_KEY, AWS_SECRET_KEY,
      or EC2_SECRET_KEY environment variable is used.
    - If I(profile) is set this parameter is ignored.
    - Passing the I(aws_secret_key) and I(profile) options at the same time has been deprecated
      and the options will be made mutually exclusive after 2022-06-01.
    type: str

security_token:
    aliases:
    - aws_security_token
    - access_token
    description:
    - AWS STS security token. If not set then the value of the AWS_SECURITY_TOKEN or EC2_SECURITY_TOKEN
      environment variable is used.
    - If I(profile) is set this parameter is ignored.
    - Passing the I(security_token) and I(profile) options at the same time has been deprecated
      and the options will be made mutually exclusive after 2022-06-01.
    type: str

validate_certs:
    default: true
    description:
    - When set to "no", SSL certificates will not be validated for boto versions >= 2.6.0.
    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: str
architecture:
  description: architecture of image
  returned: when AMI found
  sample: x86_64
  type: str
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: str
description:
  description: description of image
  returned: when AMI found
  sample: test-server01
  type: str
hypervisor:
  description: type of hypervisor
  returned: when AMI found
  sample: xen
  type: str
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: str
name:
  description: ami name of image
  returned: when AMI found
  sample: test-server01-20151015-234343
  type: str
owner_id:
  description: owner of image
  returned: when AMI found
  sample: '435210894375'
  type: str
platform:
  description: platform of image
  returned: when AMI found
  sample: null
  type: str
root_device_name:
  description: root device name of image
  returned: when AMI found
  sample: /dev/xvda
  type: str
root_device_type:
  description: root device type of image
  returned: when AMI found
  sample: ebs
  type: str
state:
  description: state of image
  returned: when AMI found
  sample: available
  type: str
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: str