Amazon AMI

source	condition	target
✔	✔	✗

source

condition

target

✔

✗

Description

The aws/ami resource queries the EC2 API for Amazon Machine Images matching a set of filters.

source: Returns the AMI ID of the first image in the sorted result set.
condition: Tests that at least one AMI matches the filters.
target: Not supported - an AMI is not something Updatecli publishes. A target fails with Target not supported for the plugin AWS/AMI.

Important

Unlike most resources, which merely ignore an scm, this one aborts a condition that has one attached:

condition with SCM is not supported

Drop the scmid from the condition; the lookup is always against the EC2 API.

Parameters

Name	Type	Description
accesskey	string	“accesskey” defines the AWS access key used to authenticate. compatible: source condition remark: it is only used when “secretkey” is also set. when unset, the default AWS credential chain is used.
dryrun	boolean	“dryrun” checks whether you have the required permissions for the action, without making the request. compatible: source condition default: false
endpoint	string	“endpoint” defines the AWS endpoint used to look for AMIs. compatible: source condition default: https://ec2..amazonaws.com
filters	array	“filters” defines the list of filters used to select AMIs. compatible: source condition remark: at least one filter is required in a source. in a condition, when no “image-id” filter is set, the source output is used as the “image-id” filter. the accepted filter names are listed on https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeImages.html example: `filters: - name: "name" values: "ubuntu/images/hvm-ssd/ubuntu-jammy-22.04-amd64-server-*" - name: "architecture" values: "x86_64"`
name	string	“name” defines the filter name. example: name: architecture
values	string	“values” defines the filter values. remark: several values are separated by a comma. example: values: x86_64 values: “x86_64,arm64”
region	string	“region” defines the AWS region used to look for AMIs. compatible: source condition default: us-east-1 example: region: eu-west-1
secretkey	string	“secretkey” defines the AWS secret key used to authenticate. compatible: source condition remark: it is only used when “accesskey” is also set. when unset, the default AWS credential chain is used.
sortby	string	“sortby” defines the order of the AMIs found, the last one being returned. compatible: source condition remark: accepted values are “creationdateasc” and “creationdatedesc”, case insensitive. when unset, the order returned by the AWS API is kept. example: sortby: creationdateasc

region: The AWS region to query. AMI IDs are region-specific, so the same filters return different IDs per region.
endpoint: Overrides the EC2 endpoint, for a non-AWS or private deployment.
accesskey / secretkey: Credentials. Prefer '{{ requiredEnv "AWS_ACCESS_KEY_ID" }}' over literals in the manifest, or leave them unset to fall back to the ambient AWS configuration.
dryrun: Passes the EC2 DryRun flag, which checks permissions without running the query.

Considering that the AMI resource is designed to manipulate the latest AMI found based on filters, the parameter SortBy can be used to specify how the list of results is sorted which affects the latest element returned.

sortBy accepts one of the following creationDateAsc and creationDateDesc where they will respectively return the newest or the oldest AMI ID based on creation time.

Filter

AMI are identified based on different filters such as platform, name, etc.

Name	Required	Default	Description
Name	✔	-	Define the filter Name.
Values	✔	-	Define the filter value associated to the filter name.

Name

Required

Default

Description

Name

✔

Define the filter Name.

Values

✔

Define the filter value associated to the filter name.

Name

architecture - The image architecture (i386 | x86_64 | arm64).
block-device-mapping.delete-on-termination - A Boolean value that indicates whether the Amazon EBS volume is deleted on instance termination.
block-device-mapping.device-name - The device name specified in the block device mapping (for example, /dev/sdh or xvdh).
block-device-mapping.snapshot-id - The ID of the snapshot used for the EBS volume.
block-device-mapping.volume-size - The volume size of the EBS volume, in GiB.
block-device-mapping.volume-type - The volume type of the EBS volume (gp3 | gp2 | io1 | io2 | st1 | sc1 | standard).
block-device-mapping.encrypted - A Boolean that indicates whether the EBS volume is encrypted.
description - The description of the image (provided during image creation).
ena-support - A Boolean that indicates whether enhanced networking with ENA is enabled.
hypervisor - The hypervisor type (ovm | xen).
image-id - The ID of the image.
image-type - The image type (machine | kernel | ramdisk).
is-public - A Boolean that indicates whether the image is public.
kernel-id - The kernel ID.
manifest-location - The location of the image manifest.
name - The name of the AMI (provided during image creation).
owner-alias - The owner alias (amazon | aws-marketplace). The valid aliases are defined in an Amazon-maintained list. This is not the AWS account alias that can be set using the IAM console. We recommend that you use the Owner request parameter instead of this filter.
owner-id - The AWS account ID of the owner. We recommend that you use the Owner request parameter instead of this filter.
platform - The platform. To only list Windows-based AMIs, use windows.
product-code - The product code.
product-code.type - The type of the product code (devpay | marketplace).
ramdisk-id - The RAM disk ID.
root-device-name - The device name of the root device volume (for example, /dev/sda1).
root-device-type - The type of the root device volume (ebs | instance-store).
state - The state of the image (available | pending | failed).
state-reason-code - The reason code for the state change.
state-reason-message - The message for the state change.
sriov-net-support - A value of simple indicates that enhanced networking with the Intel 82599 VF interface is enabled.
tag:<key> - The key/value combination of a tag assigned to the resource. Use the tag key in the filter name and the tag value as the filter value. For example, to find all resources that have a tag with the key Owner and the value TeamA, specify tag:Owner for the filter name and TeamA for the filter value.
tag-key - The key of a tag assigned to the resource. Use this filter to find all resources assigned a tag with a specific key, regardless of the tag value.
virtualization-type - The virtualization type (paravirtual | hvm).

Authentication

Different mechanisms can be used to authenticate with AWS API. They are applied in the following order.

Environment Variables
Shared Credentials Files
Updatecli configuration

Environment Variables

updatecli retrieves credentials from the environment variables.

Environment variables used:

Access Key ID: AWS_ACCESS_KEY_ID or AWS_ACCESS_KEY
Secret Access Key: AWS_SECRET_ACCESS_KEY or AWS_SECRET_KEY

Shared Credentials File

updatecli can retrieve credentials from the AWS cli credential file. By default, it looks for the file location into AWS_SHARED_CREDENTIALS_FILE env variable, otherwise it fall back to the current user’s home directory.

Linux/OSX: "$HOME/.aws/credentials"
Windows: "%USERPROFILE%\.aws\credentials"

The AWS "profile" used is defined by the environment variable AWS_PROFILE and fallback to "default" if not defined.

Updatecli configuration

Credentials can be provided directly in the manifest with accesskey and secretkey:

updatecli configuration

kind: aws/ami
name: resource to manipulate aws ami id
spec:
  accesskey: '{{ requiredEnv "AWS_ACCESS_KEY_ID" }}'
  secretkey: '{{ requiredEnv "AWS_SECRET_ACCESS_KEY" }}'
  filters:
    - name: "name"
      values: "image name"

Warning

The names are accesskey and secretkey, with no underscore. Earlier versions of this page showed access_key and secret_key, which do not match any field.

Unknown keys in a spec are silently ignored rather than rejected, so a misspelled credential does not raise an error, Updatecli simply falls back to the environment or the shared credentials file, and you get an AuthFailure from AWS that looks like a permissions problem:

AWS API Error - Code: AuthFailure, Message: AWS was not able to validate the provided access credentials

IAM Policy

To work, we need at least the following IAM policy

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Action": [
                "ec2:ReadTags",
                "ec2:DescribeInstances",
                "ec2:DescribeRegions",
                "ec2:DescribeImages",
                "ec2:DescribeAvailabilityZones"
            ],
            "Effect": "Allow",
            "Resource": "*"
        }
    ]
}

Example

---
title: Bump agent templates version on all controllers
sources:
  packerImageVersion:
    kind: githubRelease
    spec:
      owner: "jenkins-infra"
      repository: "packer-images"
      token: '{{ requiredEnv "UPDATECLI_GITHUB_TOKEN" }}'
      username: '{{ requiredEnv "UPDATECLI_GITHUB_ACTOR" }}'
  getLatestUbuntuAgentAMIAmd64:
    kind: aws/ami
    depends_on:
      - packerImageVersion
    spec:
      region: us-east-2
      filters:
        - name: "name"
          values: "jenkins-agent-ubuntu-20-amd64-*"
        - name: "tag:build_type"
          values: "prod"
        - name: "tag:version"
          values: '{{ source "packerImageVersion" }}'
  getLatestWindowsAgentAMIAmd64:
    kind: aws/ami
    depends_on:
      - packerImageVersion
    spec:
      region: us-east-2
      filters:
        - name: "name"
          values: "jenkins-agent-windows-2019-amd64-*"
        - name: "tag:build_type"
          values: "prod"
        - name: "tag:version"
          values: '{{ source "packerImageVersion" }}'
  getLatestUbuntuAgentAMIArm64:
    kind: aws/ami
    depends_on:
      - packerImageVersion
    spec:
      region: us-east-2
      filters:
        - name: "name"
          values: "jenkins-agent-ubuntu-20-arm64-*"
        - name: "tag:build_type"
          values: "prod"
        - name: "tag:version"
          values: '{{ source "packerImageVersion" }}'

targets:
  setUbuntuAgentAMIAmd64:
    name: "Bump AMI ID for Ubuntu AMD64 agents"
    kind: shell
    sourceID: getLatestUbuntuAgentAMIAmd64
    spec:
      command: echo ubuntu-amd
  setUbuntuAgentAMIArm64:
    name: "Bump AMI ID for Ubuntu ARM64 agents"
    kind: shell
    sourceID: getLatestUbuntuAgentAMIArm64
    spec:
      command: echo ubuntu-arm
  setWindowsAgentAMIAmd64:
    name: "Bump AMI ID for Windows AMD64 agents"
    kind: shell
    sourceID: getLatestWindowsAgentAMIAmd64
    spec:
      command: echo windows-amd

Last updated on August 2, 2026

Github Search

Github

Docs

Updatecli

Title here

Amazon AMI

Description

Parameters

SortBy

Filter

Name

Authentication

Environment Variables

Shared Credentials File

Updatecli configuration

IAM Policy

Example