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

Note that this is the path within the container, not the path on the customers machine (but we create a docker "volume" to make it persistent). Maybe you could leave a comment explaining that?

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.

humm, which part set this envvar, I might have missed that

https://github.com/SilanHe/aws-sam-cli/blob/2a2469c6c113e1ab7f0f93e0cb26a040782828a2/samcli/local/docker/durable_functions_emulator_container.py#L256

https://github.com/SilanHe/aws-sam-cli/blob/2a2469c6c113e1ab7f0f93e0cb26a040782828a2/samcli/local/docker/durable_functions_emulator_container.py#L181

https://github.com/SilanHe/aws-sam-cli/blob/2a2469c6c113e1ab7f0f93e0cb26a040782828a2/samcli/local/docker/durable_functions_emulator_container.py#L85

https://github.com/SilanHe/aws-sam-cli/blob/2a2469c6c113e1ab7f0f93e0cb26a040782828a2/samcli/local/docker/durable_functions_emulator_container.py#L135

I guess technically, the code doesn't dynamically detect if 9014 is currently used since it's the default but we have the ability to set it to something else.

Yeah that's what I mean, probably we should consider the dynamic assign. Currently in the tests if I run 2 DAR test in parallel it would fail for port in use.

This port is static intentionally because of the order in which the containers are created.

When we create an instance of the DurableLambdaContainer class, we have to tell the lambda container what port the emulator is listening on (by setting the AWS_ENDPOINT_URL_LAMBDA in the container environment to the emulator port first), then we start (or attach) the emulator. Since the lambda container port itself is set dynamically, we pass it through to the emulator as part of the execution payload and the emulator keeps track of it (this is also how we support concurrent executions).

However, if the emulator port was set dynamically, we'd have to update the lambda runtime container environment after the lambda container is created, which isn't possible.

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?

I think that is a good idea however due to time constraints I won't have any more capacity to work on this for a while so I'd be happy to have this as a follow up item. I'm guessing I'll have to confer with SAM CLI team for the name of the parameter, updating the docs, etc.

I don't think having it as an environment variable makes it substantially harder to use in the meantime.

Personally I don't think this should be exposed as a new parameter on the CLI. Our expectation is for the latest image to always be "stable", so it should only be overridden in unexpected cases. The way I see this, having this be overridable at all is like a backdoor, and we shouldn't expect customers to need to use this.

Do you agree?

…ing format strings

SilanHe · 2026-03-02T20:14:09Z

I ran integration tests locally

SAM_CLI_DEV=1 pytest tests/integration/local/invoke/test_invoke_durable.py::TestInvokeDurable -vv -s && SAM_CLI_DEV=1 pytest tests/integration/local/start_lambda/test_start_lambda_durable.py::TestStartLambdaDurable -vv -s && SAM_CLI_DEV=1 pytest tests/integration/local/start_api/test_start_api_durable.py::TestStartApiDurable -vv -s

and they all passed

valerena

LGTM. Waiting for the final official image location.

bchampp

Nice - I much prefer this approach, 1 blocking comment about the --lambda-endpoint and two minor suggestions.

bchampp · 2026-03-05T22:05:47Z

samcli/local/docker/durable_functions_emulator_container.py

+                "--lambda-endpoint",
+                "http://host.docker.internal:3001",


This needs to be removed. We pass in the lambda endpoint dynamically as part of the payload to starting the execution. I think the emulator is already be falling back on 3001 (this is the sam local start-lambda port), but having this here is misleading since it's not actually used for the interactions between the emulator and lambda container.

bchampp · 2026-03-05T22:06:56Z

samcli/local/docker/durable_functions_emulator_container.py

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


Note that this is the path within the container, not the path on the customers machine (but we create a docker "volume" to make it persistent). Maybe you could leave a comment explaining that?

bchampp · 2026-03-05T22:08:50Z

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. "
+            f"Check https://${self._get_emulator_image().replace('public.ecr', 'gallery.ecr')}. "
+            "and https://github.com/aws/aws-durable-execution-sdk-python-testing/releases "
+            "for valid image tags. If the problems persist, you can try updating the SAM CLI version "
+            " in case of incompatibility."


If the emulator itself doesn't become ready, it likely indicates a problem with the emulator server. We have an environment variable that will capture the emulator logs and persist them: https://github.com/aws/aws-sam-cli/blob/develop/samcli/local/docker/durable_functions_emulator_container.py#L63

I wonder if we should add instructions on how to use this here?

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 3 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

chore: ran make pr + cut down on redundant environment variables

384b9fb

SilanHe requested review from roger-zhangg and valerena March 2, 2026 17:41

valerena reviewed Mar 3, 2026

View reviewed changes

bchampp suggested changes Mar 5, 2026

View reviewed changes

		"--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!

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!

SilanHe commented Mar 2, 2026

Uh oh!

valerena left a comment

Choose a reason for hiding this comment

Uh oh!

bchampp left a comment

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

SilanHe commented Feb 26, 2026 •

edited

Loading

SilanHe Feb 27, 2026 •

edited

Loading