2025/11/19 - Amazon Elastic Container Registry - 5 new 8 updated api methods
Changes Add support for ECR archival storage class and Inspector org policy for scanning
Lists the artifacts associated with a specified subject image.
See also: AWS API Documentation
Request Syntax
client.list_image_referrers(
registryId='string',
repositoryName='string',
subjectId={
'imageDigest': 'string'
},
filter={
'artifactTypes': [
'string',
],
'artifactStatus': 'ACTIVE'|'ARCHIVED'|'ACTIVATING'|'ANY'
},
nextToken='string',
maxResults=123
)
string
The Amazon Web Services account ID associated with the registry that contains the repository in which to list image referrers. If you do not specify a registry, the default registry is assumed.
string
[REQUIRED]
The name of the repository that contains the subject image.
dict
[REQUIRED]
An object containing the image digest of the subject image for which to retrieve associated artifacts.
imageDigest (string) -- [REQUIRED]
The digest of the image.
dict
The filter key and value with which to filter your ListImageReferrers results. If no filter is specified, only artifacts with ACTIVE status are returned.
artifactTypes (list) --
The artifact types with which to filter your ListImageReferrers results.
(string) --
artifactStatus (string) --
The artifact status with which to filter your ListImageReferrers results. Valid values are ACTIVE, ARCHIVED, ACTIVATING, or ANY. If not specified, only artifacts with ACTIVE status are returned.
string
The nextToken value returned from a previous paginated ListImageReferrers request where maxResults was used and the results exceeded the value of that parameter. Pagination continues from the end of the previous results that returned the nextToken value. This value is null when there are no more results to return.
integer
The maximum number of image referrer results returned by ListImageReferrers in paginated output. When this parameter is used, ListImageReferrers only returns maxResults results in a single page along with a nextToken response element. The remaining results of the initial request can be seen by sending another ListImageReferrers request with the returned nextToken value. This value can be between 1 and 50. If this parameter is not used, then ListImageReferrers returns up to 50 results and a nextToken value, if applicable.
dict
Response Syntax
{
'referrers': [
{
'digest': 'string',
'mediaType': 'string',
'artifactType': 'string',
'size': 123,
'annotations': {
'string': 'string'
},
'artifactStatus': 'ACTIVE'|'ARCHIVED'|'ACTIVATING'
},
],
'nextToken': 'string'
}
Response Structure
(dict) --
referrers (list) --
The list of artifacts associated with the subject image.
(dict) --
An object representing an artifact associated with a subject image.
digest (string) --
The digest of the artifact manifest.
mediaType (string) --
The media type of the artifact manifest.
artifactType (string) --
A string identifying the type of artifact.
size (integer) --
The size, in bytes, of the artifact.
annotations (dict) --
A map of annotations associated with the artifact.
(string) --
(string) --
artifactStatus (string) --
The status of the artifact. Valid values are ACTIVE, ARCHIVED, or ACTIVATING.
nextToken (string) --
The nextToken value to include in a future ListImageReferrers request. When the results of a ListImageReferrers request exceed maxResults, this value can be used to retrieve the next page of results. This value is null when there are no more results to return.
Lists the IAM principals that are excluded from having their image pull times recorded.
See also: AWS API Documentation
Request Syntax
client.list_pull_time_update_exclusions(
maxResults=123,
nextToken='string'
)
integer
The maximum number of pull time update exclusion results returned by ListPullTimeUpdateExclusions in paginated output. When this parameter is used, ListPullTimeUpdateExclusions only returns maxResults results in a single page along with a nextToken response element. The remaining results of the initial request can be seen by sending another ListPullTimeUpdateExclusions request with the returned nextToken value. This value can be between 1 and 1000. If this parameter is not used, then ListPullTimeUpdateExclusions returns up to 100 results and a nextToken value, if applicable.
string
The nextToken value returned from a previous paginated ListPullTimeUpdateExclusions request where maxResults was used and the results exceeded the value of that parameter. Pagination continues from the end of the previous results that returned the nextToken value. This value is null when there are no more results to return.
dict
Response Syntax
{
'pullTimeUpdateExclusions': [
'string',
],
'nextToken': 'string'
}
Response Structure
(dict) --
pullTimeUpdateExclusions (list) --
The list of IAM principal ARNs that are excluded from having their image pull times recorded.
(string) --
nextToken (string) --
The nextToken value to include in a future ListPullTimeUpdateExclusions request. When the results of a ListPullTimeUpdateExclusions request exceed maxResults, this value can be used to retrieve the next page of results. This value is null when there are no more results to return.
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.
See also: AWS API Documentation
Request Syntax
client.update_image_storage_class(
registryId='string',
repositoryName='string',
imageId={
'imageDigest': 'string',
'imageTag': 'string'
},
targetStorageClass='STANDARD'|'ARCHIVE'
)
string
The Amazon Web Services account ID associated with the registry that contains the image to transition. If you do not specify a registry, the default registry is assumed.
string
[REQUIRED]
The name of the repository that contains the image to transition.
dict
[REQUIRED]
An object with identifying information for an image in an Amazon ECR repository.
imageDigest (string) --
The sha256 digest of the image manifest.
imageTag (string) --
The tag used for the image.
string
[REQUIRED]
The target storage class for the image.
dict
Response Syntax
{
'registryId': 'string',
'repositoryName': 'string',
'imageId': {
'imageDigest': 'string',
'imageTag': 'string'
},
'imageStatus': 'ACTIVE'|'ARCHIVED'|'ACTIVATING'
}
Response Structure
(dict) --
registryId (string) --
The registry ID associated with the request.
repositoryName (string) --
The repository name associated with the request.
imageId (dict) --
An object with identifying information for an image in an Amazon ECR repository.
imageDigest (string) --
The sha256 digest of the image manifest.
imageTag (string) --
The tag used for the image.
imageStatus (string) --
The current status of the image after the call to UpdateImageStorageClass is complete. Valid values are ACTIVE, ARCHIVED, and ACTIVATING.
Adds an IAM principal to the pull time update exclusion list for a registry. Amazon ECR will not record the pull time if an excluded principal pulls an image.
See also: AWS API Documentation
Request Syntax
client.register_pull_time_update_exclusion(
principalArn='string'
)
string
[REQUIRED]
The ARN of the IAM principal to exclude from having image pull times recorded.
dict
Response Syntax
{
'principalArn': 'string',
'createdAt': datetime(2015, 1, 1)
}
Response Structure
(dict) --
principalArn (string) --
The ARN of the IAM principal that was added to the pull time update exclusion list.
createdAt (datetime) --
The date and time, expressed in standard JavaScript date format, when the exclusion was created.
Removes a principal from the pull time update exclusion list for a registry. Once removed, Amazon ECR will resume updating the pull time if the specified principal pulls an image.
See also: AWS API Documentation
Request Syntax
client.deregister_pull_time_update_exclusion(
principalArn='string'
)
string
[REQUIRED]
The ARN of the IAM principal to remove from the pull time update exclusion list.
dict
Response Syntax
{
'principalArn': 'string'
}
Response Structure
(dict) --
principalArn (string) --
The ARN of the IAM principal that was removed from the pull time update exclusion list.
{'layers': {'layerAvailability': {'ARCHIVED'}}}
Checks the availability of one or more image layers in a repository.
When an image is pushed to a repository, each image layer is checked to verify if it has been uploaded before. If it has been uploaded, then the image layer is skipped.
See also: AWS API Documentation
Request Syntax
client.batch_check_layer_availability(
registryId='string',
repositoryName='string',
layerDigests=[
'string',
]
)
string
The Amazon Web Services account ID associated with the registry that contains the image layers to check. If you do not specify a registry, the default registry is assumed.
string
[REQUIRED]
The name of the repository that is associated with the image layers to check.
list
[REQUIRED]
The digests of the image layers to check.
(string) --
dict
Response Syntax
{
'layers': [
{
'layerDigest': 'string',
'layerAvailability': 'AVAILABLE'|'UNAVAILABLE'|'ARCHIVED',
'layerSize': 123,
'mediaType': 'string'
},
],
'failures': [
{
'layerDigest': 'string',
'failureCode': 'InvalidLayerDigest'|'MissingLayerDigest',
'failureReason': 'string'
},
]
}
Response Structure
(dict) --
layers (list) --
A list of image layer objects corresponding to the image layer references in the request.
(dict) --
An object representing an Amazon ECR image layer.
layerDigest (string) --
The sha256 digest of the image layer.
layerAvailability (string) --
The availability status of the image layer.
layerSize (integer) --
The size, in bytes, of the image layer.
mediaType (string) --
The media type of the layer, such as application/vnd.docker.image.rootfs.diff.tar.gzip or application/vnd.oci.image.layer.v1.tar+gzip.
failures (list) --
Any failures associated with the call.
(dict) --
An object representing an Amazon ECR image layer failure.
layerDigest (string) --
The layer digest associated with the failure.
failureCode (string) --
The failure code associated with the failure.
failureReason (string) --
The reason for the failure.
{'failures': {'failureCode': {'ImageInaccessible'}}}
Deletes a list of specified images within a repository. Images are specified with either an imageTag or imageDigest.
You can remove a tag from an image by specifying the image's tag in your request. When you remove the last tag from an image, the image is deleted from your repository.
You can completely delete an image (and all of its tags) by specifying the image's digest in your request.
See also: AWS API Documentation
Request Syntax
client.batch_delete_image(
registryId='string',
repositoryName='string',
imageIds=[
{
'imageDigest': 'string',
'imageTag': 'string'
},
]
)
string
The Amazon Web Services account ID associated with the registry that contains the image to delete. If you do not specify a registry, the default registry is assumed.
string
[REQUIRED]
The repository that contains the image to delete.
list
[REQUIRED]
A list of image ID references that correspond to images to delete. The format of the imageIds reference is imageTag=tag or imageDigest=digest.
(dict) --
An object with identifying information for an image in an Amazon ECR repository.
imageDigest (string) --
The sha256 digest of the image manifest.
imageTag (string) --
The tag used for the image.
dict
Response Syntax
{
'imageIds': [
{
'imageDigest': 'string',
'imageTag': 'string'
},
],
'failures': [
{
'imageId': {
'imageDigest': 'string',
'imageTag': 'string'
},
'failureCode': 'InvalidImageDigest'|'InvalidImageTag'|'ImageTagDoesNotMatchDigest'|'ImageNotFound'|'MissingDigestAndTag'|'ImageReferencedByManifestList'|'KmsError'|'UpstreamAccessDenied'|'UpstreamTooManyRequests'|'UpstreamUnavailable'|'ImageInaccessible',
'failureReason': 'string'
},
]
}
Response Structure
(dict) --
imageIds (list) --
The image IDs of the deleted images.
(dict) --
An object with identifying information for an image in an Amazon ECR repository.
imageDigest (string) --
The sha256 digest of the image manifest.
imageTag (string) --
The tag used for the image.
failures (list) --
Any failures associated with the call.
(dict) --
An object representing an Amazon ECR image failure.
imageId (dict) --
The image ID associated with the failure.
imageDigest (string) --
The sha256 digest of the image manifest.
imageTag (string) --
The tag used for the image.
failureCode (string) --
The code associated with the failure.
failureReason (string) --
The reason for the failure.
{'failures': {'failureCode': {'ImageInaccessible'}}}
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.
See also: AWS API Documentation
Request Syntax
client.batch_get_image(
registryId='string',
repositoryName='string',
imageIds=[
{
'imageDigest': 'string',
'imageTag': 'string'
},
],
acceptedMediaTypes=[
'string',
]
)
string
The Amazon Web Services account ID associated with the registry that contains the images to describe. If you do not specify a registry, the default registry is assumed.
string
[REQUIRED]
The repository that contains the images to describe.
list
[REQUIRED]
A list of image ID references that correspond to images to describe. The format of the imageIds reference is imageTag=tag or imageDigest=digest.
(dict) --
An object with identifying information for an image in an Amazon ECR repository.
imageDigest (string) --
The sha256 digest of the image manifest.
imageTag (string) --
The tag used for the image.
list
The accepted media types for the request.
Valid values: application/vnd.docker.distribution.manifest.v1+json | application/vnd.docker.distribution.manifest.v2+json | application/vnd.oci.image.manifest.v1+json
(string) --
dict
Response Syntax
{
'images': [
{
'registryId': 'string',
'repositoryName': 'string',
'imageId': {
'imageDigest': 'string',
'imageTag': 'string'
},
'imageManifest': 'string',
'imageManifestMediaType': 'string'
},
],
'failures': [
{
'imageId': {
'imageDigest': 'string',
'imageTag': 'string'
},
'failureCode': 'InvalidImageDigest'|'InvalidImageTag'|'ImageTagDoesNotMatchDigest'|'ImageNotFound'|'MissingDigestAndTag'|'ImageReferencedByManifestList'|'KmsError'|'UpstreamAccessDenied'|'UpstreamTooManyRequests'|'UpstreamUnavailable'|'ImageInaccessible',
'failureReason': 'string'
},
]
}
Response Structure
(dict) --
images (list) --
A list of image objects corresponding to the image references in the request.
(dict) --
An object representing an Amazon ECR image.
registryId (string) --
The Amazon Web Services account ID associated with the registry containing the image.
repositoryName (string) --
The name of the repository associated with the image.
imageId (dict) --
An object containing the image tag and image digest associated with an image.
imageDigest (string) --
The sha256 digest of the image manifest.
imageTag (string) --
The tag used for the image.
imageManifest (string) --
The image manifest associated with the image.
imageManifestMediaType (string) --
The manifest media type of the image.
failures (list) --
Any failures associated with the call.
(dict) --
An object representing an Amazon ECR image failure.
imageId (dict) --
The image ID associated with the failure.
imageDigest (string) --
The sha256 digest of the image manifest.
imageTag (string) --
The tag used for the image.
failureCode (string) --
The code associated with the failure.
failureReason (string) --
The reason for the failure.
{'imageScanStatus': {'status': {'IMAGE_ARCHIVED'}}}
Returns the scan findings for the specified image.
See also: AWS API Documentation
Request Syntax
client.describe_image_scan_findings(
registryId='string',
repositoryName='string',
imageId={
'imageDigest': 'string',
'imageTag': 'string'
},
nextToken='string',
maxResults=123
)
string
The Amazon Web Services account ID associated with the registry that contains the repository in which to describe the image scan findings for. If you do not specify a registry, the default registry is assumed.
string
[REQUIRED]
The repository for the image for which to describe the scan findings.
dict
[REQUIRED]
An object with identifying information for an image in an Amazon ECR repository.
imageDigest (string) --
The sha256 digest of the image manifest.
imageTag (string) --
The tag used for the image.
string
The nextToken value returned from a previous paginated DescribeImageScanFindings request where maxResults was used and the results exceeded the value of that parameter. Pagination continues from the end of the previous results that returned the nextToken value. This value is null when there are no more results to return.
integer
The maximum number of image scan results returned by DescribeImageScanFindings in paginated output. When this parameter is used, DescribeImageScanFindings only returns maxResults results in a single page along with a nextToken response element. The remaining results of the initial request can be seen by sending another DescribeImageScanFindings request with the returned nextToken value. This value can be between 1 and 1000. If this parameter is not used, then DescribeImageScanFindings returns up to 100 results and a nextToken value, if applicable.
dict
Response Syntax
{
'registryId': 'string',
'repositoryName': 'string',
'imageId': {
'imageDigest': 'string',
'imageTag': 'string'
},
'imageScanStatus': {
'status': 'IN_PROGRESS'|'COMPLETE'|'FAILED'|'UNSUPPORTED_IMAGE'|'ACTIVE'|'PENDING'|'SCAN_ELIGIBILITY_EXPIRED'|'FINDINGS_UNAVAILABLE'|'LIMIT_EXCEEDED'|'IMAGE_ARCHIVED',
'description': 'string'
},
'imageScanFindings': {
'imageScanCompletedAt': datetime(2015, 1, 1),
'vulnerabilitySourceUpdatedAt': datetime(2015, 1, 1),
'findingSeverityCounts': {
'string': 123
},
'findings': [
{
'name': 'string',
'description': 'string',
'uri': 'string',
'severity': 'INFORMATIONAL'|'LOW'|'MEDIUM'|'HIGH'|'CRITICAL'|'UNDEFINED',
'attributes': [
{
'key': 'string',
'value': 'string'
},
]
},
],
'enhancedFindings': [
{
'awsAccountId': 'string',
'description': 'string',
'findingArn': 'string',
'firstObservedAt': datetime(2015, 1, 1),
'lastObservedAt': datetime(2015, 1, 1),
'packageVulnerabilityDetails': {
'cvss': [
{
'baseScore': 123.0,
'scoringVector': 'string',
'source': 'string',
'version': 'string'
},
],
'referenceUrls': [
'string',
],
'relatedVulnerabilities': [
'string',
],
'source': 'string',
'sourceUrl': 'string',
'vendorCreatedAt': datetime(2015, 1, 1),
'vendorSeverity': 'string',
'vendorUpdatedAt': datetime(2015, 1, 1),
'vulnerabilityId': 'string',
'vulnerablePackages': [
{
'arch': 'string',
'epoch': 123,
'filePath': 'string',
'name': 'string',
'packageManager': 'string',
'release': 'string',
'sourceLayerHash': 'string',
'version': 'string',
'fixedInVersion': 'string'
},
]
},
'remediation': {
'recommendation': {
'url': 'string',
'text': 'string'
}
},
'resources': [
{
'details': {
'awsEcrContainerImage': {
'architecture': 'string',
'author': 'string',
'imageHash': 'string',
'imageTags': [
'string',
],
'platform': 'string',
'pushedAt': datetime(2015, 1, 1),
'lastInUseAt': datetime(2015, 1, 1),
'inUseCount': 123,
'registry': 'string',
'repositoryName': 'string'
}
},
'id': 'string',
'tags': {
'string': 'string'
},
'type': 'string'
},
],
'score': 123.0,
'scoreDetails': {
'cvss': {
'adjustments': [
{
'metric': 'string',
'reason': 'string'
},
],
'score': 123.0,
'scoreSource': 'string',
'scoringVector': 'string',
'version': 'string'
}
},
'severity': 'string',
'status': 'string',
'title': 'string',
'type': 'string',
'updatedAt': datetime(2015, 1, 1),
'fixAvailable': 'string',
'exploitAvailable': 'string'
},
]
},
'nextToken': 'string'
}
Response Structure
(dict) --
registryId (string) --
The registry ID associated with the request.
repositoryName (string) --
The repository name associated with the request.
imageId (dict) --
An object with identifying information for an image in an Amazon ECR repository.
imageDigest (string) --
The sha256 digest of the image manifest.
imageTag (string) --
The tag used for the image.
imageScanStatus (dict) --
The current state of the scan.
status (string) --
The current state of an image scan.
description (string) --
The description of the image scan status.
imageScanFindings (dict) --
The information contained in the image scan findings.
imageScanCompletedAt (datetime) --
The time of the last completed image scan.
vulnerabilitySourceUpdatedAt (datetime) --
The time when the vulnerability data was last scanned.
findingSeverityCounts (dict) --
The image vulnerability counts, sorted by severity.
(string) --
(integer) --
findings (list) --
The findings from the image scan.
(dict) --
Contains information about an image scan finding.
name (string) --
The name associated with the finding, usually a CVE number.
description (string) --
The description of the finding.
uri (string) --
A link containing additional details about the security vulnerability.
severity (string) --
The finding severity.
attributes (list) --
A collection of attributes of the host from which the finding is generated.
(dict) --
This data type is used in the ImageScanFinding data type.
key (string) --
The attribute key.
value (string) --
The value assigned to the attribute key.
enhancedFindings (list) --
Details about the enhanced scan findings from Amazon Inspector.
(dict) --
The details of an enhanced image scan. This is returned when enhanced scanning is enabled for your private registry.
awsAccountId (string) --
The Amazon Web Services account ID associated with the image.
description (string) --
The description of the finding.
findingArn (string) --
The Amazon Resource Number (ARN) of the finding.
firstObservedAt (datetime) --
The date and time that the finding was first observed.
lastObservedAt (datetime) --
The date and time that the finding was last observed.
packageVulnerabilityDetails (dict) --
An object that contains the details of a package vulnerability finding.
cvss (list) --
An object that contains details about the CVSS score of a finding.
(dict) --
The CVSS score for a finding.
baseScore (float) --
The base CVSS score used for the finding.
scoringVector (string) --
The vector string of the CVSS score.
source (string) --
The source of the CVSS score.
version (string) --
The version of CVSS used for the score.
referenceUrls (list) --
One or more URLs that contain details about this vulnerability type.
(string) --
relatedVulnerabilities (list) --
One or more vulnerabilities related to the one identified in this finding.
(string) --
source (string) --
The source of the vulnerability information.
sourceUrl (string) --
A URL to the source of the vulnerability information.
vendorCreatedAt (datetime) --
The date and time that this vulnerability was first added to the vendor's database.
vendorSeverity (string) --
The severity the vendor has given to this vulnerability type.
vendorUpdatedAt (datetime) --
The date and time the vendor last updated this vulnerability in their database.
vulnerabilityId (string) --
The ID given to this vulnerability.
vulnerablePackages (list) --
The packages impacted by this vulnerability.
(dict) --
Information on the vulnerable package identified by a finding.
arch (string) --
The architecture of the vulnerable package.
epoch (integer) --
The epoch of the vulnerable package.
filePath (string) --
The file path of the vulnerable package.
name (string) --
The name of the vulnerable package.
packageManager (string) --
The package manager of the vulnerable package.
release (string) --
The release of the vulnerable package.
sourceLayerHash (string) --
The source layer hash of the vulnerable package.
version (string) --
The version of the vulnerable package.
fixedInVersion (string) --
The version of the package that contains the vulnerability fix.
remediation (dict) --
An object that contains the details about how to remediate a finding.
recommendation (dict) --
An object that contains information about the recommended course of action to remediate the finding.
url (string) --
The URL address to the CVE remediation recommendations.
text (string) --
The recommended course of action to remediate the finding.
resources (list) --
Contains information on the resources involved in a finding.
(dict) --
Details about the resource involved in a finding.
details (dict) --
An object that contains details about the resource involved in a finding.
awsEcrContainerImage (dict) --
An object that contains details about the Amazon ECR container image involved in the finding.
architecture (string) --
The architecture of the Amazon ECR container image.
author (string) --
The image author of the Amazon ECR container image.
imageHash (string) --
The image hash of the Amazon ECR container image.
imageTags (list) --
The image tags attached to the Amazon ECR container image.
(string) --
platform (string) --
The platform of the Amazon ECR container image.
pushedAt (datetime) --
The date and time the Amazon ECR container image was pushed.
lastInUseAt (datetime) --
The most recent date and time a cluster was running the image.
inUseCount (integer) --
The number of Amazon ECS or Amazon EKS clusters currently running the image.
registry (string) --
The registry the Amazon ECR container image belongs to.
repositoryName (string) --
The name of the repository the Amazon ECR container image resides in.
id (string) --
The ID of the resource.
tags (dict) --
The tags attached to the resource.
(string) --
(string) --
type (string) --
The type of resource.
score (float) --
The Amazon Inspector score given to the finding.
scoreDetails (dict) --
An object that contains details of the Amazon Inspector score.
cvss (dict) --
An object that contains details about the CVSS score given to a finding.
adjustments (list) --
An object that contains details about adjustment Amazon Inspector made to the CVSS score.
(dict) --
Details on adjustments Amazon Inspector made to the CVSS score for a finding.
metric (string) --
The metric used to adjust the CVSS score.
reason (string) --
The reason the CVSS score has been adjustment.
score (float) --
The CVSS score.
scoreSource (string) --
The source for the CVSS score.
scoringVector (string) --
The vector for the CVSS score.
version (string) --
The CVSS version used in scoring.
severity (string) --
The severity of the finding.
status (string) --
The status of the finding.
title (string) --
The title of the finding.
type (string) --
The type of the finding.
updatedAt (datetime) --
The date and time the finding was last updated at.
fixAvailable (string) --
Details on whether a fix is available through a version update. This value can be YES, NO, or PARTIAL. A PARTIAL fix means that some, but not all, of the packages identified in the finding have fixes available through updated versions.
exploitAvailable (string) --
If a finding discovered in your environment has an exploit available.
nextToken (string) --
The nextToken value to include in a future DescribeImageScanFindings request. When the results of a DescribeImageScanFindings request exceed maxResults, this value can be used to retrieve the next page of results. This value is null when there are no more results to return.
{'filter': {'imageStatus': 'ACTIVE | ARCHIVED | ACTIVATING | ANY'}}
Response {'imageDetails': {'imageScanStatus': {'status': {'IMAGE_ARCHIVED'}},
'imageStatus': 'ACTIVE | ARCHIVED | ACTIVATING',
'lastActivatedAt': 'timestamp',
'lastArchivedAt': 'timestamp',
'subjectManifestDigest': 'string'}}
Returns metadata about the images in a repository.
See also: AWS API Documentation
Request Syntax
client.describe_images(
registryId='string',
repositoryName='string',
imageIds=[
{
'imageDigest': 'string',
'imageTag': 'string'
},
],
nextToken='string',
maxResults=123,
filter={
'tagStatus': 'TAGGED'|'UNTAGGED'|'ANY',
'imageStatus': 'ACTIVE'|'ARCHIVED'|'ACTIVATING'|'ANY'
}
)
string
The Amazon Web Services account ID associated with the registry that contains the repository in which to describe images. If you do not specify a registry, the default registry is assumed.
string
[REQUIRED]
The repository that contains the images to describe.
list
The list of image IDs for the requested repository.
(dict) --
An object with identifying information for an image in an Amazon ECR repository.
imageDigest (string) --
The sha256 digest of the image manifest.
imageTag (string) --
The tag used for the image.
string
The nextToken value returned from a previous paginated DescribeImages request where maxResults was used and the results exceeded the value of that parameter. Pagination continues from the end of the previous results that returned the nextToken value. This value is null when there are no more results to return. This option cannot be used when you specify images with imageIds.
integer
The maximum number of repository results returned by DescribeImages in paginated output. When this parameter is used, DescribeImages only returns maxResults results in a single page along with a nextToken response element. The remaining results of the initial request can be seen by sending another DescribeImages request with the returned nextToken value. This value can be between 1 and 1000. If this parameter is not used, then DescribeImages returns up to 100 results and a nextToken value, if applicable. This option cannot be used when you specify images with imageIds.
dict
The filter key and value with which to filter your DescribeImages results.
tagStatus (string) --
The tag status with which to filter your DescribeImages results. You can filter results based on whether they are TAGGED or UNTAGGED.
imageStatus (string) --
The image status with which to filter your DescribeImages results. Valid values are ACTIVE, ARCHIVED, and ACTIVATING.
dict
Response Syntax
{
'imageDetails': [
{
'registryId': 'string',
'repositoryName': 'string',
'imageDigest': 'string',
'imageTags': [
'string',
],
'imageSizeInBytes': 123,
'imagePushedAt': datetime(2015, 1, 1),
'imageScanStatus': {
'status': 'IN_PROGRESS'|'COMPLETE'|'FAILED'|'UNSUPPORTED_IMAGE'|'ACTIVE'|'PENDING'|'SCAN_ELIGIBILITY_EXPIRED'|'FINDINGS_UNAVAILABLE'|'LIMIT_EXCEEDED'|'IMAGE_ARCHIVED',
'description': 'string'
},
'imageScanFindingsSummary': {
'imageScanCompletedAt': datetime(2015, 1, 1),
'vulnerabilitySourceUpdatedAt': datetime(2015, 1, 1),
'findingSeverityCounts': {
'string': 123
}
},
'imageManifestMediaType': 'string',
'artifactMediaType': 'string',
'lastRecordedPullTime': datetime(2015, 1, 1),
'subjectManifestDigest': 'string',
'imageStatus': 'ACTIVE'|'ARCHIVED'|'ACTIVATING',
'lastArchivedAt': datetime(2015, 1, 1),
'lastActivatedAt': datetime(2015, 1, 1)
},
],
'nextToken': 'string'
}
Response Structure
(dict) --
imageDetails (list) --
A list of ImageDetail objects that contain data about the image.
(dict) --
An object that describes an image returned by a DescribeImages operation.
registryId (string) --
The Amazon Web Services account ID associated with the registry to which this image belongs.
repositoryName (string) --
The name of the repository to which this image belongs.
imageDigest (string) --
The sha256 digest of the image manifest.
imageTags (list) --
The list of tags associated with this image.
(string) --
imageSizeInBytes (integer) --
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.
imagePushedAt (datetime) --
The date and time, expressed in standard JavaScript date format, at which the current image was pushed to the repository.
imageScanStatus (dict) --
The current state of the scan.
status (string) --
The current state of an image scan.
description (string) --
The description of the image scan status.
imageScanFindingsSummary (dict) --
A summary of the last completed image scan.
imageScanCompletedAt (datetime) --
The time of the last completed image scan.
vulnerabilitySourceUpdatedAt (datetime) --
The time when the vulnerability data was last scanned.
findingSeverityCounts (dict) --
The image vulnerability counts, sorted by severity.
(string) --
(integer) --
imageManifestMediaType (string) --
The media type of the image manifest.
artifactMediaType (string) --
The artifact media type of the image.
lastRecordedPullTime (datetime) --
The date and time, expressed in standard JavaScript date format, when Amazon ECR recorded the last image pull.
subjectManifestDigest (string) --
The digest of the subject manifest for images that are referrers.
imageStatus (string) --
The current status of the image.
lastArchivedAt (datetime) --
The date and time, expressed in standard JavaScript date format, when the image was last transitioned to Amazon ECR archive.
lastActivatedAt (datetime) --
The date and time, expressed in standard JavaScript date format, when the image was last restored from Amazon ECR archive to Amazon ECR standard.
nextToken (string) --
The nextToken value to include in a future DescribeImages request. When the results of a DescribeImages request exceed maxResults, this value can be used to retrieve the next page of results. This value is null when there are no more results to return.
{'previewResults': {'action': {'targetStorageClass': 'ARCHIVE',
'type': {'TRANSITION'}},
'storageClass': 'ARCHIVE | STANDARD'},
'summary': {'transitioningImageTotalCounts': [{'imageTotalCount': 'integer',
'targetStorageClass': 'ARCHIVE'}]}}
Retrieves the results of the lifecycle policy preview request for the specified repository.
See also: AWS API Documentation
Request Syntax
client.get_lifecycle_policy_preview(
registryId='string',
repositoryName='string',
imageIds=[
{
'imageDigest': 'string',
'imageTag': 'string'
},
],
nextToken='string',
maxResults=123,
filter={
'tagStatus': 'TAGGED'|'UNTAGGED'|'ANY'
}
)
string
The Amazon Web Services account ID associated with the registry that contains the repository. If you do not specify a registry, the default registry is assumed.
string
[REQUIRED]
The name of the repository.
list
The list of imageIDs to be included.
(dict) --
An object with identifying information for an image in an Amazon ECR repository.
imageDigest (string) --
The sha256 digest of the image manifest.
imageTag (string) --
The tag used for the image.
string
The nextToken value returned from a previous paginated
GetLifecyclePolicyPreviewRequest request where maxResults was used and the results exceeded the value of that parameter. Pagination continues from the end of the previous results that returned the nextToken value. This value is null when there are no more results to return. This option cannot be used when you specify images with imageIds.
integer
The maximum number of repository results returned by GetLifecyclePolicyPreviewRequest in paginated output. When this parameter is used, GetLifecyclePolicyPreviewRequest only returns
maxResults results in a single page along with a nextToken response element. The remaining results of the initial request can be seen by sending another GetLifecyclePolicyPreviewRequest request with the returned nextToken value. This value can be between 1 and 100. If this parameter is not used, then GetLifecyclePolicyPreviewRequest returns up to 100 results and a nextToken value, if applicable. This option cannot be used when you specify images with imageIds.
dict
An optional parameter that filters results based on image tag status and all tags, if tagged.
tagStatus (string) --
The tag status of the image.
dict
Response Syntax
{
'registryId': 'string',
'repositoryName': 'string',
'lifecyclePolicyText': 'string',
'status': 'IN_PROGRESS'|'COMPLETE'|'EXPIRED'|'FAILED',
'nextToken': 'string',
'previewResults': [
{
'imageTags': [
'string',
],
'imageDigest': 'string',
'imagePushedAt': datetime(2015, 1, 1),
'action': {
'type': 'EXPIRE'|'TRANSITION',
'targetStorageClass': 'ARCHIVE'
},
'appliedRulePriority': 123,
'storageClass': 'ARCHIVE'|'STANDARD'
},
],
'summary': {
'expiringImageTotalCount': 123,
'transitioningImageTotalCounts': [
{
'targetStorageClass': 'ARCHIVE',
'imageTotalCount': 123
},
]
}
}
Response Structure
(dict) --
registryId (string) --
The registry ID associated with the request.
repositoryName (string) --
The repository name associated with the request.
lifecyclePolicyText (string) --
The JSON lifecycle policy text.
status (string) --
The status of the lifecycle policy preview request.
nextToken (string) --
The nextToken value to include in a future GetLifecyclePolicyPreview request. When the results of a GetLifecyclePolicyPreview request exceed maxResults, this value can be used to retrieve the next page of results. This value is null when there are no more results to return.
previewResults (list) --
The results of the lifecycle policy preview request.
(dict) --
The result of the lifecycle policy preview.
imageTags (list) --
The list of tags associated with this image.
(string) --
imageDigest (string) --
The sha256 digest of the image manifest.
imagePushedAt (datetime) --
The date and time, expressed in standard JavaScript date format, at which the current image was pushed to the repository.
action (dict) --
The type of action to be taken.
type (string) --
The type of action to be taken.
targetStorageClass (string) --
The target storage class for the action. This is only present when the type is TRANSITION.
appliedRulePriority (integer) --
The priority of the applied rule.
storageClass (string) --
The storage class of the image.
summary (dict) --
The list of images that is returned as a result of the action.
expiringImageTotalCount (integer) --
The number of expiring images.
transitioningImageTotalCounts (list) --
The total count of images that will be transitioned to each storage class. This field is only present if at least one image will be transitoned in the summary.
(dict) --
The total count of images transitioning to a storage class.
targetStorageClass (string) --
The target storage class.
imageTotalCount (integer) --
The total number of images transitioning to the storage class.
{'filter': {'imageStatus': 'ACTIVE | ARCHIVED | ACTIVATING | ANY'}}
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.
See also: AWS API Documentation
Request Syntax
client.list_images(
registryId='string',
repositoryName='string',
nextToken='string',
maxResults=123,
filter={
'tagStatus': 'TAGGED'|'UNTAGGED'|'ANY',
'imageStatus': 'ACTIVE'|'ARCHIVED'|'ACTIVATING'|'ANY'
}
)
string
The Amazon Web Services account ID associated with the registry that contains the repository in which to list images. If you do not specify a registry, the default registry is assumed.
string
[REQUIRED]
The repository with image IDs to be listed.
string
The nextToken value returned from a previous paginated ListImages request where maxResults was used and the results exceeded the value of that parameter. Pagination continues from the end of the previous results that returned the nextToken value. This value is null when there are no more results to return.
integer
The maximum number of image results returned by ListImages in paginated output. When this parameter is used, ListImages only returns maxResults results in a single page along with a nextToken response element. The remaining results of the initial request can be seen by sending another ListImages request with the returned nextToken value. This value can be between 1 and 1000. If this parameter is not used, then ListImages returns up to 100 results and a nextToken value, if applicable.
dict
The filter key and value with which to filter your ListImages results.
tagStatus (string) --
The tag status with which to filter your ListImages results.
imageStatus (string) --
The image status with which to filter your ListImages results. Valid values are ACTIVE, ARCHIVED, and ACTIVATING.
dict
Response Syntax
{
'imageIds': [
{
'imageDigest': 'string',
'imageTag': 'string'
},
],
'nextToken': 'string'
}
Response Structure
(dict) --
imageIds (list) --
The list of image IDs for the requested repository.
(dict) --
An object with identifying information for an image in an Amazon ECR repository.
imageDigest (string) --
The sha256 digest of the image manifest.
imageTag (string) --
The tag used for the image.
nextToken (string) --
The nextToken value to include in a future ListImages request. When the results of a ListImages request exceed maxResults, this value can be used to retrieve the next page of results. This value is null when there are no more results to return.
{'imageScanStatus': {'status': {'IMAGE_ARCHIVED'}}}
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.
See also: AWS API Documentation
Request Syntax
client.start_image_scan(
registryId='string',
repositoryName='string',
imageId={
'imageDigest': 'string',
'imageTag': 'string'
}
)
string
The Amazon Web Services account ID associated with the registry that contains the repository in which to start an image scan request. If you do not specify a registry, the default registry is assumed.
string
[REQUIRED]
The name of the repository that contains the images to scan.
dict
[REQUIRED]
An object with identifying information for an image in an Amazon ECR repository.
imageDigest (string) --
The sha256 digest of the image manifest.
imageTag (string) --
The tag used for the image.
dict
Response Syntax
{
'registryId': 'string',
'repositoryName': 'string',
'imageId': {
'imageDigest': 'string',
'imageTag': 'string'
},
'imageScanStatus': {
'status': 'IN_PROGRESS'|'COMPLETE'|'FAILED'|'UNSUPPORTED_IMAGE'|'ACTIVE'|'PENDING'|'SCAN_ELIGIBILITY_EXPIRED'|'FINDINGS_UNAVAILABLE'|'LIMIT_EXCEEDED'|'IMAGE_ARCHIVED',
'description': 'string'
}
}
Response Structure
(dict) --
registryId (string) --
The registry ID associated with the request.
repositoryName (string) --
The repository name associated with the request.
imageId (dict) --
An object with identifying information for an image in an Amazon ECR repository.
imageDigest (string) --
The sha256 digest of the image manifest.
imageTag (string) --
The tag used for the image.
imageScanStatus (dict) --
The current state of the scan.
status (string) --
The current state of an image scan.
description (string) --
The description of the image scan status.