Amazon EC2 Systems Manager Parameter Store adds support for Parameter versions

By Lou de la Torre, AWS Partner Solutions Architect and Venkat Krishnamachari, Principal Product Manager, Amazon EC2 Systems Manager

Today we are excited to announce versioning support for Amazon EC2 Systems Manager Parameter Store. With Parameter Store versioning support, each iteration of a parameter is assigned a unique version number at creation time. These individual version numbers can be easily referenced in API actions and Systems Manager Documents. By default, the latest value of the parameter will be returned when no version is specified.

Parameter Store

Parameter Store is part of Amazon EC2 Systems Manager. It provides a centralized, encrypted store to manage your configuration data, whether it is plain text data (database strings) or secure strings and secrets (such as passwords, and API keys). Because Parameter Store is available through the AWS CLI, APIs, and SDKs, you can easily reference parameters across AWS services such as AWS Lambda and Amazon EC2 Container Service (ECS).

For additional posts on Parameter Store, see:

The Right Way to Store Secrets using Parameter Store

Managing Secrets for Amazon ECS Applications Using Parameter Store and IAM Roles for Tasks

Organize Parameters by Hierarchy, Tags, or Amazon CloudWatch Events with Amazon EC2 Systems Manager Parameter Store

Parameter Store Versioning

Versioning provides an additional layer of protection for your Parameter Store values. For example, if code deployment fails you can easily roll back and reference older versions of config data saved as parameters in the Parameter Store. You can recover from unintended user errors that caused an overwrite in your parameter value. You can also use versioning to keep track of the number of times your stored values changed over the parameter’s lifetime for auditing purposes (see Figure 1).

By default, the initially created parameters’ version is 1. Versions are incremented automatically by increments of 1 whenever a value is updated in the Parameter Store. To demonstrate the value of Parameter Store versioning, consider the following scenario.

In an effort to minimize management overhead you decide to migrate your .NET application back-end SQL database from SQL on EC2 to RDS SQL. This will require that you deploy new code to your .NET application to update the database connection string. As with any migration, you want to ensure you can quickly rollback in case of failure.

With Parameter Store versioning you can quickly rollback by performing the following steps:

1. Create a new Parameter pointing to the existing database string (SQL on EC2)
2. Create a new version of the Parameter pointing to the new database string (RDS SQL)
3. Update your code with a reference to the latest or Default version of the parameter
4. Migrate your database from SQL on EC2 to RDS SQL
5. Deploy your code updating the .NET application to point to the new SQL database running on RDS via the latest or Default version of the parameter
6. If any issues arise, simply update your code with the original version of the Parameter pointing your .NET application back to the original SQL on EC2 instance and re-deploy

Let’s take a look at how easily you can make that happen by first creating a Parameter, then updating the parameter, viewing all existing versions of the Parameter, retrieving a Parameter by specific version number and finally rolling back to the original version of the Parameter. To do this you can use either the AWS CLI or the AWS Tools for Windows PowerShell. We will walk you through using both.

Step 1. Create a Parameter

Execute the following command to create a Parameter using the AWS CLI:

aws ssm put-parameter --name "/Prod/dotnet" --type String --value "ec2-13-57-12-38.us-west-1.compute.amazonaws.com:1433"

or you can use the AWS Tools for Windows PowerShell:

Write-SSMParameter -Name "/Prod/dotnet" -Value "ec2-13-57-12-38.us-west-1.compute.amazonaws.com:1433" -Type "String"

Step 2. Update the Parameter

Execute the following command to update the parameter using the AWS CLI (note the change in value and the overwrite option):

aws ssm put-parameter --name "/Prod/dotnet" --type String --value "dotnet.ctvzltftaz4x.us-west-1.rds.amazonaws.com:1433" --overwrite

Or you can use the AWS Tools for Windows PowerShell (note the change in value and the overwrite option):

Write-SSMParameter -Name "/Prod/dotnet" -Value "dotnet.ctvzltftaz4x.us-west-1.rds.amazonaws.com:1433" -Type "String" -Overwrite $true

Step 3. View all existing Versions of the Parameter

Execute the following command to view all existing versions of the Parameter using the CLI:

aws ssm get-parameter-history --name “/Prod/dotnet”

The System returns information similar to the following:

PS C:\> aws ssm get-parameter-history --name “/Prod/dotnet”
{
    "Parameters": [
        {
            "LastModifiedUser": "arn:aws:iam", 
            "LastModifiedDate": 1507742527.826, 
            "Type": "String", 
            "Name": "/Prod/dotnet", 
            "Value": "ec2-13-57-12-38.us-west-1.compute.amazonaws.com:1433"
                           "Version": 1
        }, 
        {
            "LastModifiedUser": "arn:aws:iam", 
            "LastModifiedDate": 1507743165.366, 
            "Type": "String", 
            "Name": "/Prod/dotnet", 
            "Value": "dotnet.ctvzltftaz4x.us-west-1.rds.amazonaws.com:1433"
            "Version": 2
        }
    ]
}

or you can execute the following command to view all existing versions of the Parameter using the AWS Tools for Windows PowerShell:

Get-SSMParameterHistory -Name "/Prod/dotnet"

The System returns information similar to the following:

PS C:\> Get-SSMParameterHistory -Name "/Prod/dotnet"
Description      :
KeyId            :
LastModifiedDate : 10/11/2017 5:22:07 PM
LastModifiedUser: arn:aws:iam
Name             : /Prod/dotnet
Type             : String
Value            : ec2-13-57-12-38.us-west-1.compute.amazonaws.com:1433
Version          : 1
Description      : 
KeyId            :
LastModifiedDate : 10/11/2017 5:32:45 PM
LastModifiedUser : arn:aws:iam
Name             : /Prod/dotnet
Type             : String
Value            : dotnet.ctvzltftaz4x.us-west-1.rds.amazonaws.com:1433
Version          : 2

Step 4. Retrieve the Parameter

Use the following AWS CLI to retrieve parameters:

Execute the following command to retrieve the latest version of the Parameter (default):

aws ssm get-parameters --names “/Prod/dotnet”

The System returns information similar to the following:

PS C:\> aws ssm get-parameters --name “/Prod/dotnet”

{
    "InvalidParameters": [],
    "Parameters": [
        {
            "Type": "String",
            "Name": "/Prod/dotnet",
            "Value": "dotnet.ctvzltftaz4x.us-west-1.rds.amazonaws.com:1433"
            "Version": 2
        }
    ]
}

aws ssm get-parameters --names “/Prod/dotnet:1"

PS C:\> aws ssm get-parameters --region us-west-1 --name “/Prod/dotnet”

{
    "InvalidParameters": [],
    "Parameters": [
        {
            "Type": "String",
            "Name": "/Prod/dotnet",
            "Value": "ec2-13-57-12-38.us-west-1.compute.amazonaws.com:1433"
            "Version": 1
        }
    ]
}

or using the the AWS Tools for Windows PowerShell, you can execute the following command to retrieve the latest version of the Parameter (default):

(Get-SSMParameterValue -Names "/Prod/dotnet").Parameters | fl

The System returns information similar to the following:

PS C:\> (Get-SSMParameterValue -Name "/Prod/dotnet").Parameters | fl
Name     : /Prod/dotnet
Type       : String
Value     : dotnet.ctvzltftaz4x.us-west-1.rds.amazonaws.com:1433
Version  : 2

Execute the following command to retrieve a specific version of the Parameter (by version number):

(Get-SSMParameterValue -Names "/Prod/dotnet:1").Parameters | fl

The system returns information similar to the following:

PS C:\> (Get-SSMParameterValue -Name "/Prod/dotnet:1").Parameters | fl
Name      : /Prod/dotnet
Type        : String
Value      : ec2-13-57-12-38.us-west-1.compute.amazonaws.com:1433
Version   : 1

Note the difference in values.

To roll back your .NET application to point to the original SQL on EC2 instance, simply update your code to reference the previous version of the Parameter and re-deploy.

You can reference Parameter Store versioning in Systems Manager Documents as well, as show in the following example:

Systems Manager AWS-RunShellScript example

The default value for commands is referenced with version 2 of SSM parameter ‘runcommand’.

{
    "schemaVersion":"1.2",
    "description":"Run a shell script or specify the commands to run.",
    "parameters":{
        "commands":{
            "type":"StringList",
            "description":"(Required) Specify a shell script or a command to run.",
            "minItems":1,
            "displayType":"textarea"
            "default":"{{ssm:runcommand:2}}"
        },
        "executionTimeout":{
            "type":"String",
            "default":"3600",
            "description":"(Optional) The time in seconds for a command to complete before it is considered to have failed. Default is 3600 (1 hour). Maximum is 28800 (8 hours).",
            "allowedPattern":"([1-9][0-9]{0,3})|(1[0-9]{1,4})|(2[0-7][0-9]{1,3})|(28[0-7][0-9]{1,2})|(28800)"
        }
    },
    "runtimeConfig":{
        "aws:runShellScript":{
            "properties":[
                {
                    "id":"0.aws:runShellScript",
                    "runCommand":"{{ commands }}",
                    "timeoutSeconds":"{{ executionTimeout }}"
                }
            ]
        }
    }
}

Summary
Parameter Store provides a centralized, encrypted store to manage your configuration data, whether it is plain text data (database strings) or secure strings and secrets (such as passwords, and API keys). Use versioning to add an extra layer of protection for your Parameter Store values. This new feature is available now and you can start using it today!

About the author

Lou De La Torre is a Partner Solutions Architect with Amazon Web Services. Lou is responsible for assisting Partners and Customers alike with their AWS for Windows architectures and migration strategies. With a career in information technology that spans more than two decades, Lou brings a significant amount of expertise in cloud and systems architecture, systems management, disaster recovery, process improvement and compliance management. Lou consistently strives to ensure that he is delivering solutions that align with the needs and requirements of his customer’s business objectives, while alleviating any pain points they may be experiencing in their IT operations.