AWS Systems Manager
User Guide

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

    aws configure

    The system prompts you to specify the following.

    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.

    aws ssm put-parameter --name "parameter_name" --value "a parameter 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.

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

    The command returns the version number of the parameter.

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

    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.

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

    The command returns the version number of the parameter.

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

    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.

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

    aws ssm send-command --document-name "AWS-RunShellScript" --parameters '{"commands":["echo {{ssm:/Test/IAD/helloWorld}}"]}' --targets "Key=instanceids,Values=instance-ids"

Use the following procedure to create a Secure String parameter. For more information about Secure String parameters, see Use 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

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

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

    aws ssm put-parameter --name "parameter_name" --value "a parameter 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.

    aws ssm put-parameter --name "my-password" --value "P@ssW%rd#1" --type "SecureString" --key-id "arn:aws:kms:us-east-2:123456789012:key/1a2b3c4d-1a2b-1a2b-1a2b-1a2b3c4d5e"
  2. Execute the following command to view the parameter metadata.

    aws ssm describe-parameters --filters "Key=Name,Values=the_name_that_you_specified"
  3. Execute the following command to change the parameter value.

    aws ssm put-parameter --name "the_name_that_you_specified" --value "new parameter value" --type "SecureString" --overwrite

    Updating a Secure String parameter that uses your default KMS key

    aws ssm put-parameter --name "the_name_that_you_specified" --value "new parameter value" --type "SecureString" --key-id "the-AWS KMS-key-ID" --overwrite

    Updating a Secure String parameter that uses a custom KMS key

    aws ssm put-parameter --name "the_name_that_you_specified" --value "new parameter 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.

    aws ssm get-parameters --names "the_name_that_you_specified" --with-decryption
  5. Execute the following command to view the parameter value history.

    aws ssm get-parameter-history --name "the_name_that_you_specified"

Important

Only the value of a secure string parameter is encrypted. Parameter names, descriptions, and other properties are not encrypted.