Table of Contents
ECR.Client¶A low-level client representing Amazon EC2 Container Registry (ECR):
client = session.create_client('ecr')
These are the available methods:
batch_check_layer_availability()batch_delete_image()batch_get_image()can_paginate()complete_layer_upload()create_repository()delete_repository()delete_repository_policy()describe_images()describe_repositories()generate_presigned_url()get_authorization_token()get_download_url_for_layer()get_paginator()get_repository_policy()get_waiter()initiate_layer_upload()list_images()put_image()set_repository_policy()upload_layer_part()batch_check_layer_availability(**kwargs)¶Check the availability of multiple image layers in a specified registry and repository.
Note
This operation is used by the Amazon ECR proxy, and it is not intended for general use by customers for pulling and pushing images. In most cases, you should use the docker CLI to pull, tag, and push images.
See also: AWS API Documentation
Request Syntax
response = client.batch_check_layer_availability(
registryId='string',
repositoryName='string',
layerDigests=[
'string',
]
)
| Parameters: |
|
|---|---|
| Return type: | dict |
| Returns: | Response Syntax {
'layers': [
{
'layerDigest': 'string',
'layerAvailability': 'AVAILABLE'|'UNAVAILABLE',
'layerSize': 123,
'mediaType': 'string'
},
],
'failures': [
{
'layerDigest': 'string',
'failureCode': 'InvalidLayerDigest'|'MissingLayerDigest',
'failureReason': 'string'
},
]
}
Response Structure
|
batch_delete_image(**kwargs)¶Deletes a list of specified images within a specified repository. Images are specified with either 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
response = client.batch_delete_image(
registryId='string',
repositoryName='string',
imageIds=[
{
'imageDigest': 'string',
'imageTag': 'string'
},
]
)
| Parameters: |
|
|---|---|
| Return type: | dict |
| Returns: | Response Syntax {
'imageIds': [
{
'imageDigest': 'string',
'imageTag': 'string'
},
],
'failures': [
{
'imageId': {
'imageDigest': 'string',
'imageTag': 'string'
},
'failureCode': 'InvalidImageDigest'|'InvalidImageTag'|'ImageTagDoesNotMatchDigest'|'ImageNotFound'|'MissingDigestAndTag',
'failureReason': 'string'
},
]
}
Response Structure
|
Examples
This example deletes images with the tags precise and trusty in a repository called ubuntu in the default registry for an account.
response = client.batch_delete_image(
imageIds=[
{
'imageTag': 'precise',
},
],
repositoryName='ubuntu',
)
print(response)
Expected Output:
{
'failures': [
],
'imageIds': [
{
'imageDigest': 'sha256:examplee6d1e504117a17000003d3753086354a38375961f2e665416ef4b1b2f',
'imageTag': 'precise',
},
],
'ResponseMetadata': {
'...': '...',
},
}
batch_get_image(**kwargs)¶Gets detailed information for specified images within a specified repository. Images are specified with either imageTag or imageDigest .
See also: AWS API Documentation
Request Syntax
response = client.batch_get_image(
registryId='string',
repositoryName='string',
imageIds=[
{
'imageDigest': 'string',
'imageTag': 'string'
},
],
acceptedMediaTypes=[
'string',
]
)
| Parameters: |
|
|---|---|
| Return type: | dict |
| Returns: | Response Syntax {
'images': [
{
'registryId': 'string',
'repositoryName': 'string',
'imageId': {
'imageDigest': 'string',
'imageTag': 'string'
},
'imageManifest': 'string'
},
],
'failures': [
{
'imageId': {
'imageDigest': 'string',
'imageTag': 'string'
},
'failureCode': 'InvalidImageDigest'|'InvalidImageTag'|'ImageTagDoesNotMatchDigest'|'ImageNotFound'|'MissingDigestAndTag',
'failureReason': 'string'
},
]
}
Response Structure
|
Examples
This example obtains information for an image with a specified image digest ID from the repository named ubuntu in the current account.
response = client.batch_get_image(
imageIds=[
{
'imageTag': 'precise',
},
],
repositoryName='ubuntu',
)
print(response)
Expected Output:
{
'failures': [
],
'images': [
{
'imageId': {
'imageDigest': 'sha256:example76bdff6d83a09ba2a818f0d00000063724a9ac3ba5019c56f74ebf42a',
'imageTag': 'precise',
},
'imageManifest': '{\n "schemaVersion": 1,\n "name": "ubuntu",\n "tag": "precise",\n...',
'registryId': '244698725403',
'repositoryName': 'ubuntu',
},
],
'ResponseMetadata': {
'...': '...',
},
}
can_paginate(operation_name)¶Check if an operation can be paginated.
| Parameters: | operation_name (string) – The operation name. This is the same name
as the method name on the client. For example, if the
method name is create_foo, and you’d normally invoke the
operation as client.create_foo(**kwargs), if the
create_foo operation can be paginated, you can use the
call client.get_paginator("create_foo"). |
|---|---|
| Returns: | True if the operation can be paginated,
False otherwise. |
complete_layer_upload(**kwargs)¶Inform Amazon ECR that the image layer upload for a specified registry, repository name, and upload ID, has completed. You can optionally provide a sha256 digest of the image layer for data validation purposes.
Note
This operation is used by the Amazon ECR proxy, and it is not intended for general use by customers for pulling and pushing images. In most cases, you should use the docker CLI to pull, tag, and push images.
See also: AWS API Documentation
Request Syntax
response = client.complete_layer_upload(
registryId='string',
repositoryName='string',
uploadId='string',
layerDigests=[
'string',
]
)
| Parameters: |
|
|---|---|
| Return type: | dict |
| Returns: | Response Syntax {
'registryId': 'string',
'repositoryName': 'string',
'uploadId': 'string',
'layerDigest': 'string'
}
Response Structure
|
create_repository(**kwargs)¶Creates an image repository.
See also: AWS API Documentation
Request Syntax
response = client.create_repository(
repositoryName='string'
)
| Parameters: | repositoryName (string) – [REQUIRED] The name to use for the repository. The repository name may be specified on its own (such as |
|---|---|
| Return type: | dict |
| Returns: | Response Syntax{
'repository': {
'repositoryArn': 'string',
'registryId': 'string',
'repositoryName': 'string',
'repositoryUri': 'string',
'createdAt': datetime(2015, 1, 1)
}
}
Response Structure
|
Examples
This example creates a repository called nginx-web-app inside the project-a namespace in the default registry for an account.
response = client.create_repository(
repositoryName='project-a/nginx-web-app',
)
print(response)
Expected Output:
{
'repository': {
'registryId': '012345678901',
'repositoryArn': 'arn:aws:ecr:us-west-2:012345678901:repository/project-a/nginx-web-app',
'repositoryName': 'project-a/nginx-web-app',
},
'ResponseMetadata': {
'...': '...',
},
}
delete_repository(**kwargs)¶Deletes an existing image repository. If a repository contains images, you must use the force option to delete it.
See also: AWS API Documentation
Request Syntax
response = client.delete_repository(
registryId='string',
repositoryName='string',
force=True|False
)
| Parameters: |
|
|---|---|
| Return type: | dict |
| Returns: | Response Syntax {
'repository': {
'repositoryArn': 'string',
'registryId': 'string',
'repositoryName': 'string',
'repositoryUri': 'string',
'createdAt': datetime(2015, 1, 1)
}
}
Response Structure
|
Examples
This example force deletes a repository named ubuntu in the default registry for an account. The force parameter is required if the repository contains images.
response = client.delete_repository(
force=True,
repositoryName='ubuntu',
)
print(response)
Expected Output:
{
'repository': {
'registryId': '012345678901',
'repositoryArn': 'arn:aws:ecr:us-west-2:012345678901:repository/ubuntu',
'repositoryName': 'ubuntu',
},
'ResponseMetadata': {
'...': '...',
},
}
delete_repository_policy(**kwargs)¶Deletes the repository policy from a specified repository.
See also: AWS API Documentation
Request Syntax
response = client.delete_repository_policy(
registryId='string',
repositoryName='string'
)
| Parameters: |
|
|---|---|
| Return type: | dict |
| Returns: | Response Syntax {
'registryId': 'string',
'repositoryName': 'string',
'policyText': 'string'
}
Response Structure
|
Examples
This example deletes the policy associated with the repository named ubuntu in the current account.
response = client.delete_repository_policy(
repositoryName='ubuntu',
)
print(response)
Expected Output:
{
'policyText': '{ ... }',
'registryId': '012345678901',
'repositoryName': 'ubuntu',
'ResponseMetadata': {
'...': '...',
},
}
describe_images(**kwargs)¶Returns metadata about the images in a repository, including image size, image tags, and creation date.
Note
Beginning 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, so it may return a larger image size than the image sizes returned by DescribeImages .
See also: AWS API Documentation
Request Syntax
response = client.describe_images(
registryId='string',
repositoryName='string',
imageIds=[
{
'imageDigest': 'string',
'imageTag': 'string'
},
],
nextToken='string',
maxResults=123,
filter={
'tagStatus': 'TAGGED'|'UNTAGGED'
}
)
| Parameters: |
|
|---|---|
| Return type: | dict |
| Returns: | Response Syntax {
'imageDetails': [
{
'registryId': 'string',
'repositoryName': 'string',
'imageDigest': 'string',
'imageTags': [
'string',
],
'imageSizeInBytes': 123,
'imagePushedAt': datetime(2015, 1, 1)
},
],
'nextToken': 'string'
}
Response Structure
|
describe_repositories(**kwargs)¶Describes image repositories in a registry.
See also: AWS API Documentation
Request Syntax
response = client.describe_repositories(
registryId='string',
repositoryNames=[
'string',
],
nextToken='string',
maxResults=123
)
| Parameters: |
|
|---|---|
| Return type: | dict |
| Returns: | Response Syntax {
'repositories': [
{
'repositoryArn': 'string',
'registryId': 'string',
'repositoryName': 'string',
'repositoryUri': 'string',
'createdAt': datetime(2015, 1, 1)
},
],
'nextToken': 'string'
}
Response Structure
|
Examples
The following example obtains a list and description of all repositories in the default registry to which the current user has access.
response = client.describe_repositories(
)
print(response)
Expected Output:
{
'repositories': [
{
'registryId': '012345678910',
'repositoryArn': 'arn:aws:ecr:us-west-2:012345678910:repository/ubuntu',
'repositoryName': 'ubuntu',
},
{
'registryId': '012345678910',
'repositoryArn': 'arn:aws:ecr:us-west-2:012345678910:repository/test',
'repositoryName': 'test',
},
],
'ResponseMetadata': {
'...': '...',
},
}
generate_presigned_url(ClientMethod, Params=None, ExpiresIn=3600, HttpMethod=None)¶Generate a presigned url given a client, its method, and arguments
| Parameters: |
|
|---|---|
| Returns: | The presigned url |
Retrieves a token that is valid for a specified registry for 12 hours. This command allows you to use the docker CLI to push and pull images with Amazon ECR. If you do not specify a registry, the default registry is assumed.
The authorizationToken returned for each registry specified is a base64 encoded string that can be decoded and used in a docker login command to authenticate to a registry. The AWS CLI offers an aws ecr get-login command that simplifies the login process.
See also: AWS API Documentation
Request Syntax
response = client.get_authorization_token(
registryIds=[
'string',
]
)
| Parameters: | registryIds (list) – A list of AWS account IDs that are associated with the registries for which to get authorization tokens. If you do not specify a registry, the default registry is assumed.
|
|---|---|
| Return type: | dict |
| Returns: | Response Syntax{
'authorizationData': [
{
'authorizationToken': 'string',
'expiresAt': datetime(2015, 1, 1),
'proxyEndpoint': 'string'
},
]
}
Response Structure
|
Examples
This example gets an authorization token for your default registry.
response = client.get_authorization_token(
)
print(response)
Expected Output:
{
'authorizationData': [
{
'authorizationToken': 'QVdTOkN...',
'expiresAt': datetime(2016, 8, 11, 21, 44, 52, 3, 224, 0),
'proxyEndpoint': 'https://012345678901.dkr.ecr.us-west-2.amazonaws.com',
},
],
'ResponseMetadata': {
'...': '...',
},
}
get_download_url_for_layer(**kwargs)¶Retrieves the pre-signed Amazon S3 download URL corresponding to an image layer. You can only get URLs for image layers that are referenced in an image.
Note
This operation is used by the Amazon ECR proxy, and it is not intended for general use by customers for pulling and pushing images. In most cases, you should use the docker CLI to pull, tag, and push images.
See also: AWS API Documentation
Request Syntax
response = client.get_download_url_for_layer(
registryId='string',
repositoryName='string',
layerDigest='string'
)
| Parameters: |
|
|---|---|
| Return type: | dict |
| Returns: | Response Syntax {
'downloadUrl': 'string',
'layerDigest': 'string'
}
Response Structure
|
get_paginator(operation_name)¶Create a paginator for an operation.
| Parameters: | operation_name (string) – The operation name. This is the same name
as the method name on the client. For example, if the
method name is create_foo, and you’d normally invoke the
operation as client.create_foo(**kwargs), if the
create_foo operation can be paginated, you can use the
call client.get_paginator("create_foo"). |
|---|---|
| Raises: | OperationNotPageableError – Raised if the operation is not
pageable. You can use the client.can_paginate method to
check if an operation is pageable. |
| Return type: | L{botocore.paginate.Paginator} |
| Returns: | A paginator object. |
get_repository_policy(**kwargs)¶Retrieves the repository policy for a specified repository.
See also: AWS API Documentation
Request Syntax
response = client.get_repository_policy(
registryId='string',
repositoryName='string'
)
| Parameters: |
|
|---|---|
| Return type: | dict |
| Returns: | Response Syntax {
'registryId': 'string',
'repositoryName': 'string',
'policyText': 'string'
}
Response Structure
|
Examples
This example obtains the repository policy for the repository named ubuntu.
response = client.get_repository_policy(
repositoryName='ubuntu',
)
print(response)
Expected Output:
{
'policyText': '{\n "Version" : "2008-10-17",\n "Statement" : [ {\n "Sid" : "new statement",\n "Effect" : "Allow",\n "Principal" : {\n "AWS" : "arn:aws:iam::012345678901:role/CodeDeployDemo"\n },\n"Action" : [ "ecr:GetDownloadUrlForLayer", "ecr:BatchGetImage", "ecr:BatchCheckLayerAvailability" ]\n } ]\n}',
'registryId': '012345678901',
'repositoryName': 'ubuntu',
'ResponseMetadata': {
'...': '...',
},
}
get_waiter(waiter_name)¶initiate_layer_upload(**kwargs)¶Notify Amazon ECR that you intend to upload an image layer.
Note
This operation is used by the Amazon ECR proxy, and it is not intended for general use by customers for pulling and pushing images. In most cases, you should use the docker CLI to pull, tag, and push images.
See also: AWS API Documentation
Request Syntax
response = client.initiate_layer_upload(
registryId='string',
repositoryName='string'
)
| Parameters: |
|
|---|---|
| Return type: | dict |
| Returns: | Response Syntax {
'uploadId': 'string',
'partSize': 123
}
Response Structure
|
list_images(**kwargs)¶Lists all the image IDs for a given repository.
You can filter images based on whether or not they are tagged by setting the tagStatus parameter to TAGGED or UNTAGGED . 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
response = client.list_images(
registryId='string',
repositoryName='string',
nextToken='string',
maxResults=123,
filter={
'tagStatus': 'TAGGED'|'UNTAGGED'
}
)
| Parameters: |
|
|---|---|
| Return type: | dict |
| Returns: | Response Syntax {
'imageIds': [
{
'imageDigest': 'string',
'imageTag': 'string'
},
],
'nextToken': 'string'
}
Response Structure
|
Examples
This example lists all of the images in the repository named ubuntu in the default registry in the current account.
response = client.list_images(
repositoryName='ubuntu',
)
print(response)
Expected Output:
{
'imageIds': [
{
'imageDigest': 'sha256:764f63476bdff6d83a09ba2a818f0d35757063724a9ac3ba5019c56f74ebf42a',
'imageTag': 'precise',
},
],
'ResponseMetadata': {
'...': '...',
},
}
put_image(**kwargs)¶Creates or updates the image manifest and tags associated with an image.
Note
This operation is used by the Amazon ECR proxy, and it is not intended for general use by customers for pulling and pushing images. In most cases, you should use the docker CLI to pull, tag, and push images.
See also: AWS API Documentation
Request Syntax
response = client.put_image(
registryId='string',
repositoryName='string',
imageManifest='string',
imageTag='string'
)
| Parameters: |
|
|---|---|
| Return type: | dict |
| Returns: | Response Syntax {
'image': {
'registryId': 'string',
'repositoryName': 'string',
'imageId': {
'imageDigest': 'string',
'imageTag': 'string'
},
'imageManifest': 'string'
}
}
Response Structure
|
set_repository_policy(**kwargs)¶Applies a repository policy on a specified repository to control access permissions.
See also: AWS API Documentation
Request Syntax
response = client.set_repository_policy(
registryId='string',
repositoryName='string',
policyText='string',
force=True|False
)
| Parameters: |
|
|---|---|
| Return type: | dict |
| Returns: | Response Syntax {
'registryId': 'string',
'repositoryName': 'string',
'policyText': 'string'
}
Response Structure
|
upload_layer_part(**kwargs)¶Uploads an image layer part to Amazon ECR.
Note
This operation is used by the Amazon ECR proxy, and it is not intended for general use by customers for pulling and pushing images. In most cases, you should use the docker CLI to pull, tag, and push images.
See also: AWS API Documentation
Request Syntax
response = client.upload_layer_part(
registryId='string',
repositoryName='string',
uploadId='string',
partFirstByte=123,
partLastByte=123,
layerPartBlob=b'bytes'
)
| Parameters: |
|
|---|---|
| Return type: | dict |
| Returns: | Response Syntax {
'registryId': 'string',
'repositoryName': 'string',
'uploadId': 'string',
'lastByteReceived': 123
}
Response Structure
|
The available paginators are:
ECR.Paginator.DescribeImages¶paginator = client.get_paginator('describe_images')
paginate(**kwargs)¶Creates an iterator that will paginate through responses from ECR.Client.describe_images().
See also: AWS API Documentation
Request Syntax
response_iterator = paginator.paginate(
registryId='string',
repositoryName='string',
imageIds=[
{
'imageDigest': 'string',
'imageTag': 'string'
},
],
filter={
'tagStatus': 'TAGGED'|'UNTAGGED'
},
PaginationConfig={
'MaxItems': 123,
'PageSize': 123,
'StartingToken': 'string'
}
)
| Parameters: |
|
|---|---|
| Return type: | dict |
| Returns: | Response Syntax {
'imageDetails': [
{
'registryId': 'string',
'repositoryName': 'string',
'imageDigest': 'string',
'imageTags': [
'string',
],
'imageSizeInBytes': 123,
'imagePushedAt': datetime(2015, 1, 1)
},
],
'NextToken': 'string'
}
Response Structure
|
ECR.Paginator.DescribeRepositories¶paginator = client.get_paginator('describe_repositories')
paginate(**kwargs)¶Creates an iterator that will paginate through responses from ECR.Client.describe_repositories().
See also: AWS API Documentation
Request Syntax
response_iterator = paginator.paginate(
registryId='string',
repositoryNames=[
'string',
],
PaginationConfig={
'MaxItems': 123,
'PageSize': 123,
'StartingToken': 'string'
}
)
| Parameters: |
|
|---|---|
| Return type: | dict |
| Returns: | Response Syntax {
'repositories': [
{
'repositoryArn': 'string',
'registryId': 'string',
'repositoryName': 'string',
'repositoryUri': 'string',
'createdAt': datetime(2015, 1, 1)
},
],
'NextToken': 'string'
}
Response Structure
|
ECR.Paginator.ListImages¶paginator = client.get_paginator('list_images')
paginate(**kwargs)¶Creates an iterator that will paginate through responses from ECR.Client.list_images().
See also: AWS API Documentation
Request Syntax
response_iterator = paginator.paginate(
registryId='string',
repositoryName='string',
filter={
'tagStatus': 'TAGGED'|'UNTAGGED'
},
PaginationConfig={
'MaxItems': 123,
'PageSize': 123,
'StartingToken': 'string'
}
)
| Parameters: |
|
|---|---|
| Return type: | dict |
| Returns: | Response Syntax {
'imageIds': [
{
'imageDigest': 'string',
'imageTag': 'string'
},
],
'NextToken': 'string'
}
Response Structure
|