Menu
Amazon EC2 Systems Manager
User Guide

About Systems Manager Parameters

You can reference Systems Manager parameters in your scripts, commands, and configuration and automation workflows. Parameters work with Systems Manager capabilities such as Run Command, State Manager, and Automation. You can also reference parameters in other AWS services such as Amazon EC2 Container Service and AWS Lambda.

With Systems Manager capabilities, you can reference Systems Manager parameters in your AWS CLI or AWS Tools for Windows PowerShell commands or scripts. You can also reference parameters in SSM documents. For more information about SSM documents, see Systems Manager Documents.

The following is an example of a Systems Manager parameter in an AWS CLI command for Run Command. Systems Manager Parameters are always prefixed with ssm:.

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

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

Copy
{ "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}}" } } ] }

Note

The runtimeConfig section of SSM documents use similar syntax for local parameters. A local parameter is not the same as a Systems Manager parameter. You can distinguish local parameters from Systems Manager parameters by the absence of the ssm: prefix.

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

SSM documents currently don't support references to Secure String parameters. This means that to use Secure String 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

Copy
$value=aws ssm get-parameters --names the parameter name --with-decryption
Copy
aws ssm send-command –name AWS-JoinDomain –parameters password=$value –instance-id the instance ID

Tools for Windows PowerShell

Copy
$secure = (Get-SSMParameterValue -Names the parameter name -WithDecryption $True).Parameters[0].Value | ConvertTo-SecureString -AsPlainText -Force
Copy
$cred = New-Object System.Management.Automation.PSCredential -argumentlist user name,$secure

Using Secure String Parameters

A Secure String parameter 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 passwords or license keys, then create those parameters using the Secure String data type. We recommend using Secure String parameters for the following scenarios.

  • You want to use data/parameters across AWS services without exposing the values as clear text in commands, functions, agent logs, or AWS CloudTrail logs.

  • You want to control who has access to sensitive data.

  • You want to be able to audit when sensitive data is accessed (AWS CloudTrail).

  • You want AWS-level encryption for your sensitive data and you want to bring your own encryption keys to manage access.

If you choose the Secure String data type when you create your parameter, then AWS KMS encrypts the parameter value. For more information about AWS KMS, see AWS Key Management Service Developer Guide.

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

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

Important

Only the value of the secure string parameter is encrypted. The name of the parameter, description, and other properties are not encrypted. For this reason, consider creating a naming system that avoids the word "password" in parameter names.

Create a Secure String Parameter Using the Default KMS Key

If you create a Secure String parameter using the default 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:

Copy
aws ssm put-parameter --name a_name --value "a value" --type SecureString

Create a Secure String Parameter Using a KMS Customer Master Key (CMK)

If you want to use a custom KMS key instead of the default key assigned to your account, then you must specify the ARN using the --key-id parameter. The parameter supports the following AWS KMS parameter formats.

  • Key ARN example

    arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012

  • Alias ARN example

    arn:aws:kms:us-east-1:123456789012:alias/MyAliasName

  • Globally Unique Key ID example

    12345678-1234-1234-1234-123456789012

  • Alias Name example

    alias/MyAliasName

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

Copy
aws kms create-key

Use the following command to create a Secure String parameter using the key you just created.

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

Note

You can manually create a parameter with an encrypted value. In this case, because the value 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.

By default, all Secure String values are displayed as cipher text in the Amazon EC2 console and the AWS CLI. To decrypt a Secure String value, a user must have KMS decryption permissions.

Using Secure String Parameters With Other AWS Services

You can also use Secure String parameters with other AWS services. In the following example, the Lambda function retrieves a Secure String parameter by using the GetParameters API.

Copy
from __future__ import print_function import json import boto3 ssm = boto3.client('ssm', 'us-east-1') def get_parameters(): response = ssm.get_parameters( Names=['LambdaSecureString'],WithDecryption=True ) for parameter in response['Parameters']: return parameter['Value'] def lambda_handler(event, context): value = get_parameters() print("value1 = " + value) return value # Echo back the first key value

Related topics

For an example of how to create and use a Secure String parameter, see Create a Secure String Parameter and Join an Instance to a Domain (PowerShell).

For more information about using Systems Manager parameters with other AWS services, see the following blogpost.