View a markdown version of this page

Amazon ECR examples using AWS CLI - AWS SDK Code Examples
Actions

There are more AWS SDK examples available in the AWS Doc SDK Examples GitHub repo.

Amazon ECR examples using AWS CLI

The following code examples show you how to perform actions and implement common scenarios by using the AWS Command Line Interface with Amazon ECR.

Actions are code excerpts from larger programs and must be run in context. While actions show you how to call individual service functions, you can see actions in context in their related scenarios.

Each example includes a link to the complete source code, where you can find instructions on how to set up and run the code in context.

Topics

Actions

The following code example shows how to use batch-check-layer-availability.

AWS CLI

To check the availability of a layer

The following batch-check-layer-availability example checks the availability of a layer with the digest sha256:6171c7451a50945f8ddd72f7732cc04d7a0d1f48138a426b2e64387fdeb834ed in the cluster-autoscaler repository.

aws ecr batch-check-layer-availability \
    --repository-name cluster-autoscaler \
    --layer-digests sha256:6171c7451a50945f8ddd72f7732cc04d7a0d1f48138a426b2e64387fdeb834ed

Output:

{
    "layers": [
        {
            "layerDigest": "sha256:6171c7451a50945f8ddd72f7732cc04d7a0d1f48138a426b2e64387fdeb834ed",
            "layerAvailability": "AVAILABLE",
            "layerSize": 2777,
            "mediaType": "application/vnd.docker.container.image.v1+json"
        }
    ],
    "failures": []
}

The following code example shows how to use batch-delete-image.

AWS CLI

Example 1: To delete an image

The following batch-delete-image example deletes an image with the tag precise in the specified repository in the default registry for an account.

aws ecr batch-delete-image \
    --repository-name ubuntu \
    --image-ids imageTag=precise

Output:

{
    "failures": [],
    "imageIds": [
        {
            "imageTag": "precise",
            "imageDigest": "sha256:19665f1e6d1e504117a1743c0a3d3753086354a38375961f2e665416ef4b1b2f"
        }
    ]
}

Example 2: To delete multiple images

The following batch-delete-image example deletes all images tagged with prod and team1 in the specified repository.

aws ecr batch-delete-image \
    --repository-name MyRepository \
    --image-ids imageTag=prod imageTag=team1

Output:

{
    "imageIds": [
        {
            "imageDigest": "sha256:123456789012",
            "imageTag": "prod"
        },
        {
            "imageDigest": "sha256:567890121234",
            "imageTag": "team1"
        }
    ],
    "failures": []
}

For more information, see Deleting an Image in the Amazon ECR User Guide.

The following code example shows how to use batch-get-image.

AWS CLI

Example 1: To get an image

The following batch-get-image example gets an image with the tag v1.13.6 in a repository called cluster-autoscaler in the default registry for an account.

aws ecr batch-get-image \
    --repository-name cluster-autoscaler \
    --image-ids imageTag=v1.13.6

Output:

{
    "images": [
        {
            "registryId": "012345678910",
            "repositoryName": "cluster-autoscaler",
            "imageId": {
                "imageDigest": "sha256:4a1c6567c38904384ebc64e35b7eeddd8451110c299e3368d2210066487d97e5",
                "imageTag": "v1.13.6"
            },
            "imageManifest": "{\n   \"schemaVersion\": 2,\n   \"mediaType\": \"application/vnd.docker.distribution.manifest.v2+json\",\n   \"config\": {\n      \"mediaType\": \"application/vnd.docker.container.image.v1+json\",\n      \"size\": 2777,\n      \"digest\": \"sha256:6171c7451a50945f8ddd72f7732cc04d7a0d1f48138a426b2e64387fdeb834ed\"\n   },\n   \"layers\": [\n      {\n         \"mediaType\": \"application/vnd.docker.image.rootfs.diff.tar.gzip\",\n         \"size\": 17743696,\n         \"digest\": \"sha256:39fafc05754f195f134ca11ecdb1c9a691ab0848c697fffeb5a85f900caaf6e1\"\n      },\n      {\n         \"mediaType\": \"application/vnd.docker.image.rootfs.diff.tar.gzip\",\n         \"size\": 2565026,\n         \"digest\": \"sha256:8c8a779d3a537b767ae1091fe6e00c2590afd16767aa6096d1b318d75494819f\"\n      },\n      {\n         \"mediaType\": \"application/vnd.docker.image.rootfs.diff.tar.gzip\",\n         \"size\": 28005981,\n         \"digest\": \"sha256:c44ba47496991c9982ee493b47fd25c252caabf2b4ae7dd679c9a27b6a3c8fb7\"\n      },\n      {\n         \"mediaType\": \"application/vnd.docker.image.rootfs.diff.tar.gzip\",\n         \"size\": 775,\n         \"digest\": \"sha256:e2c388b44226544363ca007be7b896bcce1baebea04da23cbd165eac30be650f\"\n      }\n   ]\n}"
        }
    ],
    "failures": []
}

Example 2: To get multiple images

The following batch-get-image example displays details of all images tagged with prod and team1 in the specified repository.

aws ecr batch-get-image \
    --repository-name MyRepository \
    --image-ids imageTag=prod imageTag=team1

Output:

{
    "images": [
        {
            "registryId": "123456789012",
            "repositoryName": "MyRepository",
            "imageId": {
                "imageDigest": "sha256:123456789012",
                "imageTag": "prod"
            },
            "imageManifest": "manifestExample1"
        },
        {
            "registryId": "567890121234",
            "repositoryName": "MyRepository",
            "imageId": {
                "imageDigest": "sha256:123456789012",
                "imageTag": "team1"
            },
            "imageManifest": "manifestExample2"
        }
    ],
    "failures": []
}

For more information, see Images in the Amazon ECR User Guide.

  • For API details, see BatchGetImage in AWS CLI Command Reference.

The following code example shows how to use complete-layer-upload.

AWS CLI

To complete an image layer upload

The following complete-layer-upload example completes an image layer upload to the layer-test repository.

aws ecr complete-layer-upload \
    --repository-name layer-test \
    --upload-id 6cb64b8a-9378-0e33-2ab1-b780fab8a9e9 \
    --layer-digests 6cb64b8a-9378-0e33-2ab1-b780fab8a9e9:48074e6d3a68b39aad8ccc002cdad912d4148c0f92b3729323e

Output:

{
    "uploadId": "6cb64b8a-9378-0e33-2ab1-b780fab8a9e9",
    "layerDigest": "sha256:9a77f85878aa1906f2020a0ecdf7a7e962d57e882250acd773383224b3fe9a02",
    "repositoryName": "layer-test",
    "registryId": "130757420319"
}

The following code example shows how to use create-repository.

AWS CLI

Example 1: To create a repository

The following create-repository example creates a repository inside the specified namespace in the default registry for an account.

aws ecr create-repository \
    --repository-name project-a/sample-repo

Output:

{
    "repository": {
        "registryId": "123456789012",
        "repositoryName": "project-a/sample-repo",
        "repositoryArn": "arn:aws:ecr:us-west-2:123456789012:repository/project-a/sample-repo"
    }
}

For more information, see Creating a Repository in the Amazon ECR User Guide.

Example 2: To create a repository configured with image tag immutability

The following create-repository example creates a repository configured for tag immutability in the default registry for an account.

aws ecr create-repository \
    --repository-name project-a/sample-repo \
    --image-tag-mutability IMMUTABLE

Output:

{
    "repository": {
        "registryId": "123456789012",
        "repositoryName": "project-a/sample-repo",
        "repositoryArn": "arn:aws:ecr:us-west-2:123456789012:repository/project-a/sample-repo",
        "imageTagMutability": "IMMUTABLE"
    }
}

For more information, see Image Tag Mutability in the Amazon ECR User Guide.

Example 3: To create a repository configured with a scanning configuration

The following create-repository example creates a repository configured to perform a vulnerability scan on image push in the default registry for an account.

aws ecr create-repository \
    --repository-name project-a/sample-repo \
    --image-scanning-configuration scanOnPush=true

Output:

{
    "repository": {
        "registryId": "123456789012",
        "repositoryName": "project-a/sample-repo",
        "repositoryArn": "arn:aws:ecr:us-west-2:123456789012:repository/project-a/sample-repo",
        "imageScanningConfiguration": {
            "scanOnPush": true
        }
    }
}

For more information, see Image Scanning in the Amazon ECR User Guide.

The following code example shows how to use delete-lifecycle-policy.

AWS CLI

To delete the lifecycle policy for a repository

The following delete-lifecycle-policy example deletes the lifecycle policy for the hello-world repository.

aws ecr delete-lifecycle-policy \
    --repository-name hello-world

Output:

{
    "registryId": "012345678910",
    "repositoryName": "hello-world",
    "lifecyclePolicyText": "{\"rules\":[{\"rulePriority\":1,\"description\":\"Remove untagged images.\",\"selection\":{\"tagStatus\":\"untagged\",\"countType\":\"sinceImagePushed\",\"countUnit\":\"days\",\"countNumber\":10},\"action\":{\"type\":\"expire\"}}]}",
    "lastEvaluatedAt": 0.0
}

The following code example shows how to use delete-repository-policy.

AWS CLI

To delete the repository policy for a repository

The following delete-repository-policy example deletes the repository policy for the cluster-autoscaler repository.

aws ecr delete-repository-policy \
    --repository-name cluster-autoscaler

Output:

{
    "registryId": "012345678910",
    "repositoryName": "cluster-autoscaler",
    "policyText": "{\n  \"Version\" : \"2008-10-17\",\n  \"Statement\" : [ {\n    \"Sid\" : \"allow public pull\",\n    \"Effect\" : \"Allow\",\n    \"Principal\" : \"*\",\n    \"Action\" : [ \"ecr:BatchCheckLayerAvailability\", \"ecr:BatchGetImage\", \"ecr:GetDownloadUrlForLayer\" ]\n  } ]\n}"
}

The following code example shows how to use delete-repository.

AWS CLI

To delete a repository

The following delete-repository example command force deletes the specified repository in the default registry for an account. The --force flag is required if the repository contains images.

aws ecr delete-repository \
    --repository-name ubuntu \
    --force

Output:

{
    "repository": {
        "registryId": "123456789012",
        "repositoryName": "ubuntu",
        "repositoryArn": "arn:aws:ecr:us-west-2:123456789012:repository/ubuntu"
    }
}

For more information, see Deleting a Repository in the Amazon ECR User Guide.

The following code example shows how to use describe-image-scan-findings.

AWS CLI

To describe the scan findings for an image

The following describe-image-scan-findings example returns the image scan findings for an image using the image digest in the specified repository in the default registry for an account.

aws ecr describe-image-scan-findings \
    --repository-name sample-repo \
    --image-id imageDigest=sha256:74b2c688c700ec95a93e478cdb959737c148df3fbf5ea706abe0318726e885e6

Output:

{
    "imageScanFindings": {
      "findings": [
          {
              "name": "CVE-2019-5188",
              "description": "A code execution vulnerability exists in the directory rehashing functionality of E2fsprogs e2fsck 1.45.4. A specially crafted ext4 directory can cause an out-of-bounds write on the stack, resulting in code execution. An attacker can corrupt a partition to trigger this vulnerability.",
              "uri": "http://people.ubuntu.com/~ubuntu-security/cve/CVE-2019-5188",
              "severity": "MEDIUM",
              "attributes": [
                  {
                      "key": "package_version",
                      "value": "1.44.1-1ubuntu1.1"
                  },
                  {
                      "key": "package_name",
                      "value": "e2fsprogs"
                  },
                  {
                      "key": "CVSS2_VECTOR",
                      "value": "AV:L/AC:L/Au:N/C:P/I:P/A:P"
                  },
                  {
                      "key": "CVSS2_SCORE",
                      "value": "4.6"
                  }
              ]
          }
      ],
      "imageScanCompletedAt": 1579839105.0,
      "vulnerabilitySourceUpdatedAt": 1579811117.0,
      "findingSeverityCounts": {
          "MEDIUM": 1
      }
  },
  "registryId": "123456789012",
  "repositoryName": "sample-repo",
  "imageId": {
      "imageDigest": "sha256:74b2c688c700ec95a93e478cdb959737c148df3fbf5ea706abe0318726e885e6"
  },
  "imageScanStatus": {
      "status": "COMPLETE",
      "description": "The scan was completed successfully."
  }
}

For more information, see Image Scanning in the Amazon ECR User Guide.

The following code example shows how to use describe-images.

AWS CLI

To describe an image in a repository

The following describe-images example displays details about an image in the cluster-autoscaler repository with the tag v1.13.6.

aws ecr describe-images \
    --repository-name cluster-autoscaler \
    --image-ids imageTag=v1.13.6

Output:

{
    "imageDetails": [
        {
            "registryId": "012345678910",
            "repositoryName": "cluster-autoscaler",
            "imageDigest": "sha256:4a1c6567c38904384ebc64e35b7eeddd8451110c299e3368d2210066487d97e5",
            "imageTags": [
                "v1.13.6"
            ],
            "imageSizeInBytes": 48318255,
            "imagePushedAt": 1565128275.0
        }
    ]
}

The following code example shows how to use describe-repositories.

AWS CLI

To describe the repositories in a registry

This example describes the repositories in the default registry for an account.

Command:

aws ecr describe-repositories

Output:

{
    "repositories": [
        {
            "registryId": "012345678910",
            "repositoryName": "ubuntu",
            "repositoryArn": "arn:aws:ecr:us-west-2:012345678910:repository/ubuntu"
        },
        {
            "registryId": "012345678910",
            "repositoryName": "test",
            "repositoryArn": "arn:aws:ecr:us-west-2:012345678910:repository/test"
        }
    ]
}

The following code example shows how to use get-authorization-token.

AWS CLI

To get an authorization token for your default registry

The following get-authorization-token example command gets an authorization token for your default registry.

aws ecr get-authorization-token

Output:

{
    "authorizationData": [
        {
            "authorizationToken": "QVdTOkN...",
            "expiresAt": 1448875853.241,
            "proxyEndpoint": "https://123456789012.dkr.ecr.us-west-2.amazonaws.com"
        }
    ]
}

The following code example shows how to use get-download-url-for-layer.

AWS CLI

To get the download URL of a layer

The following get-download-url-for-layer example displays the download URL of a layer with the digest sha256:6171c7451a50945f8ddd72f7732cc04d7a0d1f48138a426b2e64387fdeb834ed in the cluster-autoscaler repository.

aws ecr get-download-url-for-layer \
    --repository-name cluster-autoscaler  \
    --layer-digest sha256:6171c7451a50945f8ddd72f7732cc04d7a0d1f48138a426b2e64387fdeb834ed

Output:

{
    "downloadUrl": "https://prod-us-west-2-starport-layer-bucket.s3.us-west-2.amazonaws.com/e501-012345678910-9cb60dc0-7284-5643-3987-da6dac0465f0/04620aac-66a5-4167-8232-55ee7ef6d565?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20190814T220617Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3600&X-Amz-Credential=AKIA32P3D2JDNMVAJLGF%2F20190814%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Signature=9161345894947a1672467a0da7a1550f2f7157318312fe4941b59976239c3337",
    "layerDigest": "sha256:6171c7451a50945f8ddd72f7732cc04d7a0d1f48138a426b2e64387fdeb834ed"
}

The following code example shows how to use get-lifecycle-policy-preview.

AWS CLI

To retrieve details for a lifecycle policy preview

The following get-lifecycle-policy-preview example retrieves the result of a lifecycle policy preview for the specified repository in the default registry for an account.

Command:

aws ecr get-lifecycle-policy-preview \
    --repository-name "project-a/amazon-ecs-sample"

Output:

{
    "registryId": "012345678910",
    "repositoryName": "project-a/amazon-ecs-sample",
    "lifecyclePolicyText": "{\n    \"rules\": [\n        {\n            \"rulePriority\": 1,\n            \"description\": \"Expire images older than 14 days\",\n            \"selection\": {\n                \"tagStatus\": \"untagged\",\n                \"countType\": \"sinceImagePushed\",\n                \"countUnit\": \"days\",\n                \"countNumber\": 14\n            },\n            \"action\": {\n                \"type\": \"expire\"\n            }\n        }\n    ]\n}\n",
    "status": "COMPLETE",
    "previewResults": [],
    "summary": {
        "expiringImageTotalCount": 0
    }
}

For more information, see Lifecycle Policies in the Amazon ECR User Guide.

The following code example shows how to use get-lifecycle-policy.

AWS CLI

To retrieve a lifecycle policy

The following get-lifecycle-policy example displays details of the lifecycle policy for the specified repository in the default registry for the account.

aws ecr get-lifecycle-policy \
    --repository-name "project-a/amazon-ecs-sample"

Output:

{
     "registryId": "123456789012",
     "repositoryName": "project-a/amazon-ecs-sample",
     "lifecyclePolicyText": "{\"rules\":[{\"rulePriority\":1,\"description\":\"Expire images older than 14 days\",\"selection\":{\"tagStatus\":\"untagged\",\"countType\":\"sinceImagePushed\",\"countUnit\":\"days\",\"countNumber\":14},\"action\":{\"type\":\"expire\"}}]}",
     "lastEvaluatedAt": 1504295007.0
}

For more information, see Lifecycle Policies in the Amazon ECR User Guide.

The following code example shows how to use get-login-password.

AWS CLI

To retrieve a password to authenticate to a registry

The following get-login-password displays a password that you can use with a container client of your choice to authenticate to any Amazon ECR registry that your IAM principal has access to.

aws ecr get-login-password

Output:

<password>

To use with the Docker CLI, pipe the output of the get-login-password command to the docker login command. When retrieving the password, ensure that you specify the same Region that your Amazon ECR registry exists in.

aws ecr get-login-password \
    --region <region> \
| docker login \
    --username