dbt-platform-helper 13.1.0__py3-none-any.whl → 15.16.0__py3-none-any.whl

dbt_platform_helper/providers/config.py

@@ -1,41 +1,76 @@
 from copy import deepcopy
+from datetime import datetime
 from pathlib import Path
 
 from schema import SchemaError
 
+from dbt_platform_helper.constants import FIRST_UPGRADABLE_PLATFORM_HELPER_MAJOR_VERSION
 from dbt_platform_helper.constants import PLATFORM_CONFIG_FILE
+from dbt_platform_helper.constants import PLATFORM_CONFIG_SCHEMA_VERSION
+from dbt_platform_helper.constants import PLATFORM_HELPER_PACKAGE_NAME
+from dbt_platform_helper.entities.platform_config_schema import PlatformConfigSchema
+from dbt_platform_helper.entities.semantic_version import SemanticVersion
 from dbt_platform_helper.providers.config_validator import ConfigValidator
 from dbt_platform_helper.providers.config_validator import ConfigValidatorError
 from dbt_platform_helper.providers.io import ClickIOProvider
-from dbt_platform_helper.providers.platform_config_schema import PlatformConfigSchema
+from dbt_platform_helper.providers.version import InstalledVersionProvider
 from dbt_platform_helper.providers.yaml_file import FileNotFoundException
 from dbt_platform_helper.providers.yaml_file import FileProviderException
 from dbt_platform_helper.providers.yaml_file import YamlFileProvider
 
+SCHEMA_VERSION_MESSAGE = """Installed version: platform-helper: {installed_platform_helper_version} (schema version: {installed_schema_version})
+'platform-config.yml' version: platform-helper: {config_platform_helper_version} (schema version: {config_schema_version})"""
+PLEASE_UPGRADE_TO_V13_MESSAGE = """Please ensure that you have already upgraded to platform-helper 13, following the instructions in https://platform.readme.trade.gov.uk/reference/upgrading-platform-helper/.
+
+Then upgrade platform-helper to version {installed_platform_helper_version} and run 'platform-helper config migrate' to upgrade the configuration to the current schema version."""
+
+
+class ConfigLoader:
+    def __init__(self, file_provider=YamlFileProvider, io: ClickIOProvider = ClickIOProvider()):
+        self.io = io
+        self.file_provider = file_provider
+
+    def load(self, path):
+        try:
+            file_content = self.file_provider.load(path)
+            return file_content
+        except FileNotFoundException as e:
+            self.io.abort_with_error(
+                f"{e} Please check it exists and you are in the root directory of your -deploy repository."
+            )
+        except FileProviderException as e:
+            self.io.abort_with_error(f"Error loading configuration from {path}: {e}")
+
 
 class ConfigProvider:
     def __init__(
         self,
-        config_validator: ConfigValidator = None,
-        file_provider: YamlFileProvider = None,
-        io: ClickIOProvider = None,
+        config_validator: ConfigValidator = ConfigValidator(),
+        file_provider: YamlFileProvider = YamlFileProvider,
+        io: ClickIOProvider = ClickIOProvider(),
+        schema_version_for_installed_platform_helper: int = PLATFORM_CONFIG_SCHEMA_VERSION,
+        installed_version_provider: InstalledVersionProvider = InstalledVersionProvider,
     ):
         self.config = {}
-        self.validator = config_validator or ConfigValidator()
-        self.io = io or ClickIOProvider()
-        self.file_provider = file_provider or YamlFileProvider
-
-    # TODO refactor so that apply_environment_defaults isn't set, discarded and set again
+        self.validator = config_validator
+        self.io = io
+        self.file_provider = file_provider
+        self.schema_version_for_installed_platform_helper = (
+            schema_version_for_installed_platform_helper
+        )
+        self.installed_version_provider = installed_version_provider
+
+    # TODO: DBTP-1964: refactor so that apply_environment_defaults isn't set, discarded and set again
     def get_enriched_config(self):
         return self.apply_environment_defaults(self.load_and_validate_platform_config())
 
     def _validate_platform_config(self):
         PlatformConfigSchema.schema().validate(self.config)
-
-        # TODO= logically this isn't validation but loading + parsing, to move.
+        # TODO: DBTP-1964: = logically this isn't validation but loading + parsing, to move.
         # also, we apply defaults but discard that data.  Should we just apply
         # defaults to config returned by load_and_validate
         enriched_config = ConfigProvider.apply_environment_defaults(self.config)
+
         try:
             self.validator.run_validations(enriched_config)
         except ConfigValidatorError as exc:
@@ -51,6 +86,8 @@ class ConfigProvider:
         except FileProviderException as e:
             self.io.abort_with_error(f"Error loading configuration from {path}: {e}")
 
+        self._validate_schema_version()
+
         try:
             self._validate_platform_config()
         except SchemaError as e:
@@ -58,13 +95,91 @@ class ConfigProvider:
 
         return self.config
 
+    def _abort_due_to_schema_version_error(self, config_description: str, action_required: str):
+        self.io.abort_with_error(
+            "\n".join(
+                [
+                    config_description,
+                    "",
+                    action_required,
+                ]
+            )
+        )
+
+    def _validate_schema_version(self):
+        config_schema_version = self.config.get("schema_version")
+        config_platform_helper_version = self.config.get("default_versions", {}).get(
+            "platform-helper", ""
+        )
+        header = SCHEMA_VERSION_MESSAGE.format(
+            installed_platform_helper_version=self._installed_platform_helper_version(),
+            installed_schema_version=self.schema_version_for_installed_platform_helper,
+            config_platform_helper_version=(
+                config_platform_helper_version if config_platform_helper_version else "N/A"
+            ),
+            config_schema_version=(config_schema_version if config_schema_version else "N/A"),
+        )
+
+        if config_schema_version:
+            self._handle_schema_version_mismatch(config_schema_version, header)
+        else:
+            self._handle_missing_schema_version(config_platform_helper_version, header)
+
+    def _handle_schema_version_mismatch(self, platform_config_schema_version: int, header: str):
+        platform_config_schema_version_is_old = (
+            platform_config_schema_version < self.schema_version_for_installed_platform_helper
+        )
+        installed_platform_helper_is_old = (
+            platform_config_schema_version > self.schema_version_for_installed_platform_helper
+        )
+
+        if platform_config_schema_version_is_old:
+            self._abort_due_to_schema_version_error(
+                header,
+                "Please upgrade your platform-config.yml by running 'platform-helper config migrate'.",
+            )
+        elif installed_platform_helper_is_old:
+            self._abort_due_to_schema_version_error(
+                header,
+                f"Please update your platform-helper to a version that supports schema_version: {platform_config_schema_version}.",
+            )
+        # else the schema_version is the correct one so continue.
+
+    def _handle_missing_schema_version(self, config_platform_helper_version: str, header: str):
+        config_p_h_version_semver = SemanticVersion.from_string(config_platform_helper_version)
+        major_version = config_p_h_version_semver and config_p_h_version_semver.major
+        platform_config_is_old_but_supported_by_migrations = (
+            major_version and major_version == FIRST_UPGRADABLE_PLATFORM_HELPER_MAJOR_VERSION
+        )
+        platform_config_is_old = (
+            major_version and major_version < FIRST_UPGRADABLE_PLATFORM_HELPER_MAJOR_VERSION
+        )
+        platform_config_is_really_old = not major_version
+        installed_platform_helper_version = self._installed_platform_helper_version()
+
+        if platform_config_is_old_but_supported_by_migrations:
+            self._abort_due_to_schema_version_error(
+                header,
+                f"Please upgrade your platform-config.yml to be compatible with {installed_platform_helper_version} by running: 'platform-helper config migrate'.",
+            )
+        elif platform_config_is_old or platform_config_is_really_old:
+            self._abort_due_to_schema_version_error(
+                header,
+                PLEASE_UPGRADE_TO_V13_MESSAGE.format(
+                    installed_platform_helper_version=installed_platform_helper_version,
+                ),
+            )
+        # if major_version and major_version > FIRST_UPGRADABLE_PLATFORM_HELPER_MAJOR_VERSION then
+        # the platform-config.yml is malformed and so should progress to validation if appropriate.
+
     def load_unvalidated_config_file(self, path=PLATFORM_CONFIG_FILE):
         try:
             return self.file_provider.load(path)
         except FileProviderException:
             return {}
 
-    # TODO this general function should be moved out of ConfigProvider
+    # TODO: DBTP-1888: remove function and push logic to where this is called.
+    # removed usage from config domain, code is very generic and doesn't require the overhead of a function
     def config_file_check(self, path=PLATFORM_CONFIG_FILE):
         if not Path(path).exists():
             self.io.abort_with_error(
@@ -85,17 +200,10 @@ class ConfigProvider:
             name: data if data else {} for name, data in environments.items() if name != "*"
         }
 
-        default_versions = config.get("default_versions", {})
-
         def combine_env_data(data):
             return {
                 **env_defaults,
                 **data,
-                "versions": {
-                    **default_versions,
-                    **env_defaults.get("versions", {}),
-                    **data.get("versions", {}),
-                },
             }
 
         defaulted_envs = {
@@ -106,3 +214,13 @@ class ConfigProvider:
         enriched_config["environments"] = defaulted_envs
 
         return enriched_config
+
+    def write_platform_config(self, new_platform_config):
+        current_date = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+        message = f"# Generated by platform-helper {self._installed_platform_helper_version()} / {current_date}.\n\n"
+        self.file_provider.write(PLATFORM_CONFIG_FILE, new_platform_config, message)
+
+    def _installed_platform_helper_version(self) -> str:
+        return str(
+            self.installed_version_provider.get_semantic_version(PLATFORM_HELPER_PACKAGE_NAME)
+        )

dbt_platform_helper/providers/config_validator.py

@@ -3,9 +3,11 @@ from typing import Callable
 import boto3
 
 from dbt_platform_helper.platform_exception import PlatformException
+from dbt_platform_helper.providers.aws.opensearch import Opensearch
+from dbt_platform_helper.providers.aws.redis import Redis
+from dbt_platform_helper.providers.cache import Cache
+from dbt_platform_helper.providers.cache import GetAWSVersionStrategy
 from dbt_platform_helper.providers.io import ClickIOProvider
-from dbt_platform_helper.providers.opensearch import OpensearchProvider
-from dbt_platform_helper.providers.redis import RedisProvider
 
 
 class ConfigValidatorError(PlatformException):
@@ -15,7 +17,10 @@ class ConfigValidatorError(PlatformException):
 class ConfigValidator:
 
     def __init__(
-        self, validations: Callable[[dict], None] = None, io: ClickIOProvider = ClickIOProvider()
+        self,
+        validations: Callable[[dict], None] = None,
+        io: ClickIOProvider = ClickIOProvider(),
+        session: boto3.Session = None,
     ):
         self.validations = validations or [
             self.validate_supported_redis_versions,
@@ -23,16 +28,19 @@ class ConfigValidator:
             self.validate_environment_pipelines,
             self.validate_environment_pipelines_triggers,
             self.validate_database_copy_section,
-            self.validate_database_migration_input_sources,
+            self.validate_s3_data_migration_config,
+            self.validate_cache_invalidation_config,
+            self.validate_config_for_managed_upgrades,
         ]
         self.io = io
+        self.session = session
 
     def run_validations(self, config: dict):
         for validation in self.validations:
             validation(config)
 
     def _validate_extension_supported_versions(
-        self, config, extension_type, version_key, get_supported_versions
+        self, config, aws_provider, extension_type, version_key
     ):
         extensions = config.get("extensions", {})
         if not extensions:
@@ -44,7 +52,10 @@ class ConfigValidator:
             if extension.get("type") == extension_type
         ]
 
-        supported_extension_versions = get_supported_versions()
+        # In this format so it can be monkey patched initially via mock_get_data fixture
+        cache_provider = Cache()
+        get_data_strategy = GetAWSVersionStrategy(aws_provider)
+        supported_extension_versions = cache_provider.get_data(get_data_strategy)
         extensions_with_invalid_version = []
 
         for extension in extensions_for_type:
@@ -71,24 +82,25 @@ class ConfigValidator:
                 f"{extension_type} version for environment {version_failure['environment']} is not in the list of supported {extension_type} versions: {supported_extension_versions}. Provided Version: {version_failure['version']}",
             )
 
+    def _get_client(self, service_name: str):
+        if self.session:
+            return self.session.client(service_name)
+        return boto3.client(service_name)
+
     def validate_supported_redis_versions(self, config):
         return self._validate_extension_supported_versions(
             config=config,
-            extension_type="redis",
-            version_key="engine",
-            get_supported_versions=RedisProvider(
-                boto3.client("elasticache")
-            ).get_supported_redis_versions,
+            aws_provider=Redis(self._get_client("elasticache")),
+            extension_type="redis",  # TODO: DBTP-1888: this is information which can live in the RedisProvider
+            version_key="engine",  # TODO: DBTP-1888: this is information which can live in the RedisProvider
         )
 
     def validate_supported_opensearch_versions(self, config):
         return self._validate_extension_supported_versions(
             config=config,
-            extension_type="opensearch",
-            version_key="engine",
-            get_supported_versions=OpensearchProvider(
-                boto3.client("opensearch")
-            ).get_supported_opensearch_versions,
+            aws_provider=Opensearch(self._get_client("opensearch")),
+            extension_type="opensearch",  # TODO: DBTP-1888: this is information which can live in the OpensearchProvider
+            version_key="engine",  # TODO: DBTP-1888: this is information which can live in the OpensearchProvider
         )
 
     def validate_environment_pipelines(self, config):
@@ -170,21 +182,6 @@ class ConfigValidator:
                 from_env = section["from"]
                 to_env = section["to"]
 
-                from_account = (
-                    config.get("environments", {})
-                    .get(from_env, {})
-                    .get("accounts", {})
-                    .get("deploy", {})
-                    .get("id")
-                )
-                to_account = (
-                    config.get("environments", {})
-                    .get(to_env, {})
-                    .get("accounts", {})
-                    .get("deploy", {})
-                    .get("id")
-                )
-
                 if from_env == to_env:
                     errors.append(
                         f"database_copy 'to' and 'from' cannot be the same environment in extension '{extension_name}'."
@@ -205,29 +202,10 @@ class ConfigValidator:
                         f"database_copy 'to' parameter must be a valid environment ({all_envs_string}) but was '{to_env}' in extension '{extension_name}'."
                     )
 
-                if from_account != to_account:
-                    if "from_account" not in section:
-                        errors.append(
-                            f"Environments '{from_env}' and '{to_env}' are in different AWS accounts. The 'from_account' parameter must be present."
-                        )
-                    elif section["from_account"] != from_account:
-                        errors.append(
-                            f"Incorrect value for 'from_account' for environment '{from_env}'"
-                        )
-
-                    if "to_account" not in section:
-                        errors.append(
-                            f"Environments '{from_env}' and '{to_env}' are in different AWS accounts. The 'to_account' parameter must be present."
-                        )
-                    elif section["to_account"] != to_account:
-                        errors.append(
-                            f"Incorrect value for 'to_account' for environment '{to_env}'"
-                        )
-
         if errors:
             raise ConfigValidatorError("\n".join(errors))
 
-    def validate_database_migration_input_sources(self, config: dict):
+    def validate_s3_data_migration_config(self, config: dict):
         extensions = config.get("extensions", {})
         if not extensions:
             return
@@ -246,6 +224,10 @@ class ConfigValidator:
                 if "data_migration" not in env_config:
                     continue
                 data_migration = env_config.get("data_migration", {})
+                if extension.get("serve_static_content", {}):
+                    errors.append(
+                        "Data migration is not supported for static S3 buckets to avoid the risk of unintentionally exposing private data. However, you can copy data on an ad hoc basis using AWS CLI commands such as 'aws s3 sync' or 'aws s3 cp'."
+                    )
                 if "import" in data_migration and "import_sources" in data_migration:
                     errors.append(
                         f"Error in '{extension_name}.environments.{env}.data_migration': only the 'import_sources' property is required - 'import' is deprecated."
@@ -256,3 +238,82 @@ class ConfigValidator:
                     )
         if errors:
             raise ConfigValidatorError("\n".join(errors))
+
+    def validate_cache_invalidation_config(self, config: dict):
+        codebase_pipelines = config.get("codebase_pipelines")
+        if not codebase_pipelines:
+            return
+
+        errors = []
+
+        all_environments = [env for env in config.get("environments", {}).keys() if not env == "*"]
+
+        for codebase in codebase_pipelines.values():
+            cache_invalidation_config = codebase.get("cache_invalidation")
+            if cache_invalidation_config:
+                for domain, config in cache_invalidation_config.get("domains").items():
+                    environment = config.get("environment")
+                    if environment not in all_environments:
+                        errors.append(
+                            f"Error in cache invalidation configuration for the domain '{domain}'.  Environment '{environment}' is not defined for this application"
+                        )
+
+        if errors:
+            raise ConfigValidatorError("\n".join(errors))
+
+    def validate_config_for_managed_upgrades(self, config: dict):
+        """
+        Validates that pipelines do not contain manual approvals when managed
+        upgrades are enabled.
+
+        Args:
+            config (dict): The platform configuration dictionary.
+
+        Raises:
+            ConfigValidatorError:
+            - If any pipeline contains manual approvals when platform-helper is "auto".
+            - If platform-config.yml is missing environment_pipelines or codebase_pipelines configuration.
+        """
+        errors = []
+
+        def find_pipeline_for_env(env_pipelines, env: str):
+            for name, config in env_pipelines.items():
+                if not isinstance(config, dict):
+                    continue
+                envs = config.get("environments", {})
+                if isinstance(envs, dict) and env in envs:
+                    return name
+
+        if config.get("default_versions", {}).get("platform-helper") == "auto":
+
+            pipelines = {}
+            environments = [env for env in config.get("environments").keys() if env != "*"]
+            environment_pipelines = config.get("environment_pipelines", {})
+            for env in environments:
+                pipeline = find_pipeline_for_env(environment_pipelines, env)
+                if not pipeline:
+                    errors.append(
+                        f"For auto default platform-helper version, all environments {environments} must be deployed in an environment pipeline. Missing: {env}"
+                    )
+
+            for pipeline_section in ["environment_pipelines", "codebase_pipelines"]:
+                pipelines = config.get(pipeline_section, {})
+
+                if not pipelines:
+                    errors.append(
+                        f"For auto default platform-helper version, environment and codebase pipelines must be configured in platform-config.yml. {pipeline_section} is not configured."
+                    )
+                    continue
+
+                for pipeline_name, pipeline in pipelines.items():
+                    if pipeline_section == "environment_pipelines":
+                        pipeline_deploy_to_environments = pipeline.get("environments", {})
+                        for env_name, env_config in pipeline_deploy_to_environments.items():
+                            if isinstance(env_config, dict) and env_config.get("requires_approval"):
+                                errors.append(
+                                    f"Managed upgrades enabled: (environment_pipelines) Pipeline '{pipeline_name}' environment '{env_name}' "
+                                    "cannot have manual approval when platform-helper is 'auto'."
+                                )
+
+        if errors:
+            raise ConfigValidatorError("\n".join(errors))

dbt_platform_helper/providers/copilot.py

@@ -1,10 +1,11 @@
 import json
+import subprocess
 import time
 
 from botocore.exceptions import ClientError
 
 from dbt_platform_helper.constants import CONDUIT_DOCKER_IMAGE_LOCATION
-from dbt_platform_helper.providers.aws import CreateTaskTimeoutException
+from dbt_platform_helper.providers.aws.exceptions import CreateTaskTimeoutException
 from dbt_platform_helper.providers.secrets import Secrets
 from dbt_platform_helper.utils.application import Application
 from dbt_platform_helper.utils.messages import abort_with_error
@@ -13,7 +14,6 @@ from dbt_platform_helper.utils.messages import abort_with_error
 def create_addon_client_task(
     iam_client,
     ssm_client,
-    subprocess,
     application: Application,
     env: str,
     addon_type: str,
@@ -31,7 +31,6 @@ def create_addon_client_task(
         elif access == "admin":
             create_postgres_admin_task(
                 ssm_client,
-                subprocess,
                 application,
                 addon_name,
                 addon_type,
@@ -53,7 +52,7 @@ def create_addon_client_task(
         # We cannot check for botocore.errorfactory.NoSuchEntityException as botocore generates that class on the fly as part of errorfactory.
         # factory. Checking the error code is the recommended way of handling these exceptions.
         if ex.response.get("Error", {}).get("Code", None) != "NoSuchEntity":
-            # TODO When we are refactoring this, raise an exception to be caught at the command layer
+            # TODO: DBTP-1946: When we are refactoring this, raise an exception to be caught at the command layer
             abort_with_error(
                 f"cannot obtain Role {role_name}: {ex.response.get('Error', {}).get('Message', '')}"
             )
@@ -71,15 +70,8 @@ def create_addon_client_task(
     )
 
 
-def create_postgres_admin_task(
-    ssm_client,
-    subprocess,
-    app: Application,
-    addon_name: str,
-    addon_type: str,
-    env: str,
-    secret_name: str,
-    task_name: str,
+def get_postgres_admin_connection_string(
+    ssm_client, secret_name: str, app: Application, env: str, addon_name: str
 ):
     read_only_secret_name = secret_name + "_READ_ONLY_USER"
     master_secret_name = (
@@ -94,6 +86,23 @@ def create_postgres_admin_task(
         )
     )
 
+    return connection_string
+
+
+def create_postgres_admin_task(
+    ssm_client,
+    app: Application,
+    addon_name: str,
+    addon_type: str,
+    env: str,
+    secret_name: str,
+    task_name: str,
+):
+
+    connection_string = get_postgres_admin_connection_string(
+        ssm_client, secret_name, app, env, addon_name
+    )
+
     subprocess.call(
         f"copilot task run --app {app.name} --env {env} "
         f"--task-group-name {task_name} "
@@ -121,7 +130,6 @@ def _temp_until_refactor_get_ecs_task_arns(ecs_client, cluster_arn: str, task_na
 
 def connect_to_addon_client_task(
     ecs_client,
-    subprocess,
     application_name,
     env,
     cluster_arn,
@@ -132,7 +140,7 @@ def connect_to_addon_client_task(
     tries = 0
     while tries < 15 and not running:
         tries += 1
-        # Todo: Use from ECS provider when we refactor this
+        # TODO: DBTP-1946: Use from ECS provider when we refactor this
         if get_ecs_task_arns(ecs_client, cluster_arn, task_name):
             subprocess.call(
                 "copilot task exec "
@@ -154,7 +162,7 @@ def _normalise_secret_name(addon_name: str) -> str:
 
 
 def _get_secrets_provider(application: Application, env: str) -> Secrets:
-    # Todo: We instantiate the secrets provider here to avoid rabbit holing, but something better probably possible when we are refactoring this area
+    # TODO: DBTP-1946: We instantiate the secrets provider here to avoid rabbit holing, but something better probably possible when we are refactoring this area
     return Secrets(
         application.environments[env].session.client("ssm"),
         application.environments[env].session.client("secretsmanager"),

dbt_platform_helper/providers/ecr.py

@@ -1,20 +1,102 @@
+from collections import defaultdict
+
+import botocore
 from boto3 import Session
 
+from dbt_platform_helper.providers.aws.exceptions import AWSException
+from dbt_platform_helper.providers.aws.exceptions import ImageNotFoundException
+from dbt_platform_helper.providers.aws.exceptions import MultipleImagesFoundException
+from dbt_platform_helper.providers.aws.exceptions import RepositoryNotFoundException
+from dbt_platform_helper.providers.io import ClickIOProvider
 from dbt_platform_helper.utils.aws import get_aws_session_or_abort
 
+NOT_A_UNIQUE_TAG_INFO = 'INFO: The tag "{image_ref}" is not a unique, commit-specific tag. Deploying the corresponding commit tag "{commit_tag}" instead.'
+NO_ASSOCIATED_COMMIT_TAG_WARNING = 'WARNING: The AWS ECR image "{image_ref}" has no associated commit tag so deploying "{image_ref}". Note this could result in images with unintended or incompatible changes being deployed in new ECS Tasks for your service.'
+
 
 class ECRProvider:
-    def __init__(self, session: Session = None):
+    def __init__(self, session: Session = None, click_io: ClickIOProvider = ClickIOProvider()):
         self.session = session
-        self.client = None
-
-    def _get_client(self):
-        if not self.session:
-            self.session = get_aws_session_or_abort()
-        return self.session.client("ecr")
+        self.click_io = click_io
 
     def get_ecr_repo_names(self) -> list[str]:
         out = []
         for page in self._get_client().get_paginator("describe_repositories").paginate():
             out.extend([repo["repositoryName"] for repo in page.get("repositories", {})])
         return out
+
+    def get_commit_tag_for_reference(self, application_name: str, codebase: str, image_ref: str):
+        repository = f"{application_name}/{codebase}"
+        next_page_token = None
+        tag_map = {}
+        digest_map = defaultdict(dict)
+
+        while True:
+            image_list = self._get_ecr_images(repository, image_ref, next_page_token)
+            next_page_token = image_list.get("nextToken")
+
+            for image in image_list["imageIds"]:
+                digest, tag = image["imageDigest"], image["imageTag"]
+                digest_map[digest][tag.split("-")[0]] = tag
+                tag_map[tag] = digest
+
+            if not next_page_token:
+                break
+
+        if image_ref.startswith("commit-"):
+            if image_ref in tag_map:
+                return image_ref
+            else:
+                candidates = [
+                    tag
+                    for tag in tag_map.keys()
+                    if image_ref.startswith(tag) or tag.startswith(image_ref)
+                ]
+                if not candidates:
+                    raise ImageNotFoundException(image_ref)
+                if len(candidates) > 1:
+                    raise MultipleImagesFoundException(image_ref, candidates)
+                return candidates[0]
+        else:
+            digest = tag_map.get(image_ref)
+            if not digest:
+                raise ImageNotFoundException(image_ref)
+
+            commit_tag = digest_map.get(digest, dict()).get("commit")
+
+            if commit_tag:
+                self.click_io.info(
+                    NOT_A_UNIQUE_TAG_INFO.format(image_ref=image_ref, commit_tag=commit_tag)
+                )
+                return commit_tag
+            else:
+                self.click_io.warn(NO_ASSOCIATED_COMMIT_TAG_WARNING.format(image_ref=image_ref))
+                return image_ref
+
+    def _get_ecr_images(self, repository, image_ref, next_page_token):
+        params = {"repositoryName": repository, "filter": {"tagStatus": "TAGGED"}}
+        if next_page_token:
+            params["nextToken"] = next_page_token
+        try:
+            image_list = self._get_client().list_images(**params)
+            return image_list
+        except botocore.exceptions.ClientError as e:
+            if e.response["Error"]["Code"] == "RepositoryNotFoundException":
+                raise RepositoryNotFoundException(repository)
+            else:
+                raise AWSException(
+                    f"Unexpected error for repo '{repository}' and image reference '{image_ref}': {e}"
+                )
+
+    @staticmethod
+    def _check_image_details_exists(image_info: dict, image_ref: str):
+        """Error handling for any unexpected scenario where AWS ECR returns a
+        malformed response."""
+
+        if "imageDetails" not in image_info:
+            raise ImageNotFoundException(image_ref)
+
+    def _get_client(self):
+        if not self.session:
+            self.session = get_aws_session_or_abort()
+        return self.session.client("ecr")