Menu
AWS Systems Manager
User Guide

Systems Manager Parameter Store Walkthroughs

The following walkthroughs show you how to create, store, and execute parameters with Parameter Store in a test environment. These walkthroughs show you how to use Parameter Store with other Systems Manager capabilities. You can also use Parameter Store with other AWS services. For more information, see Using Secure String Parameters With Other AWS Services.

Create and Use a Parameter in a Command (Console)

The following procedure walks you through the process of creating a parameter in Parameter Store and then executing a Run Command command that uses this parameter.

Note

The following procedure describes steps that you perform in the Amazon EC2 console. You can also perform these steps in the new AWS Systems Manager console. The steps in the new console will differ from the steps below.

To create a parameter using Parameter Store

  1. Open the Amazon EC2 console, expand Systems Manager Shared Resources in the navigation pane, and then choose Parameter Store.

  2. Choose Create Parameter.

  3. For Name, type a hierarchy and a name. For example, type /Test/helloWorld. For more information about parameter hierarchies, see Organizing Parameters into Hierarchies.

  4. In the Description field, type a description that identifies this parameter as a test parameter.

  5. For Type, choose String.

  6. In the Value field, type a string. For example, type My1stParameter.

  7. Choose Create Parameter. After the system creates the parameter, choose OK

  8. In the EC2 console navigation pane, expand Commands and then choose Run Command.

  9. Choose Run a command.

  10. In the Command Document list, choose AWS-RunPowershellScript (Windows) or AWS-RunShellScript (Linux).

  11. Under Target instances, choose the instance you created earlier.

  12. In the Commands field, type echo {{ssm:parameter name}}, for example, echo {{ssm:/Test/helloWorld}}.

  13. Choose Run.

  14. In the command history list, choose the command you just ran, choose the Output tab, and then choose View Output.

Create and Use a Parameter in a Command (AWS CLI)

The following procedure walks you through the process of creating and storing a parameter using the AWS CLI.

To create a String parameter using Parameter Store

  1. Download the AWS CLI to your local machine.

  2. Open the AWS CLI and run the following command to specify your credentials and a Region. You must either have administrator privileges in Amazon EC2, or you must have been granted the appropriate permission in AWS Identity and Access Management (IAM).

    Copy
    aws configure

    The system prompts you to specify the following.

    Copy
    AWS Access Key ID [None]: key_name AWS Secret Access Key [None]: key_name Default region name [None]: region Default output format [None]: ENTER
  3. Execute the following command to create a parameter that uses the String data type. The --name parameter uses a hierarchy. For more information about hierarchies, see Organizing Parameters into Hierarchies.

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

    Here is an example that uses a parameter hierarchy in the name. For more information about parameter hierarchies, see Organizing Parameters into Hierarchies.

    Copy
    aws ssm put-parameter --name "/Test/IAD/helloWorld" --value "My1stParameter" --type String

    The command has no output.

  4. Execute the following command to view the parameter metadata.

    Copy
    aws ssm describe-parameters --filters "Key=Name,Values=/Test/IAD/helloWorld"

    Note

    Name must be capitalized.

    The system returns information like the following.

    {
        "Parameters": [
            {
                "LastModifiedUser": "arn:aws:iam::123456789:user/User's name",
                "LastModifiedDate": 1494529763.156,
                "Type": "String",
                "Name": "helloworld"
            }
        ]
    }
    
  5. Execute the following command to change the parameter value.

    Copy
    aws ssm put-parameter --name "/Test/IAD/helloWorld" --value "good day sunshine" --type String --overwrite

    The command has no output.

  6. Execute the following command to view the latest parameter value.

    Copy
    aws ssm get-parameters --names "/Test/IAD/helloWorld"

    The system returns information like the following.

    {
        "InvalidParameters": [],
        "Parameters": [
            {
                "Type": "String",
                "Name": "/Test/IAD/helloWorld",
                "Value": "good day sunshine"
            }
        ]
    }
  7. Execute the following command to view the parameter value history.

    Copy
    aws ssm get-parameter-history --name "/Test/IAD/helloWorld"
  8. Execute the following command to use this parameter in a Run Command command.

    Copy
    aws ssm send-command --document-name "AWS-RunShellScript" --parameters "commands=["echo {{ssm:/Test/IAD/helloWorld}}"]" --targets "Key=instance-ids,Values=the ID of an instance configured for Systems Manager"

Use the following procedure to create a Secure String parameter. For more information about Secure String parameters, see Using Secure String Parameters.

To create a Secure String parameter using the AWS CLI

  1. Execute one of the following commands to create a parameter that uses the Secure String data type.

    Create a Secure String parameter that uses your default KMS key

    Copy
    aws ssm put-parameter --name "a_name" --value "a value, for example P@ssW%rd#1" --type "SecureString"

    Create a Secure String parameter that uses a custom AWS KMS key

    Copy
    aws ssm put-parameter --name "a_name" --value "a value" --type "SecureString" --key-id "your AWS user account ID/the custom AWS KMS key"

    Here is an example that uses a custom AWS KMS key.

    Copy
    aws ssm put-parameter --name "db-password" --value "P@ssW%rd#1" --type "SecureString" --key-id "arn:aws:kms:us-east-1:123456789012:key/1a2b3c4d-1a2b-1a2b-1a2b-1a2b3c4d5e"

    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.

  2. Execute the following command to view the parameter metadata.

    Copy
    aws ssm describe-parameters --filters "Key=Name,Values=the name that you specified"
  3. Execute the following command to change the parameter value.

    Copy
    aws ssm put-parameter --name "the name that you specified" --value "new value" --type "SecureString" --overwrite

    Updating a Secure String parameter that uses your default KMS key

    Copy
    aws ssm put-parameter --name "the name that you specified" --value "new value" --type "SecureString" --key-id "the AWS KMS key ID" --overwrite

    Updating a Secure String parameter that uses a custom KMS key

    Copy
    aws ssm put-parameter --name "the name that you specified" --value "new value" --type "SecureString" --key-id "your AWS user account alias/the custom KMS key" --overwrite
  4. Execute the following command to view the latest parameter value.

    Copy
    aws ssm get-parameters --names "the name that you specified" --with-decryption
  5. Execute the following command to view the parameter value history.

    Copy
    aws ssm get-parameter-history --name "the name that you specified"

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 and Join an Instance to a Domain (PowerShell)

This walkthrough shows you how to join a Windows instance to a domain using Systems Manager Secure String parameters and Run Command. The walkthrough uses typical domain parameters, such as the DNS address, the domain name, and a domain user name. These values are passed as unencrypted string values. The domain password is encrypted using a AWS KMS master key and passed as a Secure String.

To create a Secure String Parameter and Join an Instance to a Domain

  1. Enter parameters into the system using AWS Tools for Windows PowerShell.

    Copy
    Write-SSMParameter -Name DNS-IP -Value a DNS IP address -Type String Write-SSMParameter -Name domainName -Value the domain name -Type String Write-SSMParameter -Name domainJoinUserName -Value a user name -Type String Write-SSMParameter -Name domainJoinPassword -Value a password -Type SecureString

    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.

  2. Attach the AmazonEC2RoleforSSM managed policy to the IAM role permissions for your instance. For information, see Managed Policies and Inline Policies.

  3. Edit the IAM role attached to the instance and add the following policy. This policy gives the instance permissions to call the kms:Decrypt API.

    Copy
    { "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Action":[ "kms:Decrypt" ], "Resource":[ "arn:aws:kms:region:account_id:key/key_id" ] } ] }
  4. Copy and paste the following json sample into a simple text editor and save the file as JoinInstanceToDomain.json in the following location: c:\temp\JoinInstanceToDomain.json.

    Copy
    { "schemaVersion":"2.0", "description":"Run a PowerShell script to securely domain-join a Windows instance", "mainSteps":[ { "action":"aws:runPowerShellScript", "name":"runPowerShellWithSecureString", "inputs":{ "runCommand":[ "$ipdns = (Get-SSMParameterValue -Name dns).Parameters[0].Value\n", "$domain = (Get-SSMParameterValue -Name domainName).Parameters[0].Value\n", "$username = (Get-SSMParameterValue -Name domainJoinUserName).Parameters[0].Value\n", "$password = (Get-SSMParameterValue -Name domainJoinPassword -WithDecryption $True).Parameters[0].Value | ConvertTo-SecureString -asPlainText -Force\n", "$credential = New-Object System.Management.Automation.PSCredential($username,$password)\n", "Set-DnsClientServerAddress \"Ethernet 2\" -ServerAddresses $ipdns\n", "Add-Computer -DomainName $domain -Credential $credential\n", "Restart-Computer -force" ] } } ] }
  5. Execute the following command in AWS Tools for Windows PowerShell to create a new SSM document.

    Copy
    $json = Get-Content C:\temp\JoinInstanceToDomain | Out-String New-SSMDocument -Name JoinInstanceToDomain -Content $json -DocumentType Command
  6. Execute the following command in AWS Tools for Windows PowerShell to join the instance to the domain

    Copy
    Send-SSMCommand -InstanceId Instance-ID -DocumentName JoinInstanceToDomain

Manage Parameters Using Hierarchies

This walkthrough shows you how to work with parameters and parameter hierarchies by using the AWS CLI. For more information about parameter hierarchies, see Organizing Parameters into Hierarchies.

To manage parameters using hierarchies

  1. Download the AWS CLI to your local machine.

  2. Open the AWS CLI and run the following command to specify your credentials and a Region. You must either have administrator privileges in Amazon EC2, or you must have been granted the appropriate permission in AWS Identity and Access Management (IAM).

    Copy
    aws configure

    The system prompts you to specify the following.

    Copy
    AWS Access Key ID [None]: key_name AWS Secret Access Key [None]: key_name Default region name [None]: region Default output format [None]: ENTER
  3. Execute the following command to create a parameter that uses the allowedPattern parameter and the String data type. The allowed pattern in this example means the value for the parameter must be between 1 and 4 digits long.

    Copy
    aws ssm put-parameter --name "/MyService/Test/MaxConnections" --value 100 --allowed-pattern "\d{1,4}" --type String

    The command has no output.

  4. Execute the following command to attempt to overwrite the parameter you just created with a new value.

    Copy
    aws ssm put-parameter --name "/MyService/Test/MaxConnections" --value 10,000 --type String --overwrite

    The system throws the following error because the new value does not meet the requirements of the allowed pattern you specified in the previous step.

    An error occurred (ParameterPatternMismatchException) when calling the PutParameter operation: Parameter value, cannot be validated against allowedPattern: \d{1,4}

  5. Execute the following command to create a Secure String parameter that uses your default AWS KMS key. The allowed pattern in this example means the user can specify any character, and the value must be between 8 and 20 characters.

    Copy
    aws ssm put-parameter --name "/MyService/Test/DBpassword" --value "p#sW*rd33" --allowed-pattern ".{8,20}" --type SecureString
  6. Execute the following commands to create more parameters that use the hierarchy structure from the previous step.

    Copy
    aws ssm put-parameter --name "/MyService/Test/DBname" --value "SQLDevDb" --type String
    Copy
    aws ssm put-parameter --name "/MyService/Test/user" --value "SA" --type String
    Copy
    aws ssm put-parameter --name "/MyService/Test/userType" --value "SQLuser" --type String
  7. Execute the following command to get the value of two parameters.

    Copy
    aws ssm get-parameters --names "/MyService/Test/user" "/MyService/Test/userType"
  8. Execute the following command to query for all parameters within a single level.

    Copy
    aws ssm describe-parameters --filters Key=Name,Values="/MyService/Test"
  9. Execute the following command to delete two parameters

    Copy
    aws ssm delete-parameters --name "/IADRegion/Dev/user" "/IADRegion/Dev/userType"