AWS Systems Manager Parameter Store (or SSM Parameter Store) is a convenient way to store hierarchical parameters in AWS. You can use it for any configuration values, including secure values like passwords or API keys. It integrates well with other AWS services too.

When it comes to reading parameters from SSM, there are a few available options.

• Read at runtime
• Read at build time
• Read at deploy time

When thinking about these options it's important to consider:

1. When can you be sure the parameter will be available?
2. Can the parameter value change?
3. Is the parameter a secret that should be protected from data leaks?

Reading at Runtime

Reading at runtime is the safest way to both protect a secret parameter and deal with parameters that might not be available at build or deploy time. It also helps to deal with parameters whose values change frequently. Parameters can be read using the AWS SDK for your language of choice(e.g., JS, Python) or the SSM API.

It's a good idea to think about how often you will make the call to read parameter values. Parameter Store has a low throughput quota by default (40 per second) and reading the value every time you need it will also add latency. The typical solution here is to load at startup time. For example, in the context of a Lambda function, the parameter read could be outside the handler function, executed when your code is bootstrapped.

If you are worried about keeping hold of stale values at runtime, you can re-read after a reasonable timeout. ssm-cache in Python and Middy SSM for Node.js Lambda functions are two of the open source libraries that make this easy.

The runtime reading approach keeps your secret parameters in memory only, so you can be reassured that, as long as you don't write these values anywhere else, the risk of exfiltrating secrets is lower than with using files or environment variables containing plaintext secrets.

Reading at build time

There is a subtle difference between this option and the next one (reading at deploy time). Let's assume that you are using Infrastructure as Code and you are packaging your code and infrastructure together at build time. This packaging process happens before you deploy to AWS.

Reading at build time uses the SDK or API to load a parameter value and include it somewhere in your code. This could be a generated .env file or a value set in a Lambda function environment variable.

With the Serverless Framework, this can look like the following:

functions:
  getItem:
    handler: handler.handleGetItem
    environment: ${ssm:/path/to/secret}

This is really convenient because the Serverless Framework takes care of retrieving the value with little code (docs). The downside comes with secret parameters. Storing a protected secret value in code or in an environment variable leaves it open to multiple types of attack.

The CloudFormation template for this example shows how the SSM parameter value is stored in JSON in the clear.

   "Environment": {
     "Variables": {
       "SECRET_CODE": "shhhhh!s3cr3t"
     }
   },

The environment variable can also be seen after we deploy in the Lambda function's configuration. Once it's available as an environment variable, it can easily be discovered and exfiltrated by any malicious code running in the function or actor with access to the function's configuration.

Reading at build time also requires you to ensure that your build environment has the right credentials to read the parameter and that it exists, even if you are only building without deploying.

Reading at Deploy Time

If you are using AWS CloudFormation, or any of the great tools built on top of it, like CDK, Serverless Framework or SAM, you have two options to load and use SSM Parameters at deploy time. This means that responsibility for reading the parameters is deferred until after you build and when CloudFormation performs cloud-side deployment of your full stack. The advantages are that you do not need privileges to read the parameters at build time and you don't have to ensure the values exist until it comes to deployment in any given environment.

The first option is using a special syntax for Cloudformation Parameters. In raw CloudFormation YAML, the declaration looks something like this:

resources:
  Parameters:
    UserPoolArnParameter:
      Type: AWS::SSM::Parameter::Value<String>
      Default: /dev/user-service/user-pool-arn

  Resources:
    CognitoAuthorizer:
      Type: AWS::ApiGateway::Authorizer
      Properties:
        ...
        ProviderARNs:
          - !Ref UserPoolArnParameter

A complete example is available here. This syntax does not support SecureString types. It is documented along with other CloudFormation Parameter types here.

The second deploy-time option in CloudFormation uses a feature called dynamic parameters and this option does support SecureString types for a fixed set of services. CloudFormation dynamic parameters also support specific parameter versions. It looks like the following.

{{resolve:ssm:/path/to/parameter:VERSION}}
or
{{resolve:ssm:/path/to/secure-parameter:VERSION}}

The :VERSION suffix is optional in both cases, with the latest version being automatically selected by default.

While these options may be more verbose than the Serverless Framework's ssm: variable syntax, CloudFormation syntax tends to be more stable, ensures deploy-time validation, and fits better with the cloud-side deployment model of CloudFormation stacks.

AWS CDK provides convenient functions for SSM parameters that dynamically generate either of these CloudFormation options for you. It might not be obvious that these are deploy-time lookups rather than at CDK build time, but you can check the synthesized CDK output to see what is happening under the hood.

Secrets Manager

The focus here is on SSM Parameter Parameters as opposed to Secrets Manager. The principles all apply but with Secrets Manager, you are more likely to be dealing with sensitive values that are rotated regularly so the emphasis on secure, late binding of secret values is event more important! CloudFormation dynamic values support Secrets Manager as well but there is no support in CloudFormation Parameters.

Conclusion

The rule of thumb for reading SSM parameters is generally, read them as late as possible. This reduces the likelihood of reading stale values and of having stored secrets that can be compromised. If you need to look up the value before running your code, try one of the CloudFormation methods. Reading at build time should be avoided where possible.