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 eg 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 ?

Answer 1

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'

Answer 2

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?

Answer 3

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. :)

Answer 4

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!