Module container_image 

Image pulls for the runtimes that launch containers: ECS (and Batch through it) and Lambda PackageType=Image functions pull on every launch with pull_image; EC2 instances and CodeBuild builds, whose images stand in for an AMI or a curated build image, pull only when the image is missing with ensure_image.

A bare docker pull always contacts the registry, even when the image is already in the local cache, so a momentary registry failure fails the launch. The common one is rate limiting: anonymous pulls from public.ecr.aws are capped per source IP, and a burst of task launches – or several processes sharing one NAT address – gets 429 Too Many Requests back.

A transient failure (throttling, a registry 5xx, a network timeout) is retried with backoff, and falls back to the image already cached locally instead of failing the launch. A refusal is final: an image that no longer exists or a pull the registry denies fails at once with the registry’s own error, even when a stale copy is cached. Otherwise an image deleted from ECR, or one a repository policy denies, would keep launching from the local copy – which neither Fargate nor Lambda, having no per-host image cache, ever does.

Enums

PulledImage

How an image became available for a launch.

Functions

ensure_image

Make reference available locally, pulling it only when it is not already cached – what docker run does with its implicit pull, but with pull_image’s retry when the registry fails transiently. docker run gives up on the first 429 Too Many Requests, which on a host with an empty cache fails every launch that races the first pull of an image.

pull_image

Pull reference with the container cli. A transient registry failure falls back to a locally cached copy, or is retried with backoff when nothing is cached; any other failure is returned at once. docker_config is exported as DOCKER_CONFIG for the pull so registry credentials resolve.