Parameter Store reference

A parameter is any piece of data stored in Parameter Store, such as a block of text, a list of names, an AMI ID, a merchant ID, or another configuration value. You can centrally reference this data in your scripts, commands, and SSM documents.

When you reference a parameter, you specify the parameter name using the following convention.

{{ssm:parameter-name}}

Parameter Store provides support for three types of parameters: String, StringList, and SecureString.

With one exception, when you create or update a parameter, you enter the parameter value as plaintext, and Parameter Store performs no validation on the text you enter. For String parameters, however, you can specify the data type as aws:ec2:image, and Parameter Store validates that the value you enter is the proper format for an Amazon EC2 AMI; for example: ami-12345abcdeEXAMPLE.

Parameter type: String

By default, the value of a String parameter consists of any block of text you enter. For example:

Parameter type: StringList

The values of StringList parameters contain a comma-separated list of values, as shown in the following examples.

Monday,Wednesday,Friday

CSV,TSV,CLF,ELF,JSON

Parameter type: SecureString

Use SecureString for configuration values that require encryption, such as service endpoints and account identifiers. For secrets such as database credentials, API keys, or tokens, we recommend AWS Secrets Manager, which provides purpose built security controls including automatic rotation and cross-region replication.

Only the parameter value is encrypted. The parameter name, description, and other metadata aren't encrypted.

Parameter Store encrypts and decrypts SecureString parameter values using an AWS KMS key. You can use the default AWS managed key for Parameter Store or a customer managed key. Use a customer managed key when you need to restrict which principals can decrypt particular parameters. For more information, see Encrypting and decrypting parameters using AWS KMS keys.

You can use SecureString parameters with other AWS services. The following Lambda function retrieves an encrypted merchant ID from the /myapp/dev/vendor/merchant-id parameter. The function uses the value without writing it to the function logs or returning it in the response.

import json
import boto3

ssm = boto3.client("ssm", region_name="us-east-1")

def lambda_handler(event, context):
    response = ssm.get_parameter(
        Name="/myapp/dev/vendor/merchant-id",
        WithDecryption=True
    )

    merchant_id = response["Parameter"]["Value"]

    # Use merchant_id when communicating with the vendor system.
    # Don't write the value to logs or include it in the response.

    return {
        "statusCode": 200,
        "body": json.dumps("Vendor configuration retrieved.")
    }

AWS KMS encryption and pricing

When you create a SecureString parameter, Systems Manager uses AWS KMS to encrypt the parameter value.

There is no charge from Parameter Store to create a SecureString parameter, but charges for using AWS KMS can apply. For more information, see AWS Key Management Service pricing.

For more information about AWS managed keys and customer managed keys, see AWS Key Management Service Concepts in the AWS Key Management Service Developer Guide. For more information about how Parameter Store uses AWS KMS, see How AWS Systems Manager Parameter Store uses AWS KMS.

aws kms describe-key \
    --region us-east-1 \
    --key-id alias/aws/ssm

Parameter name constraints

Use the information in this topic to help you specify valid values for parameter names when you create a parameter.

This information supplements the details in the topic PutParameter in the AWS Systems Manager API Reference, which also provides information about the values AllowedPattern, Description, KeyId, Overwrite, Type, and Value.

The requirements and constraints for parameter names include the following: