How do I reference Systems Manager parameters in different AWS services?

Short description

The following example scenarios are different ways that you can reference Systems Manager parameters:

• Reference a regular string type parameter in a Systems Manager command document
• Reference a secure string type parameter in a Systems Manager command document
• Reference a string type parameter in an AWS CloudFormation template
• Reference a string type parameter in a Boto3 script
• Reference a string type parameter in a Systems Manager automation document
• Reference a string type parameter in an AWS Command Line Interface (AWS CLI)

Resolution

Reference a regular string type parameter in a Systems Manager command document

In this example, you're installing a version of AWS Command Line Interface (AWS CLI) on an Amazon Elastic Compute Cloud (Amazon EC2) Linux x86 (64-bit) instance. The AWS CLI version number is stored in the Parameter Store as /CLI/required-version.

The example references the parameter in a command document as {{ssm:/CLI/required-version}}:

Note: You can reference any Systems Manager parameter in a command document in the following format {{ssm:parameter-name}}.

{  
  "mainSteps": [  
    {  
      "action": "aws:runShellScript",  
      "name": "installSoftware",  
      "inputs": {  
        "runCommand": [  
          "echo 'Installing AWS CLI version {{ssm:/CLI/required-version}}'",  
          "curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64-{{ssm:/CLI/required-version}}" -o "awscliv2.zip",  
          "unzip awscliv2.zip",  
          "sudo ./aws/install"  
        ]  
      }  
    }  
  ]  
}

Reference a secure string type parameter in a Systems Manager command document

If you use a SecureString parameter type, then you must first decrypt the parameter through an AWS CLI command. Then, you can use the parameter in the command document.

Note: If you don't decrypt the parameter first, then the value that's written is the metadata value.

The following is an example of referencing a secure string type parameter in a command document:

{  
  "mainSteps": [  
    {  
      "action": "aws:runShellScript",  
      "name": "installSoftware",  
      "inputs": {  
        "runCommand": [  
          "secure=$(aws ssm get-parameters --names /CLI/required-version --with-decryption --query Parameters[0].Value)",  
          "curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64-$secure" -o "awscliv2.zip",  
          "unzip awscliv2.zip",  
          "sudo ./aws/install"  
        ]  
      }  
    }  
  ]  
}

Reference a string type parameter in a CloudFormation template

You can use a CloudFormation template to reference a string type parameter. Defining the value as a String indicates that the value that's returned for that parameter is a string. For other supported parameter types, see Supported SSM parameter types.

The following is an example of launching an Amazon EC2 instance whose name is stored in Parameter Store under the parameter name InstanceName:

{  
  "Parameters": {  
    "MyInstanceName": {  
      "Type": "AWS::SSM::Parameter::Value<String>",  
      "Default": "InstanceName",  
      "Description": "Name of the EC2 instance"  
    }  
  },  
  "Resources": {  
    "TestInstance": {  
      "Type": "AWS::EC2::Instance",  
      "Properties": {  
        "ImageId": "ami-xxxx",  
        "InstanceType": "t3.xlarge",  
        "Tags": [{  
          "Key": "Name",  
          "Value": { "Ref": "MyInstanceName" }  
        }]  
      }  
    }  
  }  
}

CloudFormation doesn't support defining template parameters as SecureString Systems Manager parameter types. However, you can use dynamic references to reference a secure string parameter in a CloudFormation template for only supported resources.

If you're using a dynamic reference for a secure string parameter in a CloudFormation template, then see this Example.

Reference a string type parameter in a Boto3 script

With Boto3, you can call a get_parameter function with a Name parameter. You can also include the WithDecryption field to reference an encrypted parameter.

The following example references the value of a secure string Systems Manager parameter called /instance/name to start the instance. In this example, the EC2 instance name is stored in the Systems Manager parameter /instance/name:.

Note: If you're using Boto3 with a string type parameter, then you can remove the WithDecryption field.

import boto3  
ec2_client = boto3.client('ec2')  
ssm_client = boto3.client('ssm')  
parameter_name = '/instance/name'  
response = ssm_client.get_parameter(  
    Name=parameter_name,  
    WithDecryption=True  
)  
instance_name = response['Parameter']['Value']  
response = ec2_client.describe_instances(  
    Filters=[  
        {  
            'Name': 'tag:Name',  
            'Values': [instance_name]  
        }  
    ]  
)  
instance_id = response['Reservations'][0]['Instances'][0]['InstanceId']  
ec2_client.start_instances(InstanceIds=[instance_id])  
print("Instance started successfully.")

Reference a string type parameter in an Systems Manager automation document

With Systems Manager automation documents, you can use the aws:executeAwsApi API to reference a Systems Manager parameter.

In the following example, the AMI Id is stored in the Systems Manager parameter and parsed as an input for this automation document. The parameter value from Step 1 is passed as input to Step 2 for launching an EC2 Instance.

Note: If you're referencing a SecureString parameter, then you can set the value for WithDecryption field to True. However, the output for the automation step getparameter displays the decrypted value of the parameter.

description: Sample runbook using AWS API operations
schemaVersion: '0.3'
assumeRole: '{{ AutomationAssumeRole }}'
parameters:
  AutomationAssumeRole:
    type: String
    description: (Optional) The ARN of the role that allows Automation to perform the actions on your behalf.
    default: ''
  AMIParameter:
    type: String
    description: SSM Parameter name to get the AMI ID from
mainSteps:
  - name: getparameter
    action: 'aws:executeAwsApi'
    inputs:
      Service: ssm
      Api: GetParameter
      Name: '{{AMIParameter}}'
      WithDecryption: false
    outputs:
      - Name: ImageId
        Selector: Parameter.Value
        Type: String
  - name: launchOneInstance
    action: 'aws:executeAwsApi'
    inputs:
      Service: ec2
      Api: RunInstances
      ImageId: '{{ getparameter.ImageId }}'
      MaxCount: 1
      MinCount: 1
    outputs:
      - Name: InstanceId
        Selector: '$.Instances[0].InstanceId'
        Type: String

Reference a string type parameter in the AWS CLI

Referencing Systems Manager parameters in the AWS CLI is similar to referencing the parameters in command documents. You can reference a string type parameter as ssm:parameter-name. For secure string parameters, you must first decrypt the parameter. Then, you can use the parameter in the AWS CLI command.

For an example of referencing a parameter in the AWS CLI, see Run a parameter (AWS CLI).