The Wrong Way to Handle SSM Parameters in the Serverless Framework

I recently started playing with the Serverless framework to work with AWS Lambda functions. While exploring the framework's features and enjoying the CLI commands provided to create, test, and deploy my lambda functions, I came across an issue with using SSM parameters. The existing documentation mentioned a specific syntax, but I encountered an error when implementing it. After some research, I discovered the correct solution. Let me share the details with you.

Tl;dr jump to the solution to see the correct way to use SSM parameters in the serverless.yml configuration.

Using the Parameters as per the documentation

The existing documentation for serverless framework secret management mentions the usage of the AWS SSM parameter as shown in the snippet below with the following explanation

 ${ssm:/secret-api-key~true}

Explanation:

We add ~true to the end of the key reference. This way, the Serverless Framework fetches the parameter from SSM, decrypts it, and places the decrypted value into an environment variable for us to use

here is a sample snippet of how I applied it in my configuration file

functions:
  api:
    handler: index.handler
    environment:
        OTEL_EXPORTER_OTLP_HEADERS: ${ssm:/nr_ingest_key~true}
        OTEL_SERVICE_NAME: otel-lambda-sls-otel-example

The Issue

While the above-documented way worked fine when testing the function offline with sls offline , it kept failing with the following error on running the sls deploy with the error message below

Error:

Cannot resolve serverless.yml: Variables resolution errored with:

• Cannot resolve variable at "functions.api.environment.OTEL_EXPORTER_OTLP_HEADERS": Parameter name: can't be prefixed with "ssm" (case-insensitive). If formed as a path, it can consist of sub-paths divided by a slash symbol; each sub-path can be formed as a mix of letters, numbers and the following 3 symbols .-_

After using my exceptional Googling skills, I found a GitHub issue on the serverless repository that had the exact same error. (Tip: check for open or closed issues if the documentation doesn't help)

Here is a preview of the issue:

Going through each of the comments from the discussion on this issue helped me finally figure out the solution.

The Solution

The syntax was updated and the support for ~true or ~false was dropped.

The correct way to refer to the SSM parameters in your serverless.yml configuration now is without the ~ tilde (/ˈtɪldə,ˈtɪldi/).

Here is an updated snippet from my working configuration file.

functions:
  api:
    handler: index.handler
    environment:
        OTEL_EXPORTER_OTLP_HEADERS: ${ssm:/nr_ingest_key}
        OTEL_SERVICE_NAME: otel-lambda-sls-otel-example

Additionally, If you want to construct the value for a specific use-case, such as HTTP Headers, you can enclose the value, along with the string, in single quotes. Check out the sample below.

    environment:
        OTEL_EXPORTER_OTLP_HEADERS: 'api-key=${ssm:/nr_ingest_key}'

Happy Coding! 🚀