Container image pull behavior - Amazon Elastic Container Service

Container image pull behavior

Container image pull behavior for Fargate launch types

Fargate does not cache images, and therefore the whole image is pulled from the registry when a task runs. The following are our recommendations for images used for Fargate tasks:

  • Use a larger task size with additional vCPUs. The larger task size can help reduce the time that is required to extract the image when a task launches.

  • Use a smaller base image.

  • Have the repository that stores the image in the same Region as the task.

Container image pull behavior for Fargate Windows launch types

Fargate Windows caches the most recent month's, and the previous month's, servercore base image provided by Microsoft. These images match the KB/Build number patches updated each Patch Tuesday. For example, on 8/8/2023 Microsoft released KB5029247 (17763.4737) for Windows Server 2019. The previous month KB on 7/11/2023 was KB5028168 (17763.4645). So for the platforms WINDOWS_SERVER_2019_CORE and WINDOWS_SERVER_2019_FULL the following container images were cached:

  • mcr.microsoft.com/windows/servercore:ltsc2019

  • mcr.microsoft.com/windows/servercore:10.0.17763.4737

  • mcr.microsoft.com/windows/servercore:10.0.17763.4645

Additionally, on 8/8/2023 Microsoft released KB5029250 (20348.1906) for Windows Server 2022. The previous months KB on 7/11/2023 was KB5028171 (20348.1850). So for the platforms WINDOWS_SERVER_2022_CORE and WINDOWS_SERVER_2022_FULL the following container images were cached:

  • mcr.microsoft.com/windows/servercore:ltsc2022

  • mcr.microsoft.com/windows/servercore:10.0.20348.1906

  • mcr.microsoft.com/windows/servercore:10.0.20348.1850

Container image pull behavior for Amazon EC2 launch types

When the Amazon ECS agent starts a task, it pulls the Docker image from its remote registry, and then caches a local copy. When you use a new image tag for each release of your application, this behavior is unnecessary.


                    Diagram showing the container image pull behavior.

The ECS_IMAGE_PULL_BEHAVIOR agent parameter determines the image pull behavior and has the following values:

  • ECS_IMAGE_PULL_BEHAVIOR: default

    The image will be pulled remotely. If the pull fails, the cached image in the instance will be used.

  • ECS_IMAGE_PULL_BEHAVIOR: always

    The image will be pulled remotely. If the pull fails, the task fails.

To speed up deployment, set the Amazon ECS agent parameter to one of the following values:

  • ECS_IMAGE_PULL_BEHAVIOR: once

    The image is pulled remotely only if it wasn't pulled by a previous task on the same container instance or if the cached image was removed by the automated image cleanup process. Otherwise, the cached image on the instance is used. This ensures that no unnecessary image pulls are attempted.

  • ECS_IMAGE_PULL_BEHAVIOR: prefer-cached

    The image is pulled remotely if there is no cached image. Otherwise, the cached image on the instance is used. Automated image cleanup is disabled for the container to ensure that the cached image isn't removed.

Setting the parameter to either of the preceding values can save time because the Amazon ECS agent uses the existing downloaded image. For larger Docker images, the download time might take 10-20 seconds to pull over the network.