libera_utils.aws.ecr_upload#

Module for uploading docker images to the ECR

Functions

build_docker_image(context_dir, image_name)

Build a Docker image from a specified directory and tag it with a custom name.

ecr_upload_cli_handler(parsed_args)

CLI handler function for ecr-upload CLI subcommand.

push_image_to_ecr(image_name, image_tag, ...)

Push a Docker image to Amazon ECR with robust authentication handling.

Classes

DockerConfigManager([override_default_config])

Context manager object, suitable for use with docker-py DockerClient.login
class libera_utils.aws.ecr_upload.DockerConfigManager(override_default_config: bool = False)#

Context manager object, suitable for use with docker-py DockerClient.login

If override_default_config is True, dockercfg_path points to a temporary directory with a blank config. Otherwise, dockercfg_path is None, which allows DockerClient.login to use the default config location.

libera_utils.aws.ecr_upload._get_fresh_ecr_auth(region_name: str, *, boto_session: Session) → dict#

Get fresh ECR authentication configuration.

Parameters:

  • region_name (str) – AWS region name

  • boto_session (boto3.Session) – Boto3 session used to obtain the ECR authorization token (already role-assumed if needed)

Returns:

Authentication configuration for Docker API

Return type:

dict

libera_utils.aws.ecr_upload._process_push_logs(push_logs, full_ecr_tag: str) → str | None#

Consume a decoded Docker push stream, log a concise summary, and return the pushed image digest.

The raw Docker push stream is extremely chatty: it emits many per-layer "Pushing" progress events (byte counters and terminal progress bars) that are meaningless in a line-based log. This processor suppresses those, logs one readable line per layer transition at DEBUG, surfaces the terminal digest and a single summary at INFO, and raises on any error the stream reports.

Parameters:

  • push_logs (iterable of dict) – The decoded events yielded by docker_client.api.push(..., stream=True, decode=True).

  • full_ecr_tag (str) – Complete ECR tag (registry/repository:tag) being pushed, used for log context.

Returns:

The image digest (sha256:...) reported in the stream’s aux event, or None if not present.

Return type:

str or None

Raises:

ValueError – If the stream reports one or more errors (via the error or errorDetail fields).

libera_utils.aws.ecr_upload._push_single_tag(docker_client: DockerClient, local_image: Image, full_ecr_tag: str, region_name: str, max_retries: int = 3, boto_session: Session = None) → str | None#

Push a single tagged image to ECR with retry logic and fresh authentication.

Parameters:

  • docker_client (docker.DockerClient) – Docker client instance

  • local_image (docker.models.images.Image) – Local Docker image to push

  • full_ecr_tag (str) – Complete ECR tag (registry/repository:tag)

  • region_name (str) – AWS region name

  • max_retries (int) – Maximum retry attempts

  • boto_session (boto3.Session) – Boto3 session used to obtain ECR credentials (already role-assumed if needed)

Returns:

The image digest (sha256:...) reported for the pushed image, or None if not available.

Return type:

str or None

libera_utils.aws.ecr_upload.build_docker_image(context_dir: str | Path, image_name: str, tag: str = 'latest', target: str | None = None, platform: str = 'linux/amd64') → None#

Build a Docker image from a specified directory and tag it with a custom name.

Parameters:

  • context_dir (Union[str, Path]) – The path to the directory containing the Dockerfile and other build context.

  • image_name (str) – The name to give the Docker image.

  • tag (str, optional) – The tag to apply to the image (default is ‘latest’).

  • target (Optional[str]) – Name of the target to build.

  • platform (str) – Default “linux/amd64”.

Raises:

ValueError – If the specified directory does not exist or the build fails.

libera_utils.aws.ecr_upload.ecr_upload_cli_handler(parsed_args: Namespace) → None#

CLI handler function for ecr-upload CLI subcommand.

Parameters:

parsed_args (argparse.Namespace) – Namespace of parsed CLI arguments

Return type:

None

libera_utils.aws.ecr_upload.push_image_to_ecr(image_name: str, image_tag: str, processing_step_id: str | ProcessingStepIdentifier, *, ecr_image_tags: list[str] = None, region_name: str | None = None, ignore_docker_config: bool = False, max_retries: int = 1, boto_session: Session | None = None) → dict[str, str | None]#

Push a Docker image to Amazon ECR with robust authentication handling.

This function handles ECR authentication by obtaining fresh credentials for each push operation, preventing authentication token expiration issues during multi-tag pushes.

Parameters:

  • image_name (str) – Local name of the Docker image

  • image_tag (str) – Local tag of the Docker image (often ‘latest’)

  • processing_step_id (Union[str, ProcessingStepIdentifier]) – Processing step ID string or object used to determine ECR repository name. L0 processing step IDs are not supported as they have no associated ECR.

  • ecr_image_tags (Optional[List[str]], default None) – Tags to apply to the pushed image in ECR (e.g., [“1.3.4”, “latest”]). If None, defaults to [“latest”].

  • region_name (str, optional) – AWS region containing the target ECR registry. If None (the default), the region is taken from the session’s AWS configuration (profile / AWS_REGION), so it is not hard-coded.

  • ignore_docker_config (bool, default False) – If True, creates a temporary Docker config to prevent using stored credentials

  • max_retries (int, default 3) – Maximum number of retry attempts for failed push operations

  • boto_session (boto3.Session, optional) – Boto3 session used for ECR operations (already role-assumed if needed). If None, a default session is created (so callers that don’t need role assumption, e.g. libera_cdk integration tests, can omit it).

Raises:

  • ValueError – If processing_step_id cannot be mapped to an ECR repository name, or if push operations encounter errors after all retries

  • docker.errors.APIError – If Docker API operations fail

  • boto3.exceptions.ClientError – If AWS ECR operations fail

Returns:

Mapping of each pushed ECR tag to the image digest (sha256:...) reported for it, or None if the digest was not available in the push stream.

Return type:

dict[str, str | None]