Parameter types and examples - AWS Systems Manager

Parameter types and examples

A Parameter Store parameter is any piece of data that is saved in Parameter Store, such as a block of text, a list of names, a password, an Amazon Machine Image (AMI) ID, a license key, and so on. You can centrally and securely reference this data in your scripts, commands, and SSM documents.

Important

Do not store sensitive data in a String or StringList parameter. For all sensitive data that must remain encrypted, use only the SecureString parameter type.

For more information, see SecureString parameters.

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

{{ssm:parameter-name}}

Note

Parameters can't be referenced or nested in the values of other parameters. You can't include {{}} or {{ssm:parameter-name}} in a parameter value.

Parameter types

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 plain text, 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.

String

By default, String parameters consist of any block of text you enter. For example:

  • abc123

  • Example Corp

  • <img src="images/bannerImage1.png"/>

You can also use the DataType option to validate that the parameter value you enter is a properly formatted Amazon EC2 AMI ID, as shown in the following example AWS CLI command.

Linux

Parameter not in a hierarchy:

aws ssm put-parameter \ --name "golden-ami" \ --type "String" \ --data-type "aws:ec2:image" \ --value "ami-12345abcdeEXAMPLE"

Parameter in a hierarchy:

aws ssm put-parameter \ --name "\amis\linux\golden-ami" \ --type "String" \ --data-type "aws:ec2:image" \ --value "ami-12345abcdeEXAMPLE"
Windows

Parameter not in a hierarchy:

aws ssm put-parameter ^ --name "golden-ami" ^ --type "String" ^ --data-type "aws:ec2:image" ^ --value "ami-12345abcdeEXAMPLE"

Parameter in a hierarchy:

aws ssm put-parameter ^ --name "\amis\windows\golden-ami" ^ --type "String" ^ --data-type "aws:ec2:image" ^ --value "ami-12345abcdeEXAMPLE"

You do not need to specify a data type in any other cases.

StringList

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

Monday,Wednesday,Friday

CSV,TSV,CLF,ELF,JSON

SecureString

The SecureString parameter type can be used for textual data that you want to encrypt, such as passwords, application secrets, confidential configuration data, or any other types of data you need to protect. SecureString data is encrypted and decrypted using a AWS Key Management Service (KMS) key. You can use either a default KMS key provided by AWS or create and use your own customer master key (CMK). (Use your own CMK if you need to restrict user access to SecureString parameters. For information, see IAM permissions for using AWS default keys and customer managed keys.)

There is no charge from Parameter Store to create a SecureString parameter, but charges for use of AWS Key Management Service encryption do apply. For information, see AWS Key Management Service pricing.

Note

Parameter Store is also integrated with AWS Secrets Manager. You can retrieve Secrets Manager secrets when using other AWS services that already support references to Parameter Store parameters. For more information, see Referencing AWS Secrets Manager secrets from Parameter Store parameters in this guide.

For more information about SecureString parameters, see SecureString parameters.

Parameter examples (AWS CLI)

Creating parameters

The following example creates a plain-text String parameter.

Linux
aws ssm put-parameter \ --name "MyStringTextParameter" \ --type "String" \ --value "Text parameter test"
Windows
aws ssm put-parameter ^ --name "MyStringTextParameter" ^ --type "String" ^ --value "Text parameter test"

The following example creates a String parameter that specifies the data type as aws:ec2:image.

Linux
aws ssm put-parameter \ --name "MyStringAMIParameter" \ --type "String" \ --data-type "aws:ec2:image" \ --value "ami-12345abcdeEXAMPLE"
Windows
aws ssm put-parameter ^ --name "MyStringAMIParameter" ^ --type "String" ^ --data-type "aws:ec2:image" ^ --value "ami-12345abcdeEXAMPLE"

For information about using the data type aws:ec2:image, see Parameter types and Native parameter support for Amazon Machine Image IDs.

The following example creates a StringList parameter:

Linux
aws ssm put-parameter \ --name "MyStringListParameter" \ --type "StringList" \ --value "North,South,East,West"
Windows
aws ssm put-parameter ^ --name "MyStringListParameter" ^ --type "StringList" ^ --value "North,South,East,West"

For more examples of creating and updating parameters using the AWS CLI, see Create a Systems Manager parameter (AWS CLI) and put-parameter in the AWS Systems Manager section of the AWS CLI Command Reference.

Parameters in Run Command commands

The following example command includes a Systems Manager parameter named DNS-IP. The value of this parameter is simply the IP address of an instance. This example uses an AWS CLI command to echo the parameter value.

Linux
aws ssm send-command \ --document-name "AWS-RunPowerShellScript" \ --document-version "1" \ --targets "Key=instanceids,Values=i-02573cafcfEXAMPLE" \ --parameters "commands='echo {{ssm:DNS-IP}}'" \ --timeout-seconds 600 \ --max-concurrency "50" \ --max-errors "0" \ --region us-east-2
Windows
aws ssm send-command ^ --document-name "AWS-RunPowerShellScript" ^ --document-version "1" ^ --targets "Key=instanceids,Values=i-02573cafcfEXAMPLE" ^ --parameters "commands='echo {{ssm:DNS-IP}}'" ^ --timeout-seconds 600 ^ --max-concurrency "50" ^ --max-errors "0" ^ --region us-east-2

The next example command uses a SecureString parameter named SecurePassword. The command commands=['$secure = (Get-SSMParameterValue -Names SecurePassword -WithDecryption $True).Parameters[0].Value','net user administrator $secure'] retrieves and decrypts the value of the SecureString parameter, and then resets the local administrator password without having to pass the password in clear text.

Linux
aws ssm send-command \ --document-name "AWS-RunPowerShellScript" \ --document-version "1" \ --targets "Key=instanceids,Values=i-02573cafcfEXAMPLE" \ --parameters "commands=['$secure = (Get-SSMParameterValue -Names SecurePassword -WithDecryption $True).Parameters[0].Value','net user administrator $secure']" \ --timeout-seconds 600 \ --max-concurrency "50" \ --max-errors "0" \ --region us-east-2
Windows
aws ssm send-command ^ --document-name "AWS-RunPowerShellScript" ^ --document-version "1" ^ --targets "Key=instanceids,Values=i-02573cafcfEXAMPLE" ^ --parameters "commands=['$secure = (Get-SSMParameterValue -Names SecurePassword -WithDecryption $True).Parameters[0].Value','net user administrator $secure']" ^ --timeout-seconds 600 ^ --max-concurrency "50" ^ --max-errors "0" ^ --region us-east-2

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

{ "schemaVersion":"2.0", "description":"Sample version 2.0 document v2", "parameters":{ "commands" : { "type": "StringList", "default": ["{{ssm:parameter-name}}"] } }, "mainSteps":[ { "action":"aws:runShellScript", "name":"runShellScript", "inputs":{ "runCommand": "{{commands}}" } } ] }

Don't confuse the similar syntax for local parameters used in the runtimeConfig section of SSM documents with Parameter Store parameters. A local parameter isn't the same as a Systems Manager parameter. You can distinguish local parameters from Systems Manager parameters by the absence of the ssm: prefix:

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

SSM documents currently don't support references to SecureString parameters. This means that to use SecureString parameters with, for example, Run Command, you have to retrieve the parameter value before passing it to Run Command, as shown in the following examples:

Linux
value=$(aws ssm get-parameters --names parameter-name --with-decryption)
aws ssm send-command \ --name AWS-JoinDomain \ --parameters password=$value \ --instance-id instance-id
Windows
aws ssm send-command ^ --name AWS-JoinDomain ^ --parameters password=$value ^ --instance-id instance-id
Tools for Windows PowerShell
$secure = (Get-SSMParameterValue -Names parameter-name -WithDecryption $True).Parameters[0].Value | ConvertTo-SecureString -AsPlainText -Force
$cred = New-Object System.Management.Automation.PSCredential -argumentlist user-name,$secure

Integration examples from the community

The following section provide links to blog posts, articles, and community-provided examples for using Parameter Store parameters.

Note

These links are provided for informational purposes only, and should not be considered either a comprehensive list or an endorsement of the content of the examples. AWS is not responsible for the content or accuracy of external content.