sam local start-api detached mode

[frob]

Describe your idea/feature/enhancement

Allow sam local start-api to run detached

Proposal

While SAM is great for local development it can fall short for CI or even test commands. In order to run tests automatically against my api-gateway I need to run sam local start-api this command continues running until I press Ctrl-C. This works well for local development but I would like to script this out into a CI that will allow me to run integration tests without deploying to aws.

Things to consider:

1. Will this require any updates to the SAM Spec

   • No, as far as I know, this should require any updates to the spec.

2. Additional arguments/commands

   • By adding a detached mode that also means there must be a non-interrupt way to stop the api. I suggest sam local stop-api as a way to stop the api. This command would be dependent on the directory and template that is running and thus the running instance would be a singleton.
   • I would suggest -d as this would follow the docker command scheme and be more familiar to developers.

[ndobryanskyy]

Proposed feature is really handy, I like it, but there are some open questions and to me, this flag seems to be not that simple.

• As I understood, user would be able to start only single local api-gateway? And stop-api will work from any directory to enable the user to easily stop the service? Or should one be able to start several api-gateways for different templates?
• SAM should also include the command to attach to the running local api-gateway to examine logs -> which leads us to the fact, that all of the logs should be aggregated somewhere, so the user could examine the recent logs upon attaching.
• -d flag name is already taken by the --debugger-port option as a shorthand name, so this should be more verbose like --detached or something;

Does that make sense, @frob?

[frob]

Yes that is what I am referring to.

As I understood, user would be able to start only single local api-gateway? And stop-api will work from any directory to enable the user to easily stop the service? Or should one be able to start several api-gateways for different templates?

Does SAM CLI currently work with multiple templates? I was thinking of single endpoints, but I could see it being useful for multiple. The purpose for this is for integration testing so as many endpoints as needed for the test and I can see an argument for multiple endpoints being required for a full integration test. Honestly, it is usually these features work better if they start small and then we can add features in another issue.

SAM should also include the command to attach to the running local api-gateway to examine logs -> which leads us to the fact, that all of the logs should be aggregated somewhere, so the user could examine the recent logs upon attaching .

I am unclear about this. I kind of think that logging would just follow the current workflow for docker.

-d flag name is already taken by the --debugger-port option as a shorthand name, so this should be more verbose like --detached or something;

Good point. Docker run docs use --detach and I suggest we use that.

Any updates on this?

[mmartsen]

Can it be just "dockerized"? So instead of running "sam local start-api" we run "docker-compose up"?
To me it seems doable to generate docker-compose.yml after "sam build" command with all necessary folders mapped. I think majority of CI/CD tools could work with docker-compose, also things like logging, attach/detach are already solved there.

[Santiago8888]

The second time I run into this issue, current use cases:

1. Test lambdas on CI/CD envs. without deploying them.
2. Lift multiple API Gateways without opening multiple terminals.

[jonowhite]

I think this would be really helpful. I have similar use cases, my current method I am testing (which might be a little dodgy) is to send the sam command to the background and redirect all logs to prevent interference.

sam local start-api  > /dev/null 2>&1 &

This keeps the local API active while retaining control of the shell. So you could run it multiple times, or re-use the shell to run tests against the local API.

Potential issue when it comes to stopping the background processes if you have multiple running and need to be careful with which you kill.

[tahoward]

Running into a similar situation. Using this in a Makefile in interim:

start:
	sam local start-api --docker-network <network_name> --warm-containers EAGER &

stop:
	kill $$(ps -wwo pid,args | grep "[/]bin/sam local start-api" | awk '{print $$1}')
	CONTAINERS=$$(docker network inspect <network_name> | jq -r '.[].Containers[].Name')
	echo "$$CONTAINERS" | xargs docker stop; echo "$$CONTAINERS" | xargs docker rm

sam local start-api --docker-network <network_name> is used to track any containers spawned by sam. It appears to orphan them when using --warm-containers and PID gets killed.

[dschiavu]

+1

Would love to see this command being implemented.

[matthew-heyner]

+1

This would be helpful.