feat: Implement Finch container client (#8285)

* feat: Finch Native Support

Adds Finch container runtime support as an alternative to Docker for AWS SAM CLI local development and testing.
Finch provides a lightweight, open-source container runtime that offers better performance and resource
efficiency compared to Docker Desktop, especially inenterprise environments. This change enables SAM CLI
users to leverage Finch for local Lambda function development, testing, and debugging without requiring Docker Desktop.

How does it address the issue?
- Container Runtime Abstraction: Implements a unified container client system that supports both Docker and Finch through a factory pattern
- Automatic Detection: Adds enterprise detectionmechanism to automatically identify and configure Finch installations
- API Compatibility: Ensures all existing SAM CLI container operations work seamlessly with Finch
- Test Infrastructure: Updates integration and unit tests to support both container runtimes
- Error Handling: Provides Finch-specific error messages and fallback mechanisms
- Performance Optimizations: Implements file locking and build caching to prevent race conditions
What side effects does this change have?
- Users can now use Finch as a Docker alternative, potentially improving performance and
reducing resource usage
- Existing Docker workflows remain unchanged; Finch support is additive
- New metrics track container runtime preferences for usage analytics

* increase time out for build integration tests

Issue with AppVeyor Windows instances that take longer to finishing building.

* fix: container engine telemetry

* fix: container engine telemetry

* fix: telemetry test in make pr failure

Author: vicheey

.gitignore

@@ -423,3 +423,4 @@ tests/integration/testdata/sync/code/before/dotnet_function/src/HelloWorld/obj/
 # Installer build folder
 .build
 
+.kiro

appveyor-ubuntu.yml

@@ -23,6 +23,7 @@
 from samcli.lib.utils.boto_utils import get_boto_client_provider_with_config
 from samcli.lib.utils.packagetype import ZIP
 from samcli.lib.utils.stream_writer import StreamWriter
+from samcli.local.docker.container_client import ContainerClient
 from samcli.local.docker.exceptions import PortAlreadyInUse
 from samcli.local.docker.lambda_image import LambdaImage
 from samcli.local.docker.manager import ContainerManager
@@ -32,12 +33,6 @@
 LOG = logging.getLogger(__name__)
 
 
-class DockerIsNotReachableException(InvokeContextException):
-    """
-    Docker is not installed or not running at the moment
-    """
-
-
 class InvalidEnvironmentVariablesFileException(InvokeContextException):
     """
     User provided an environment variables file which couldn't be read by SAM CLI
@@ -220,6 +215,7 @@ def __init__(
         self._lambda_runtimes: Optional[Dict[ContainersMode, LambdaRuntime]] = None
 
         self._local_lambda_runner: Optional[LocalLambdaRunner] = None
+        self._initialized_container_ids: List[str] = []
 
     def __enter__(self) -> "InvokeContext":
         """
@@ -280,14 +276,9 @@ def __enter__(self) -> "InvokeContext":
             self._docker_network, self._skip_pull_image, self._shutdown
         )
 
-        if not self._container_manager.is_docker_reachable:
-            raise DockerIsNotReachableException(
-                "Running AWS SAM projects locally requires Docker. Have you got it installed and running?"
-            )
-
         # initialize all lambda function containers upfront
         if self._containers_initializing_mode == ContainersInitializationMode.EAGER:
-            self._initialize_all_functions_containers()
+            self._initialized_container_ids = self._initialize_all_functions_containers()
 
         for func in self._function_provider.get_all():
             if func.packagetype == ZIP and func.inlinecode:
@@ -312,15 +303,20 @@ def __exit__(self, *args: Any) -> None:
         if self._containers_mode == ContainersMode.WARM:
             self._clean_running_containers_and_related_resources()
 
-    def _initialize_all_functions_containers(self) -> None:
+    def _initialize_all_functions_containers(self) -> List[str]:
         """
         Create and run a container for each available lambda function
+
+        Returns:
+            List[str]: List of container IDs that were created and started
         """
         LOG.info("Initializing the lambda functions containers.")
 
+        container_ids = []
+
         def initialize_function_container(function: Function) -> None:
             function_config = self.local_lambda_runner.get_invoke_config(function)
-            self.lambda_runtime.run(
+            container = self.lambda_runtime.run(
                 container=None,
                 function_config=function_config,
                 debug_context=self._debug_context,
@@ -329,13 +325,27 @@ def initialize_function_container(function: Function) -> None:
                 extra_hosts=self._extra_hosts,
             )
 
+            # Collect container ID in a thread-safe way
+            if container and hasattr(container, "id"):
+                container_ids.append(container.id)
+
         try:
             async_context = AsyncContext()
             for function in self._function_provider.get_all():
                 async_context.add_async_task(initialize_function_container, function)
 
             async_context.run_async(default_executor=False)
-            LOG.info("Containers Initialization is done.")
+            LOG.info("Containers created. Waiting for readiness...")
+            LOG.debug("Initialized container IDs: %s", container_ids)
+
+            # Wait for all containers to be ready before returning
+            if container_ids:
+                self._wait_for_containers_readiness(container_ids)
+                LOG.info("All containers are ready.")
+            else:
+                LOG.info("No containers were created.")
+
+            return container_ids
         except KeyboardInterrupt:
             LOG.debug("Ctrl+C was pressed. Aborting containers initialization")
             self._clean_running_containers_and_related_resources()
@@ -347,6 +357,89 @@ def initialize_function_container(function: Function) -> None:
             self._clean_running_containers_and_related_resources()
             raise ContainersInitializationException("Lambda functions containers initialization failed") from ex
 
+    def _wait_for_containers_readiness(self, container_ids: List[str], max_wait_seconds: int = 30) -> None:
+        """
+        Wait for all containers to be running using native Docker container status.
+
+        Args:
+            container_ids: List of container IDs to check
+            max_wait_seconds: Maximum time to wait for all containers to be running
+        """
+        import time
+
+        from samcli.local.docker.utils import get_validated_container_client
+
+        if not container_ids:
+            return
+
+        LOG.info("Waiting for %d containers to be running...", len(container_ids))
+        docker_client = get_validated_container_client()
+        start_time = time.time()
+
+        while time.time() - start_time < max_wait_seconds:
+            running_containers = 0
+
+            for container_id in container_ids:
+                try:
+                    container = docker_client.containers.get(container_id)
+
+                    # Check if container is running
+                    if container.status == "running":
+                        running_containers += 1
+
+                except Exception as e:
+                    LOG.debug("Error checking container %s: %s", container_id[:12], e)
+                    continue
+
+            if running_containers == len(container_ids):
+                elapsed = time.time() - start_time
+                LOG.info("All %d containers running after %.1f seconds", len(container_ids), elapsed)
+                return
+
+            # Log progress every 10 seconds
+            elapsed = time.time() - start_time
+            if int(elapsed) % 10 == 0 and elapsed > 0:
+                LOG.info(
+                    "Container status: %d/%d running after %.1f seconds",
+                    running_containers,
+                    len(container_ids),
+                    elapsed,
+                )
+
+            time.sleep(0.5)  # Check every 500ms
+
+        # Timeout reached
+        elapsed = time.time() - start_time
+        running_containers = sum(1 for cid in container_ids if self._is_container_running(docker_client, cid))
+
+        if running_containers < len(container_ids):
+            LOG.warning(
+                "Container startup timeout after %.1f seconds. %d/%d containers running",
+                elapsed,
+                running_containers,
+                len(container_ids),
+            )
+        else:
+            LOG.info("All containers running after %.1f seconds", elapsed)
+
+    def _is_container_running(self, docker_client: ContainerClient, container_id: str) -> bool:
+        """
+        Check if a container is currently running.
+
+        Args:
+            docker_client: Docker client instance
+            container_id: Container ID to check
+
+        Returns:
+            bool: True if container is running, False otherwise
+        """
+        try:
+            container = docker_client.containers.get(container_id)
+            return bool(container.status == "running")
+        except Exception as e:
+            LOG.debug("Error checking container %s: %s", container_id[:12], e)
+            return False
+
     def _clean_running_containers_and_related_resources(self) -> None:
         """
         Clean the running containers and any other related open resources,
@@ -453,6 +546,16 @@ def local_lambda_runner(self) -> LocalLambdaRunner:
         )
         return self._local_lambda_runner
 
+    @property
+    def initialized_container_ids(self) -> List[str]:
+        """
+        Returns the list of container IDs that were initialized in EAGER mode
+
+        Returns:
+            List[str]: List of container IDs, empty if not in EAGER mode or not initialized
+        """
+        return self._initialized_container_ids
+
     @property
     def stdout(self) -> StreamWriter:
         """

samcli/commands/local/cli_common/invoke_context.py

@@ -154,7 +154,7 @@ def do_cli(
     Implementation of the ``cli`` method
     """
 
-    from datetime import datetime
+    from datetime import datetime, timezone
 
     from samcli.commands.logs.logs_context import ResourcePhysicalIdResolver, parse_time
     from samcli.commands.logs.puller_factory import generate_puller
@@ -168,7 +168,7 @@ def do_cli(
         )
 
     sanitized_start_time = parse_time(start_time, "start-time")
-    sanitized_end_time = parse_time(end_time, "end-time") or datetime.utcnow()
+    sanitized_end_time = parse_time(end_time, "end-time") or datetime.now(timezone.utc)
 
     boto_client_provider = get_boto_client_provider_with_config(region=region, profile=profile)
     boto_resource_provider = get_boto_resource_provider_with_config(region=region, profile=profile)

samcli/commands/logs/command.py

@@ -21,10 +21,8 @@
 
 import boto3
 import click
-import docker
 
 from samcli.commands.package.exceptions import PackageFailedError
-from samcli.lib.constants import DOCKER_MIN_API_VERSION
 from samcli.lib.intrinsic_resolver.intrinsics_symbol_table import IntrinsicsSymbolTable
 from samcli.lib.package.artifact_exporter import Template
 from samcli.lib.package.code_signer import CodeSigner
@@ -36,6 +34,7 @@
 from samcli.lib.utils.boto_utils import get_boto_config_with_user_agent
 from samcli.lib.utils.preview_runtimes import PREVIEW_RUNTIMES
 from samcli.lib.utils.resources import AWS_LAMBDA_FUNCTION, AWS_SERVERLESS_FUNCTION
+from samcli.local.docker.utils import get_validated_container_client
 from samcli.yamlhelper import yaml_dump
 
 LOG = logging.getLogger(__name__)
@@ -124,7 +123,7 @@ def run(self):
         )
         ecr_client = boto3.client("ecr", config=get_boto_config_with_user_agent(region_name=region_name))
 
-        docker_client = docker.from_env(version=DOCKER_MIN_API_VERSION)
+        docker_client = get_validated_container_client()
 
         s3_uploader = S3Uploader(
             s3_client, self.s3_bucket, self.s3_prefix, self.kms_key_id, self.force_upload, self.no_progressbar

samcli/commands/package/package_context.py

@@ -5,7 +5,7 @@
 import logging
 import threading
 from dataclasses import dataclass
-from datetime import datetime
+from datetime import datetime, timezone
 from pathlib import Path
 from typing import Dict, Optional, cast
 
@@ -56,13 +56,13 @@ def update_resource_sync_state(self, resource_id: str, hash_value: str) -> None:
         hash_value: str
             The logical ID identifier of the resource
         """
-        self.resource_sync_states[resource_id] = ResourceSyncState(hash_value, datetime.utcnow())
+        self.resource_sync_states[resource_id] = ResourceSyncState(hash_value, datetime.now(timezone.utc))
 
     def update_infra_sync_time(self) -> None:
         """
         Updates the last infra sync time to be stored in the TOML file.
         """
-        self.latest_infra_sync_time = datetime.utcnow()
+        self.latest_infra_sync_time = datetime.now(timezone.utc)
 
 
 def _sync_state_to_toml_document(sync_state: SyncState) -> TOMLDocument:

samcli/commands/sync/sync_context.py

@@ -73,7 +73,7 @@ def do_cli(trace_ids, tailing, start_time, end_time, output, region):
     """
     Implementation of the ``cli`` method
     """
-    from datetime import datetime
+    from datetime import datetime, timezone
 
     import boto3
 
@@ -82,7 +82,7 @@ def do_cli(trace_ids, tailing, start_time, end_time, output, region):
     from samcli.lib.utils.boto_utils import get_boto_config_with_user_agent
 
     sanitized_start_time = parse_time(start_time, "start-time")
-    sanitized_end_time = parse_time(end_time, "end-time") or datetime.utcnow()
+    sanitized_end_time = parse_time(end_time, "end-time") or datetime.now(timezone.utc)
 
     boto_config = get_boto_config_with_user_agent(region_name=region)
     xray_client = boto3.client("xray", config=boto_config)