images

Creates, updates, deletes, gets or lists an images resource.

Overview

Name	images
Type	Resource
Id	aws.ecr.images

Fields

The following fields are returned by SELECT queries:

batch_get_image

Name	Datatype	Description
failures	array	Any failures associated with the call.
images	array	A list of image objects corresponding to the image references in the request.

describe_images

Name	Datatype	Description
artifact_media_type	string	The artifact media type of the image.
image_digest	string	The sha256 digest of the image manifest.
image_manifest_media_type	string	The media type of the image manifest.
image_pushed_at	string (date-time)	The date and time, expressed in standard JavaScript date format, at which the current image was pushed to the repository.
image_scan_findings_summary	object	A summary of the last completed image scan.
image_scan_status	object	The current state of the scan.
image_size_in_bytes	integer (int64)	The size, in bytes, of the image in the repository. If the image is a manifest list, this will be the max size of all manifests in the list. Starting with Docker version 1.9, the Docker client compresses image layers before pushing them to a V2 Docker registry. The output of the docker images command shows the uncompressed image size. Therefore, Docker might return a larger image than the image shown in the Amazon Web Services Management Console.
image_status	string	The current status of the image. (ACTIVE, ARCHIVED, ACTIVATING)
image_tags	array	The list of tags associated with this image.
last_activated_at	string (date-time)	The date and time, expressed in standard JavaScript date format, when the image was last restored from Amazon ECR archive to Amazon ECR standard.
last_archived_at	string (date-time)	The date and time, expressed in standard JavaScript date format, when the image was last transitioned to Amazon ECR archive.
last_recorded_pull_time	string (date-time)	The date and time, expressed in standard JavaScript date format, when Amazon ECR recorded the last image pull. Amazon ECR refreshes the last image pull timestamp at least once every 24 hours. For example, if you pull an image once a day then the lastRecordedPullTime timestamp will indicate the exact time that the image was last pulled. However, if you pull an image once an hour, because Amazon ECR refreshes the lastRecordedPullTime timestamp at least once every 24 hours, the result may not be the exact time that the image was last pulled.
registry_id	string	The Amazon Web Services account ID associated with the registry to which this image belongs. (pattern: <code>[0-9]{12}</code>)
repository_name	string	The name of the repository to which this image belongs. (pattern: <code>[a-z0-9]+((.||__|-+)[a-z0-9]+)*(/[a-z0-9]+((.||__|-+)[a-z0-9]+))</code>)
subject_manifest_digest	string	The digest of the subject manifest for images that are referrers.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
batch_get_image	select	region		Gets detailed information for an image. Images are specified with either an imageTag or imageDigest. When an image is pulled, the BatchGetImage API is called once to retrieve the image manifest.
describe_images	select	region		Returns metadata about the images in a repository. Starting with Docker version 1.9, the Docker client compresses image layers before pushing them to a V2 Docker registry. The output of the docker images command shows the uncompressed image size. Therefore, Docker might return a larger image than the image shown in the Amazon Web Services Management Console. The new version of Amazon ECR Basic Scanning doesn't use the ImageDetail$imageScanFindingsSummary and ImageDetail$imageScanStatus attributes from the API response to return scan results. Use the DescribeImageScanFindings API instead. For more information about Amazon Web Services native basic scanning, see Scan images for software vulnerabilities in Amazon ECR.
update_image_storage_class	update	region, repositoryName, imageId, targetStorageClass		Transitions an image between storage classes. You can transition images from Amazon ECR standard storage class to Amazon ECR archival storage class for long-term storage, or restore archived images back to Amazon ECR standard.
put_image	replace	region, repositoryName, imageManifest		Creates or updates the image manifest and tags associated with an image. When an image is pushed and all new image layers have been uploaded, the PutImage API is called once to create or update the image manifest and the tags associated with the image. This operation is used by the Amazon ECR proxy and is not generally used by customers for pulling and pushing images. In most cases, you should use the docker CLI to pull, tag, and push images.
put_image_scanning_configuration	replace	region, repositoryName, imageScanningConfiguration		The PutImageScanningConfiguration API is being deprecated, in favor of specifying the image scanning configuration at the registry level. For more information, see PutRegistryScanningConfiguration. Updates the image scanning configuration for the specified repository.
put_image_tag_mutability	replace	region, repositoryName, imageTagMutability		Updates the image tag mutability settings for the specified repository. For more information, see Image tag mutability in the Amazon Elastic Container Registry User Guide.
list_images	exec	region, repositoryName		Lists all the image IDs for the specified repository. You can filter images based on whether or not they are tagged by using the tagStatus filter and specifying either TAGGED, UNTAGGED or ANY. For example, you can filter your results to return only UNTAGGED images and then pipe that result to a BatchDeleteImage operation to delete them. Or, you can filter your results to return only TAGGED images to list all of the tags in your repository.
start_image_scan	exec	region, repositoryName, imageId		Starts a basic image vulnerability scan. A basic image scan can only be started once per 24 hours on an individual image. This limit includes if an image was scanned on initial push. You can start up to 100,000 basic scans per 24 hours. This limit includes both scans on initial push and scans initiated by the StartImageScan API. For more information, see Basic scanning in the Amazon Elastic Container Registry User Guide.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
region	string	AWS region (default: us-east-1)

SELECT examples

batch_get_image

Gets detailed information for an image. Images are specified with either an imageTag or imageDigest. When an image is pulled, the BatchGetImage API is called once to retrieve the image manifest.

SELECT
failures,
images
FROM aws.ecr.images
WHERE region = '{{ region }}' -- required
;

describe_images

Returns metadata about the images in a repository. Starting with Docker version 1.9, the Docker client compresses image layers before pushing them to a V2 Docker registry. The output of the docker images command shows the uncompressed image size. Therefore, Docker might return a larger image than the image shown in the Amazon Web Services Management Console. The new version of Amazon ECR Basic Scanning doesn't use the ImageDetail$imageScanFindingsSummary and ImageDetail$imageScanStatus attributes from the API response to return scan results. Use the DescribeImageScanFindings API instead. For more information about Amazon Web Services native basic scanning, see Scan images for software vulnerabilities in Amazon ECR.

SELECT
artifact_media_type,
image_digest,
image_manifest_media_type,
image_pushed_at,
image_scan_findings_summary,
image_scan_status,
image_size_in_bytes,
image_status,
image_tags,
last_activated_at,
last_archived_at,
last_recorded_pull_time,
registry_id,
repository_name,
subject_manifest_digest
FROM aws.ecr.images
WHERE region = '{{ region }}' -- required
;

UPDATE examples

update_image_storage_class

Transitions an image between storage classes. You can transition images from Amazon ECR standard storage class to Amazon ECR archival storage class for long-term storage, or restore archived images back to Amazon ECR standard.

UPDATE aws.ecr.images
SET 
registryId = '{{ registryId }}',
repositoryName = '{{ repositoryName }}',
imageId = '{{ imageId }}',
targetStorageClass = '{{ targetStorageClass }}'
WHERE 
region = '{{ region }}' --required
AND repositoryName = '{{ repositoryName }}' --required
AND imageId = '{{ imageId }}' --required
AND targetStorageClass = '{{ targetStorageClass }}' --required
RETURNING
image_id,
image_status,
registry_id,
repository_name;

REPLACE examples

put_image

Creates or updates the image manifest and tags associated with an image. When an image is pushed and all new image layers have been uploaded, the PutImage API is called once to create or update the image manifest and the tags associated with the image. This operation is used by the Amazon ECR proxy and is not generally used by customers for pulling and pushing images. In most cases, you should use the docker CLI to pull, tag, and push images.

REPLACE aws.ecr.images
SET 
registryId = '{{ registryId }}',
repositoryName = '{{ repositoryName }}',
imageManifest = '{{ imageManifest }}',
imageManifestMediaType = '{{ imageManifestMediaType }}',
imageTag = '{{ imageTag }}',
imageDigest = '{{ imageDigest }}'
WHERE 
region = '{{ region }}' --required
AND repositoryName = '{{ repositoryName }}' --required
AND imageManifest = '{{ imageManifest }}' --required
RETURNING
image;

put_image_scanning_configuration

The PutImageScanningConfiguration API is being deprecated, in favor of specifying the image scanning configuration at the registry level. For more information, see PutRegistryScanningConfiguration. Updates the image scanning configuration for the specified repository.

REPLACE aws.ecr.images
SET 
registryId = '{{ registryId }}',
repositoryName = '{{ repositoryName }}',
imageScanningConfiguration = '{{ imageScanningConfiguration }}'
WHERE 
region = '{{ region }}' --required
AND repositoryName = '{{ repositoryName }}' --required
AND imageScanningConfiguration = '{{ imageScanningConfiguration }}' --required
RETURNING
image_scanning_configuration,
registry_id,
repository_name;

put_image_tag_mutability

Updates the image tag mutability settings for the specified repository. For more information, see Image tag mutability in the Amazon Elastic Container Registry User Guide.

REPLACE aws.ecr.images
SET 
registryId = '{{ registryId }}',
repositoryName = '{{ repositoryName }}',
imageTagMutability = '{{ imageTagMutability }}',
imageTagMutabilityExclusionFilters = '{{ imageTagMutabilityExclusionFilters }}'
WHERE 
region = '{{ region }}' --required
AND repositoryName = '{{ repositoryName }}' --required
AND imageTagMutability = '{{ imageTagMutability }}' --required
RETURNING
image_tag_mutability,
image_tag_mutability_exclusion_filters,
registry_id,
repository_name;

Lifecycle Methods

list_images

Lists all the image IDs for the specified repository. You can filter images based on whether or not they are tagged by using the tagStatus filter and specifying either TAGGED, UNTAGGED or ANY. For example, you can filter your results to return only UNTAGGED images and then pipe that result to a BatchDeleteImage operation to delete them. Or, you can filter your results to return only TAGGED images to list all of the tags in your repository.

EXEC aws.ecr.images.list_images 
@region='{{ region }}' --required 
@@json=
'{
"registryId": "{{ registryId }}", 
"repositoryName": "{{ repositoryName }}", 
"nextToken": "{{ nextToken }}", 
"maxResults": {{ maxResults }}, 
"filter": "{{ filter }}"
}'
;

start_image_scan

Starts a basic image vulnerability scan. A basic image scan can only be started once per 24 hours on an individual image. This limit includes if an image was scanned on initial push. You can start up to 100,000 basic scans per 24 hours. This limit includes both scans on initial push and scans initiated by the StartImageScan API. For more information, see Basic scanning in the Amazon Elastic Container Registry User Guide.

EXEC aws.ecr.images.start_image_scan 
@region='{{ region }}' --required 
@@json=
'{
"registryId": "{{ registryId }}", 
"repositoryName": "{{ repositoryName }}", 
"imageId": "{{ imageId }}"
}'
;