Support passing arbitrary options to underlying Docker commands
- 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
Assessment
This issue has not been assessed yet.