How do I specify template parameters when running AWS SAM Local?

Question

Using AWS SAM Local I can test my serverless application locally, which is awesome.

I can also deploy to AWS, which apparently takes the same flags as aws cloudformation deploy, so I can pass a parameters file with e.g. application secrets (API keys and such).

However, I can't find anything in aws local start-api --help or in the docs on Github about how to use a parameter file when testing locally.

How do I point to a parameters file to use with my template when running sam local start-api?

I'm not sure this is possible on some versions of the SAM CLI. I've tried the above answer, but it doesn't seem to work with my version of the SAM CLI. I get `Error: no such option: --parameter-values`. `sam --version` yields 4.0. It also doesn't appear to be listed in the options for `sam local start-api --help` (`sam local start-api --help | grep -i parameter-values` yields nothing). — curiouscat, Jul 08 '18 at 17:33
I cant believe there isn't an option already to pass the name of a cloud formation parameter file to the cloud formation stage of the sam deploy. This would be so useful. — developer, Jul 07 '23 at 08:47
The feature request for `sam deploy` has been open for a few years - https://github.com/aws/aws-sam-cli/issues/2054 - if it ever gets done it will be here. Also contains some other workarounds people are using. — mijiturka, Jul 13 '23 at 14:53

score 42 · Answer 1 · edited Oct 20 '19 at 13:39

42

You can use the --parameter-overrides switch. The syntax is quite long winded, as below:

sam local start-api --parameter-overrides ParameterKey=Key1,ParameterValue=value1 ParameterKey=Key2,ParameterValue=value2

That is, you need to specify the key and value of each pair with comma separation.

And then each pair is separated with a space.

From sam local start-api --help:

  --parameter-overrides       Optional. A string that contains
                              CloudFormation parameter overrides encoded
                              as key=value pairs. Use the same format as
                              the AWS CLI, e.g. 'ParameterKey=KeyPairName,
                              ParameterValue=MyKey ParameterKey=InstanceTy
                              pe,ParameterValue=t1.micro'

edited Oct 20 '19 at 13:39

Frank R.

1,732
18
21

answered Mar 16 '18 at 00:42

kichik

33,220
7
94
114

1

Yes, I noticed that in the help too. However, the question was specifically on how to pass a *file path* to a *file* with the parameter values, as you can do with `aws cloudformation deploy`, but I can't find how, or if, you can with `sam local start-api`. – Tomas Aschan Mar 16 '18 at 09:39
2

Doesn't look like that one is supported. You can try using the shell for that with `--parameter-values $(cat myparams.cfg)`. The file will need to have a different format than usual, but it should work. – kichik Mar 16 '18 at 15:41
2

`sam local start-api --help` now also correctly states `--parameter-overrides` – sgdesmet Oct 23 '18 at 15:36
is it possible to use `--parameter-override` from a file? I would like to keep my env parameters separate from my script – Matteo Aug 21 '19 at 01:26
@Madeo it sounds like you might use a script for something like this. User input from the command line to select a number of options, which then runs the build/package/deploy sequence after the user has input their options. – andrewec Dec 23 '19 at 22:24
How to refer to some deeply nested parameter in this option? E.g. Function -> Event -> Properties -> Path – Enbugger Sep 28 '20 at 02:15

score 6 · Answer 2 · answered Aug 21 '19 at 08:50

You can use the --parameter-overrides in sam deploy just like in aws cloudformation deploy with a small change:

Before:

sam deploy --template-file packaged.yaml --stack-name example-lambda --capabilities CAPABILITY_IAM --parameter-overrides ParameterKey=SourceS3Bucket ParameterValue=test-data-111

After:

sam deploy --template-file packaged.yaml --stack-name example-lambda --capabilities CAPABILITY_IAM --parameter-overrides SourceS3Bucket=test-data-111

Noticeable change: ParameterKey, ParameterValue does not need to be explicitly specified in sam deploy. Helps me in local testing.

Hope it helps. :)

is it possible to use `--parameters-overrides` as a .json file? — Matteo, Aug 25 '19 at 06:21

score 4 · Answer 3 · answered Oct 23 '18 at 15:32

It seems you can also use the -n or --env-vars parameter to pass environment variables in a JSON file to your functions. See the docs: Test Your Serverless Applications Locally Using SAM CLI (Public Beta)

In short, your JSON file would look like (example copied from documentation):

{
  "MyFunction1": {
    "TABLE_NAME": "localtable",
    "BUCKET_NAME": "testBucket"
  },
  "MyFunction2": {
    "TABLE_NAME": "localtable",
    "STAGE": "dev"
  },
}

And then you can do:

 $ sam local start-api --env-vars env.json

This is specifically for environment variables for your lambda functions though, so it may not be entirely what you're after?

No; while useful, this doesn't solve the problem. For example, I can't use this approach to parametrize the name of a dynamodb table or things like that. — Tomas Aschan, Oct 23 '18 at 18:14

score 1 · Answer 4 · answered Mar 14 '20 at 10:26

My strange experience was that it depends on an order of the parameters. I had two parameters - SecretKey and DatabaseUri pointing to a Mongo instance. When I had the DatabaseUri first, the SecretKey was not loaded and the build failed upon a missing parameter SecretKey. When I was really desperate I swapped the parameters having the SecretKey first and it started to work!

How do I specify template parameters when running AWS SAM Local?

4 Answers4

Linked