feat: add ECS and AgentCore container build/package/deploy support

Extends SAM CLI to build, package, and deploy container images for
AWS::ECS::TaskDefinition and AWS::BedrockAgentCore::Runtime resources
using the same Metadata convention as Lambda Image functions.

## Changes

- Add resource type constants and RESOURCES_WITH_IMAGE_COMPONENT entries
- Add ContainerBuildDefinition to build graph with Architecture support
- Add build_container_images() to ApplicationBuilder
- Create packageable resource classes for ECR push during package/deploy
- Create SamContainerServiceProvider to discover buildable resources
- Wire container builds into BuildContext.run()
- Create ECSContainerSyncFlow for sam sync support
- Register in SyncFlowFactory
- Extend sync_ecr_stack for auto ECR repo creation (--resolve-image-repos)
- Support ContainerName metadata for multi-container ECS TaskDefinitions
- Update sam build help text

## Template Usage

```yaml
Resources:
  MyAgent:
    Type: AWS::BedrockAgentCore::Runtime
    Metadata:
      Dockerfile: Dockerfile
      DockerContext: ./agent
      DockerTag: latest
      Architecture: arm64
    Properties:
      AgentRuntimeArtifact:
        ContainerConfiguration:
          ContainerUri: placeholder

  MyTask:
    Type: AWS::ECS::TaskDefinition
    Metadata:
      Dockerfile: Dockerfile
      DockerContext: ./app
      ContainerName: web  # targets specific container
    Properties:
      ContainerDefinitions:
        - Name: web
          Image: placeholder
```

## Testing

- 51 new unit tests (853 total passing)
- Integration test with Docker build
- End-to-end validated: build → ECR push → CloudFormation deploy

Author: singledigit

samcli/commands/build/build_context.py

@@ -26,7 +26,7 @@
     BuildError,
     UnsupportedBuilderLibraryVersionError,
 )
-from samcli.lib.build.build_graph import DEFAULT_DEPENDENCIES_DIR
+from samcli.lib.build.build_graph import DEFAULT_DEPENDENCIES_DIR, ContainerBuildDefinition
 from samcli.lib.build.bundler import EsbuildBundlerManager
 from samcli.lib.build.exceptions import (
     BuildInsideContainerError,
@@ -38,6 +38,7 @@
 from samcli.lib.providers.sam_api_provider import SamApiProvider
 from samcli.lib.providers.sam_function_provider import SamFunctionProvider
 from samcli.lib.providers.sam_layer_provider import SamLayerProvider
+from samcli.lib.providers.sam_container_provider import SamContainerServiceProvider
 from samcli.lib.providers.sam_stack_provider import SamLocalStackProvider
 from samcli.lib.telemetry.event import EventName, EventTracker, UsedFeature
 from samcli.lib.utils.osutils import BUILD_DIR_PERMISSIONS
@@ -293,6 +294,11 @@ def run(self) -> None:
 
             self._build_result = builder.build()
 
+            # Build container images for ECS/AgentCore resources
+            container_artifacts = self._build_container_images(builder)
+            if container_artifacts:
+                self._build_result.artifacts.update(container_artifacts)
+
             self._handle_build_post_processing(builder, self._build_result)
 
             click.secho("\nBuild Succeeded", fg="green")
@@ -623,6 +629,33 @@ def collect_all_build_resources(self) -> ResourcesToBuildCollector:
         )
         return result
 
+    def _build_container_images(self, builder: ApplicationBuilder) -> Dict[str, str]:
+        """
+        Discover and build container images for ECS/AgentCore resources.
+
+        Returns
+        -------
+        Dict[str, str]
+            Map of resource full_path to built image tag
+        """
+        container_provider = SamContainerServiceProvider(self.stacks)
+        container_services = list(container_provider.get_all())
+        if not container_services:
+            return {}
+
+        LOG.info("Found %d container service resource(s) to build", len(container_services))
+
+        container_build_defs = []
+        for service in container_services:
+            build_def = ContainerBuildDefinition(
+                resource_identifier=service.full_path,
+                resource_type=service.resource_type,
+                metadata=service.metadata,
+            )
+            container_build_defs.append(build_def)
+
+        return builder.build_container_images(container_build_defs)
+
     @property
     def is_building_specific_resource(self) -> bool:
         """

samcli/commands/build/command.py

@@ -54,6 +54,8 @@
   2. AWS::Lambda::Function\n
   3. AWS::Serverless::LayerVersion\n
   4. AWS::Lambda::LayerVersion\n
+  5. AWS::ECS::TaskDefinition (container image)\n
+  6. AWS::BedrockAgentCore::Runtime (container image)\n
   \b
   Supported Runtimes
   ------------------

samcli/lib/bootstrap/companion_stack/companion_stack_manager.py

@@ -312,6 +312,14 @@ def sync_ecr_stack(
     function_logical_ids = [
         function.full_path for function in function_provider.get_all() if function.packagetype == IMAGE
     ]
+
+    # Also include ECS/AgentCore container resources that need ECR repos
+    from samcli.lib.providers.sam_container_provider import SamContainerServiceProvider
+
+    container_provider = SamContainerServiceProvider(stacks)
+    container_logical_ids = [service.full_path for service in container_provider.get_all()]
+    function_logical_ids.extend(container_logical_ids)
+
     manager.set_functions(function_logical_ids, image_repositories)
     image_repositories.update(manager.get_repository_mapping())
     manager.sync_repos()

samcli/lib/build/app_builder.py

@@ -19,7 +19,7 @@
 from aws_lambda_builders.exceptions import LambdaBuilderError
 
 from samcli.commands._utils.experimental import get_enabled_experimental_flags
-from samcli.lib.build.build_graph import BuildGraph, FunctionBuildDefinition, LayerBuildDefinition
+from samcli.lib.build.build_graph import BuildGraph, ContainerBuildDefinition, FunctionBuildDefinition, LayerBuildDefinition
 from samcli.lib.build.build_strategy import (
     BuildStrategy,
     CachedOrIncrementalBuildStrategyWrapper,
@@ -51,7 +51,9 @@
 from samcli.lib.utils.packagetype import IMAGE, ZIP
 from samcli.lib.utils.path_utils import check_path_valid_type, convert_path_to_unix_path
 from samcli.lib.utils.resources import (
+    AWS_BEDROCK_AGENTCORE_RUNTIME,
     AWS_CLOUDFORMATION_STACK,
+    AWS_ECS_TASK_DEFINITION,
     AWS_LAMBDA_FUNCTION,
     AWS_LAMBDA_LAYERVERSION,
     AWS_SERVERLESS_APPLICATION,
@@ -378,7 +380,8 @@ def update_template(
 
             if has_build_artifact:
                 ApplicationBuilder._update_built_resource(
-                    built_artifacts[full_path], properties, resource_type, store_path
+                    built_artifacts[full_path], properties, resource_type, store_path,
+                    resource.get("Metadata"),
                 )
 
             if is_stack:
@@ -391,7 +394,9 @@ def update_template(
         return template_dict
 
     @staticmethod
-    def _update_built_resource(path: str, resource_properties: Dict, resource_type: str, absolute_path: str) -> None:
+    def _update_built_resource(
+        path: str, resource_properties: Dict, resource_type: str, absolute_path: str, metadata: Optional[Dict] = None
+    ) -> None:
         if resource_type == AWS_SERVERLESS_FUNCTION and resource_properties.get("PackageType", ZIP) == ZIP:
             resource_properties["CodeUri"] = absolute_path
         if resource_type == AWS_LAMBDA_FUNCTION and resource_properties.get("PackageType", ZIP) == ZIP:
@@ -404,6 +409,21 @@ def _update_built_resource(path: str, resource_properties: Dict, resource_type:
             resource_properties["Code"] = {"ImageUri": path}
         if resource_type == AWS_SERVERLESS_FUNCTION and resource_properties.get("PackageType", ZIP) == IMAGE:
             resource_properties["ImageUri"] = path
+        if resource_type == AWS_ECS_TASK_DEFINITION:
+            container_defs = resource_properties.get("ContainerDefinitions", [])
+            if container_defs:
+                target_name = metadata.get("ContainerName") if metadata else None
+                if target_name:
+                    for container_def in container_defs:
+                        if container_def.get("Name") == target_name:
+                            container_def["Image"] = path
+                            break
+                else:
+                    container_defs[0]["Image"] = path
+        if resource_type == AWS_BEDROCK_AGENTCORE_RUNTIME:
+            artifact = resource_properties.setdefault("AgentRuntimeArtifact", {})
+            container_config = artifact.setdefault("ContainerConfiguration", {})
+            container_config["ContainerUri"] = path
 
     def _build_lambda_image(self, function_name: str, metadata: Dict, architecture: str) -> str:
         """
@@ -538,6 +558,53 @@ def _load_lambda_image(self, image_archive_path: str) -> str:
         except (docker.errors.APIError, OSError, ContainerArchiveImageLoadFailedException) as ex:
             raise DockerBuildFailed(msg=str(ex)) from ex
 
+    def build_container_images(self, container_build_definitions: List[ContainerBuildDefinition]) -> Dict[str, str]:
+        """
+        Build container images for non-Lambda resources (ECS, AgentCore).
+
+        Parameters
+        ----------
+        container_build_definitions : List[ContainerBuildDefinition]
+            List of container build definitions to build
+
+        Returns
+        -------
+        Dict[str, str]
+            Map of resource identifier to the built image tag
+        """
+        artifacts: Dict[str, str] = {}
+        for container_def in container_build_definitions:
+            if not container_def.metadata:
+                continue
+            image_tag = self._build_container_image(
+                container_def.resource_identifier,
+                container_def.metadata,
+                container_def.architecture,
+            )
+            artifacts[container_def.resource_identifier] = image_tag
+        return artifacts
+
+    def _build_container_image(self, resource_name: str, metadata: Dict, architecture: str) -> str:
+        """
+        Build a container image for an ECS/AgentCore resource. Uses the same Metadata
+        convention as Lambda Image builds (Dockerfile, DockerContext, DockerBuildArgs, etc.)
+
+        Parameters
+        ----------
+        resource_name : str
+            Logical ID or identifier of the resource
+        metadata : dict
+            Metadata block from the resource
+        architecture : str
+            Target architecture
+
+        Returns
+        -------
+        str
+            The full tag of the built image
+        """
+        return self._build_lambda_image(resource_name, metadata, architecture)
+
     def _build_layer(
         self,
         layer_name: str,

samcli/lib/build/build_graph.py

@@ -200,12 +200,14 @@ class BuildGraph:
     # global table build definitions key
     FUNCTION_BUILD_DEFINITIONS = "function_build_definitions"
     LAYER_BUILD_DEFINITIONS = "layer_build_definitions"
+    CONTAINER_BUILD_DEFINITIONS = "container_build_definitions"
 
     def __init__(self, build_dir: str) -> None:
         # put build.toml file inside .aws-sam folder
         self._filepath = Path(build_dir).parent.joinpath(DEFAULT_BUILD_GRAPH_FILE_NAME)
         self._function_build_definitions: List["FunctionBuildDefinition"] = []
         self._layer_build_definitions: List["LayerBuildDefinition"] = []
+        self._container_build_definitions: List["ContainerBuildDefinition"] = []
         self._atomic_read()
 
     def get_function_build_definitions(self) -> Tuple["FunctionBuildDefinition", ...]:
@@ -214,6 +216,22 @@ def get_function_build_definitions(self) -> Tuple["FunctionBuildDefinition", ...
     def get_layer_build_definitions(self) -> Tuple["LayerBuildDefinition", ...]:
         return tuple(self._layer_build_definitions)
 
+    def get_container_build_definitions(self) -> Tuple["ContainerBuildDefinition", ...]:
+        return tuple(self._container_build_definitions)
+
+    def put_container_build_definition(self, container_build_definition: "ContainerBuildDefinition") -> None:
+        """
+        Puts the newly read container build definition into existing build graph.
+        Each container build definition is unique per resource identifier.
+        """
+        if container_build_definition not in self._container_build_definitions:
+            LOG.debug(
+                "Adding container build definition: %s",
+                container_build_definition,
+            )
+            self._container_build_definitions.append(container_build_definition)
+
+
     def get_function_build_definition_with_full_path(
         self, function_full_path: str
     ) -> Optional["FunctionBuildDefinition"]:
@@ -701,3 +719,67 @@ def __eq__(self, other: Any) -> bool:
             and self.env_vars == other.env_vars
             and self.architecture == other.architecture
         )
+
+
+class ContainerBuildDefinition(AbstractBuildDefinition):
+    """
+    ContainerBuildDefinition holds information about each unique container image build
+    for non-Lambda resources (ECS TaskDefinitions, AgentCore, etc.)
+    """
+
+    def __init__(
+        self,
+        resource_identifier: str,
+        resource_type: str,
+        metadata: Optional[Dict],
+        source_hash: str = "",
+        manifest_hash: str = "",
+        env_vars: Optional[Dict] = None,
+        architecture: str = X86_64,
+    ) -> None:
+        # Allow metadata to override architecture (e.g., "arm64" for AgentCore)
+        if metadata and metadata.get("Architecture"):
+            architecture = metadata["Architecture"]
+        super().__init__(source_hash, manifest_hash, env_vars, architecture)
+        self.resource_identifier = resource_identifier
+        self.resource_type = resource_type
+
+        metadata_copied = deepcopy(metadata) if metadata else {}
+        metadata_copied.pop(SAM_RESOURCE_ID_KEY, "")
+        metadata_copied.pop(SAM_IS_NORMALIZED, "")
+        self.metadata = metadata_copied
+
+    @property
+    def dockerfile(self) -> Optional[str]:
+        return self.metadata.get("Dockerfile") if self.metadata else None
+
+    @property
+    def docker_context(self) -> Optional[str]:
+        return self.metadata.get("DockerContext") if self.metadata else None
+
+    @property
+    def docker_build_args(self) -> Dict:
+        return self.metadata.get("DockerBuildArgs", {}) if self.metadata else {}
+
+    @property
+    def docker_build_target(self) -> Optional[str]:
+        return self.metadata.get("DockerBuildTarget") if self.metadata else None
+
+    def get_resource_full_paths(self) -> str:
+        return self.resource_identifier
+
+    def __str__(self) -> str:
+        return (
+            f"ContainerBuildDefinition({self.resource_identifier}, {self.resource_type}, "
+            f"{self.source_hash}, {self.uuid}, {self.metadata}, {self.architecture})"
+        )
+
+    def __eq__(self, other: Any) -> bool:
+        if not isinstance(other, ContainerBuildDefinition):
+            return False
+        return (
+            self.resource_identifier == other.resource_identifier
+            and self.resource_type == other.resource_type
+            and self.metadata == other.metadata
+            and self.architecture == other.architecture
+        )