aws / aws/aws-sam-cli

Support passing arbitrary options to underlying Docker commands

Open
#3,453 7 comments 8 reactions 0 assignees View on GitHub
area/local/invoke area/local/start-api area/local/start-lambda maintainer/need-followup stage/pm-review type/feature
Dominant language
Python
Stars
6.7k
Forks
1.2k
Avg merge
1d 10h
Merged PRs (30d)
52

Description

### Describe your idea/feature/enhancement

I wish SAM CLI would support passing arbitrary arguments to the underlying Docker commands, primarily from `sam build` to `docker build` and from `sam local ...` to `docker run`. SAM CLI already has pretty great support for passing _environment_ info to the underlying Docker commands, via `--container-env-var`, `--container-env-var-file`, `--config-env`, `--env-vars`, and the like. However, there are instances where developers need to tweak the networking (e.g., for dev containers, which I believe led to `sam local ...`'s `--container-host` option), [volumes](https://github.com/aws/aws-sam-cli/issues/1896) (for local testing), and other properties of the underlying Docker containers. I feel like the most forward-compatible solution would just be to let developers pass arbitrary arguments to Docker, sort of like the `--docker-arg` option in the Serverless Framework's [`invoke local` command](https://www.serverless.com/framework/docs/providers/aws/cli-reference/invoke-local#options).

### Proposal

I think this could be similar to how options are [passed to npm scripts](https://docs.npmjs.com/cli/v7/commands/npm-run-script). Essentially, `sam build`, `sam local ...`, and other commands that talk to Docker would use `--` to "escape" options that should be passed directly to Docker and not parsed by SAM CLI. For example:

```sh
sam local start-api --port 3001 -- --mount 'type=volume,src=,dst='
```

In this example:
- The `--port` option is parsed by SAM CLI
- The `--mount` option and its argument are passed directly to Docker.

This is actually the use case that I've been trying to get working, as I want to test my functions locally by having them write to a shared volume on my localhost, rather than S3 (currently, I have to use [David Gray's hack](https://github.com/dacgray/sam-local-start-api-container-image-volume-mount) to make this work).

Alternatively, SAM CLI could take a `--docker-arg` option like Serverless Framework's [`invoke local` command](https://www.serverless.com/framework/docs/providers/aws/cli-reference/invoke-local#options), where the Docker options become arguments to _that_ option:

```sh
sam local start-api --port 3001 --docker-arg '-v /var:/host_var'
```

This would make it a little easier for developers coming from Serverless Framework, and arguably make the serverless computing ecosystem more uniform...though I personally like the brevity of `--` better.

Things to consider:

I don't think this will require any updates to the [SAM Spec](https://github.com/awslabs/serverless-application-model)

SAM CLI could continue to have feature-specific flags/options like `--docker-network` and `--container-host`, both for backwards compatibility, and to make common scenarios more "first class citizens" of the CLI. But these would ultimately become just shorthands for the general option I think.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.