Systems Manager Parameter Store

Parameter Store currently has the following service limits:

Also note the following limitations:

Before you begin

Verify that your EC2 instances and on-premises servers or virtual machines meet Systems Manager prerequisites. For more information, see Systems Manager Prerequisites.

An Systems Manager parameter is a key-value pair that you create by specifying the following information.

After you create a parameter, you can specify it in your SSM documents, commands, or scripts using the following syntax:

{{ssm:parameter_name}}

The following is an example of an AWS CLI Run Command command using an SSM Parameter.

aws ssm send-command --instance-ids i-1a2b3c4d5e6f7g8 --document-name AWS-RunPowerShellScript --parameter '{"commands":["echo {{ssm:addUsers}}"]}'

 "runtimeConfig":{
        "aws:runShellScript":{
            "properties":[
                {
                    "id":"0.aws:runShellScript",
                    "runCommand":"{{ commands }}",
                    "workingDirectory":"{{ workingDirectory }}",
                    "timeoutSeconds":"{{ executionTimeout }}"

You can reference Systems Manager parameters in the Parameters section of an SSM document, as show in the following example.

{
   "schemaVersion":"2.0",
   "$schema":"http://amazonaws.com/schemas/ec2/v3-0/runcommand#",
   "description":"Sample version 2.0 document v2",
   "parameters":{
      "commands" : {
        "type": "StringList",
        "default": ["{{ssm:commands}}"]
      }
    },
    "mainSteps":[
       {
          "action":"aws:runShellScript",
          "name":"runShellScript",
          "inputs":{
             "commands": "{{commands}}"
          }
       }
    ]
}

Predefined SSM documents (all documents that begin with "AWS-") currently don't support Secure Strings or references to Secure String type parameters. This means that to use Secure String parameters with Run Command, you have to retrieve the parameter value before passing it to Run Command, as shown in the following example:

$value=aws ssm get-parameters --names secureparam --with-decryption

aws ssm send-command –name AWS-JoinDomain –parameters password=$value –instance-id instance_ID

A secure string is any sensitive data that needs to be stored and referenced in a secure manner. If you have data that you don't want users to alter or reference in clear text, such as domain join passwords or license keys, then specify those values using the Secure String data type. You should use secure strings when:

If you choose the Secure String data type when you create your parameter, then Systems Manager encrypts the parameter value when it is passed into a command and decrypts it when processing it on the managed instance. Encryption ensures that you can pass sensitive data such as passwords or license keys into commands or scripts without exposing the values in the command, agent logs, or other services such as AWS CloudTrail.

Encryption is handled by AWS KMS. Each AWS account is assigned a default AWS KMS key. You can view your key by executing the following command from the AWS CLI:

aws kms describe-key --key-id alias/aws/ssm

If you create a Secure String parameter using your own KMS key, then you don't have to provide a value for the Key ID parameter. The following CLI example shows the command to create a new Secure String parameter in Parameter Store without the --key-id parameter:

aws ssm put-parameter --name secure_string1_default_key --value "a_secure_string_value" --type SecureString

If you want to use a custom KMS key instead of the default key assinged to your account, then you must specify the ARN using the --key-id parameter, as shown in the following AWS CLI example:

aws ssm put-parameter --name secure_string1_custom_key --value "a_secure_string_value" --type SecureString --key-id arn:aws:kms:us-east-1:123456789012:key/1a2b3c4d-1a2b-1a2b-1a2b-1a2b3c4d5e

You can create a custom AWS KMS key from the AWS CLI by using the following command:

aws kms create-key

You can type an encrypted value for your parameter. In this case, because the string is already encrypted, you don’t have to choose the Secure String data type. If you do choose Secure String, your parameter will be doubly encrypted.

The Secure String data type is recognized by Systems Manager Run Command, which means you can define a parameter as a Secure String within the Parameters section of your Run Command SSM document. When you author your document, you set the type of the parameter to SecureString, as shown below. When returning the parameter values that were sent to a given command, the values for secure parameters will be an encrypted string. However, for existing AWS documents, not all parameters can be passed securely.

{
    "schemaVersion":"1.2",
    "description":"Run a PowerShell script or specify the paths to scripts to run.",
    "parameters":{
        "DNS":{
            "type":"SecureString",
            "description":"(Required) Specify the license key to be set on the instance."
    },
    "runtimeConfig":{
        "aws:runPowerShellScript":{
            "properties":[
                {
                    "id":"0.aws:runPowerShellScript",
                    "runCommand":"set-dns {{ license_key }}"
                }
            ]
        }
    }
}

By default, all Secure String values are cipher text when displayed using the EC2 console and the AWS CLI. To decrypt a Secure String value, a user must have KMS decryption permissions, as described in the next section. For more information about AWS KMS, see AWS Key Management Service Developer Guide.