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}}

Parameter Types

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

String

The content of a String parameter is an unvalidated plain text string. For example:

  • abc123

  • Confidential. Do Not Distribute.

  • Example Corp.

StringList

StringList parameters contain a comma-separated list of values. For example:

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).

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.

Parameter Examples (AWS CLI)

The following is an example of 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.

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.

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:

AWS CLI

value=$(aws ssm get-parameters --names parameter_name --with-decryption)
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.