Feat/use durable functions emulator image by SilanHe · Pull Request #8708 · aws/aws-sam-cli

SilanHe · 2026-02-26T23:01:39Z

Which issue(s) does this change fix?

Why is this change necessary?

This introduces a fix for the Homebrew linkage issue with the Durable Functions emulator. We are also introducing this so that SAM CLI can receive Durable Functions emulator updates uncoupled with SAM CLI release.

How does it address the issue?

We are automatically vending the emulator via an image published to ECR. See aws/aws-durable-execution-sdk-python-testing#196. Since the arm64 emulator is no longer included as an executable directly in the SAM CLI, this also fixed the issue where Homebrew users of SAM CLI could not emulate durable functions locally without doing some workaround.

What side effects does this change have?

As a bonus, this reduces the SAM CLI size.

Mandatory Checklist

PRs will only be reviewed after checklist is complete

Review the generative AI contribution guidelines
Add input/output type hints to new functions/methods
Write design document if needed (Do I need to write a design document?)
Write/update unit tests
[n/a] Write/update integration tests
[n/a] Write/update functional tests if needed
make pr passes
make update-reproducible-reqs if dependencies were changed
[n/a] Write documentation

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

…tead of building image using binary

…mage

# Conflicts: # samcli/local/docker/durable_functions_emulator_container.py

… fails to start up

valerena · 2026-02-27T19:25:46Z

samcli/local/docker/durable_functions_emulator_container.py

+            f"Durable Functions Emulator container failed to become ready within {timeout} seconds. "
+            "You may set the DURABLE_EXECUTIONS_EMULATOR_IMAGE_TAG env variable to a specific image "
+            "to ensure that you are using a compatible version. "
+            "Check https://gallery.ecr.aws/o4w4w0v6/aws-durable-execution-emulator. "


minor, but can you use self._get_emulator_image() here too?

maybe

f"Check https://${self._get_emulator_image().replace('public.ecr', 'gallery.ecr')}. "

?

or have another method that uses the same variables? Basically so if we change the location of the image, we have a consistent messaging too

ah yeah, I can definitely do that

valerena · 2026-02-27T19:31:11Z

samcli/local/docker/durable_functions_emulator_container.py

+                "--store-path",
+                "/tmp/.durable-executions-local/durable-executions.db",


I don't see this being used before. Is this a new thing needed?

Similar question about the other properties --log-level, --lambda-endpoint..

yeah we removed a "layer" to the emulator, these were previously being set by default but not transparently to the SAM CLI code

valerena · 2026-02-27T19:34:12Z

samcli/local/docker/durable_functions_emulator_container.py

+                "--store-type",
+                self._get_emulator_store_type(),


In line 187 this is already added to the environment variables, so we probably don't need to add it here again.

"EXECUTION_STORE_TYPE": self._get_emulator_store_type(),

ah, EXECUTION_STORE_TYPE is part of the emulator "layer" that was removed. So it's not being used anymore. I can remove it from the environment variables.

conversely, I can also use the "new" environment variables instead:

https://github.com/aws/aws-durable-execution-sdk-python-testing/blob/5e184cbac9ea9968d71bce1a7995635ac99f8ff0/src/aws_durable_execution_sdk_python_testing/cli.py#L67

Ah. I see. I think both alternatives work, as long as it's clear. I think it makes sense to keep it here and remove it from the env vars.

"HOST": "0.0.0.0", # ❌ UNUSED - hardcoded, passed via --host "PORT": str(self.port), # ❌ UNUSED - passed via --port (command wins) "LOG_LEVEL": "DEBUG", # ❌ UNUSED - hardcoded, passed via --log-level "EXECUTION_STORE_TYPE": self._get_emulator_store_type(), # ❌ UNUSED - passed via --store-type (command wins) "EXECUTION_TIME_SCALE": self._get_emulator_time_scale(), # ❌ UNUSED - not even a CLI arg!

so only

self.port - Can be overridden by user
self._get_emulator_store_type() - Can be overridden by user

so maybe:

command=[ "dex-local-runner", "start-server", "--host", "0.0.0.0", "--port", str(self.port), "--log-level", "DEBUG", "--lambda-endpoint", "http://host.docker.internal:3001", "--store-type", self._get_emulator_store_type(), "--store-path", "/tmp/.durable-executions-local/durable-executions.db", ], environment={ "AWS_ACCESS_KEY_ID": "foo", "AWS_SECRET_ACCESS_KEY": "bar", "AWS_DEFAULT_REGION": "us-east-1", }

roger-zhangg · 2026-02-27T21:15:12Z

samcli/local/docker/durable_functions_emulator_container.py

+                "start-server",
+                "--host",
+                "0.0.0.0",
+                "--port",


I guess not related to this PR, but do we have plan to assign this port dynamically. Currently it would just use 9014 no matter it's taken or not

oh really, I thought the code already dynamically assigned the port according to the env variable.

roger-zhangg · 2026-02-27T21:17:23Z

samcli/local/docker/durable_functions_emulator_container.py

    _RAPID_SOURCE_PATH = Path(__file__).parent.joinpath("..", "rapid").resolve()
-    _EMULATOR_IMAGE = "public.ecr.aws/ubuntu/ubuntu:24.04"
-    _EMULATOR_IMAGE_PREFIX = "samcli/durable-execution-emulator"
+    _EMULATOR_IMAGE = "public.ecr.aws/o4w4w0v6/aws-durable-execution-emulator:"


This is not the final URL right

bchampp · 2026-02-27T22:08:18Z

samcli/local/docker/durable_functions_emulator_container.py

    _RAPID_SOURCE_PATH = Path(__file__).parent.joinpath("..", "rapid").resolve()
-    _EMULATOR_IMAGE = "public.ecr.aws/ubuntu/ubuntu:24.04"
-    _EMULATOR_IMAGE_PREFIX = "samcli/durable-execution-emulator"
+    _EMULATOR_IMAGE = "public.ecr.aws/o4w4w0v6/aws-durable-execution-emulator:"


nit (since it needs a tag - and concatenate the : when we combine them):

Suggested change

_EMULATOR_IMAGE = "public.ecr.aws/o4w4w0v6/aws-durable-execution-emulator:"

_EMULATOR_IMAGE_PREFIX = "public.ecr.aws/o4w4w0v6/aws-durable-execution-emulator"

bchampp · 2026-02-27T22:08:57Z

samcli/local/docker/durable_functions_emulator_container.py

+
+    def _get_emulator_image(self):
+        """Get the full emulator image name with tag."""
+        return self._EMULATOR_IMAGE + self._get_emulator_image_tag()


Suggested change

return self._EMULATOR_IMAGE + self._get_emulator_image_tag()

return f'{self._EMULATOR_IMAGE}:{self._get_emulator_image_tag()}'

ahh yeah this would be better, thanks

yaythomas · 2026-02-27T23:13:22Z

samcli/local/docker/durable_functions_emulator_container.py

+    """
+    Allow pinning to a specific emulator image tag/version
+    """
+    ENV_EMULATOR_IMAGE_TAG = "DURABLE_EXECUTIONS_EMULATOR_IMAGE_TAG"


sam local invoke has a --invoke-image parameter, where customers can pass the location of a specific image to be used as the execution base image instead of the default Lambda base image.

https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-local-invoke.html#ref-sam-cli-local-invoke-options-invoke-image

could explore using this established pattern rather than adding ENV_EMULATOR_IMAGE_TAG?

…ing format strings

hsilan and others added 2 commits February 19, 2026 14:54

feat: aws-durable-execution-emulator uses prebuilt image from ECR ins…

7eca282

…tead of building image using binary

Merge branch 'aws:develop' into feat/use-durable-functions-emulator-i…

35f322c

…mage

github-actions bot added area/local/start-api sam local start-api command area/local/invoke sam local invoke command area/local/start-invoke pr/external stage/needs-triage Automatically applied to new issues and PRs, indicating they haven't been looked at. labels Feb 26, 2026

hsilan and others added 6 commits February 26, 2026 15:11

chore: attempt using new image vended from python testing library

58d4e91

# Conflicts: # samcli/local/docker/durable_functions_emulator_container.py

chore: update error message when Durable Functions Emulator container…

a0045a0

… fails to start up

feat: use new image with emulator built in

ea7a340

chore: lint

1430958

chore: make pr

9452dab

Merge branch 'develop' into feat/use-durable-functions-emulator-image

2a2469c

valerena reviewed Feb 27, 2026

View reviewed changes

roger-zhangg reviewed Feb 27, 2026

View reviewed changes

bchampp reviewed Feb 27, 2026

View reviewed changes

yaythomas reviewed Feb 27, 2026

View reviewed changes

hsilan and others added 2 commits February 27, 2026 15:14

chore: update env variables, address nits about reusing functions, us…

681ae2d

…ing format strings

Merge branch 'develop' into feat/use-durable-functions-emulator-image

3b0f0c9

		"--store-path",
		"/tmp/.durable-executions-local/durable-executions.db",

	_EMULATOR_IMAGE = "public.ecr.aws/o4w4w0v6/aws-durable-execution-emulator:"
	_EMULATOR_IMAGE_PREFIX = "public.ecr.aws/o4w4w0v6/aws-durable-execution-emulator"

	return self._EMULATOR_IMAGE + self._get_emulator_image_tag()
	return f'{self._EMULATOR_IMAGE}:{self._get_emulator_image_tag()}'

Conversation

SilanHe commented Feb 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Which issue(s) does this change fix?

Why is this change necessary?

How does it address the issue?

What side effects does this change have?

Mandatory Checklist

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

SilanHe Feb 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

SilanHe commented Feb 26, 2026 •

edited

Loading

SilanHe Feb 27, 2026 •

edited

Loading