libera_utils.aws.algorithm_registration#

Module for registering algorithm versions in the SDC.

Uploading an algorithm Docker image to the SDC ECR only makes the image available; it does not make it runnable by version. The SDC processing step function resolves a requested algorithm version by searching the AWS Batch job definitions for one whose container references the matching image. The SDC Registrar service (a Batch Job Definition Registrar Lambda) creates that versioned job definition in response to a NewAlgorithmImage EventBridge event: it clones the step’s default job definition and swaps in the uploaded image.

This module emits that event (see put_new_algorithm_image_event()) and, optionally, verifies that the Registrar produced the expected job definition (see verify_algorithm_registration()).

Functions

put_new_algorithm_image_event(...[, ...])

Emit a single NewAlgorithmImage event to the SDC event bus.

register_algorithm_image_cli_handler(parsed_args)

CLI handler function for the register-algorithm-image subcommand.

verify_algorithm_registration(...[, ...])

Verify the referenced ECR image exists and an ACTIVE Batch job definition references it.
libera_utils.aws.algorithm_registration._active_job_definition_exists_for_image(batch_client, expected_image: str) → bool#

Return whether any ACTIVE Batch job definition references expected_image as its container image.

libera_utils.aws.algorithm_registration._region_from_ecr_uri(ecr_repository_uri: str) → str | None#

Extract the AWS region from an ECR registry URI, or None if it cannot be parsed.

ECR URIs have the form <account>.dkr.ecr.<region>.amazonaws.com/<repository>.

Parameters:

ecr_repository_uri (str) – The full ECR registry URI (with or without a trailing repository path).

Returns:

The region segment, or None if the URI does not match the expected ECR host format.

Return type:

str or None

libera_utils.aws.algorithm_registration._verify_ecr_image_exists(boto_session: Session, repository_name: str, tag: str) → None#

Confirm that repository_name:tag exists in ECR, raising ValueError if it does not.

Parameters:

  • boto_session (boto3.Session) – Boto3 session used for the (read-only) ECR describe call.

  • repository_name (str) – The short ECR repository name (e.g. l1b-rad-docker-repo).

  • tag (str) – The image tag that must be present in the repository.

Raises:

ValueError – If the repository or the tagged image does not exist in ECR.

libera_utils.aws.algorithm_registration.put_new_algorithm_image_event(processing_step_id: str | ProcessingStepIdentifier, algorithm_version: str, *, boto_session: Session, image_digest: str | None = None, region_name: str | None = None, verify: bool = False, timeout: float = 300.0) → None#

Emit a single NewAlgorithmImage event to the SDC event bus.

The event announces that a concrete algorithm image (one ECR tag) has been uploaded and that the SDC Registrar should register a corresponding versioned AWS Batch job definition for it.

Parameters:

  • processing_step_id (str or ProcessingStepIdentifier) – The processing step whose algorithm this image implements. Determines the ECR repository name.

  • algorithm_version (str) – The concrete ECR image tag that was uploaded, e.g. "1.2.3".

  • boto_session (boto3.Session) – Boto3 session used to discover the event bus, resolve the account id, and put the event.

  • image_digest (str or None, optional) – Optional image digest (sha256:...) carried for provenance/logging. Not required; the registered job definition references the tag, not the digest.

  • 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 (see libera_utils.aws.utils._session_region()).

  • verify (bool, optional) – If True, block after emitting the event until the corresponding job definition is confirmed registered (see verify_algorithm_registration()). Default False.

  • timeout (float, optional) – Maximum number of seconds to wait for registration verification when verify is set.

Raises:

  • ValueError – If processing_step_id has no associated ECR repository (e.g. an L0 step).

  • RuntimeError – If EventBridge reports a failed entry when putting the event.

libera_utils.aws.algorithm_registration.register_algorithm_image_cli_handler(parsed_args: Namespace) → None#

CLI handler function for the register-algorithm-image subcommand.

Assumes the algorithm image has already been uploaded to ECR and emits a NewAlgorithmImage event so the SDC Registrar creates the corresponding versioned Batch job definition. With --verify, blocks until that job definition is confirmed registered.

libera_utils.aws.algorithm_registration.verify_algorithm_registration(ecr_repository_name: str, ecr_repository_uri: str, algorithm_version: str, *, boto_session: Session, timeout: float = 300.0, poll_interval: float = 10.0) → None#

Verify the referenced ECR image exists and an ACTIVE Batch job definition references it.

Two independent checks are performed:

  1. The referenced image ({ecr_repository_name}:{algorithm_version}) actually exists in ECR. This is checked first and unconditionally – even if a matching Batch job definition already exists – because registering a job definition for a nonexistent image would produce a job definition that can never run.

  2. Some ACTIVE Batch job definition has containerProperties.image equal to {ecr_repository_uri}:{algorithm_version}. This is naming-agnostic and polled until it appears.

Parameters:

  • ecr_repository_name (str) – The short ECR repository name (e.g. l1b-rad-docker-repo), used to look the image up in ECR.

  • ecr_repository_uri (str) – The full ECR registry URI for the algorithm image (without tag).

  • algorithm_version (str) – The concrete ECR image tag that should exist in ECR and be referenced by the registered job definition.

  • boto_session (boto3.Session) – Boto3 session used for the (read-only) ECR and Batch describe calls.

  • timeout (float, optional) – Maximum number of seconds to wait for the job definition to appear. Default 300 (5 minutes).

  • poll_interval (float, optional) – Number of seconds between polling passes. Default 10.

Raises:

  • ValueError – If the referenced image does not exist in ECR.

  • TimeoutError – If no matching ACTIVE job definition is found before the timeout elapses.