Menu
Amazon EC2 Systems Manager
User Guide

Working with Systems Manager Parameters

This section describes how to organize, create, and tag parameters.

Organizing Parameters into Hierarchies

Managing dozens or hundreds of parameters as a flat list is time-consuming and prone to errors. It can also be difficult to identify the correct parameter for a task. This means you might accidentally use the wrong parameter, or you might create multiple parameters that use the same configuration data.

You can use parameter hierarchies to help you organize and manage parameters. A hierarchy is a parameter name that includes a path that you define by using forward slashes. Here is an example that uses three hierarchy levels in the name to identify the following:

/Environment/Type of computer/Application/Data

/Dev/DBServer/MySQL/db-string13

You can create a hierarchy with a maximum of five levels. We suggest that you create hierarchies that reflect an existing hierarchical structure in your environment, as shown in the following examples:

  • Your continuous development and integration environment (CI/CD worklows)

    /Dev/DBServer/MySQL/db-string
    /Staging/DBServer/MySQL/db-string
    /Prod/DBServer/MySQL/db-string
  • Your applications that use containers

    /MyApp/.NET/Libaries/git-password
  • Your business organization

    /Finance/Accountants/UserList
    /Finance/Analysts/UserList
    /HR/Employees/EU/UserList

Parameter hierarchies standardize the way you create parameters and make it easier to manage parameters over time. A parameter hierarchy can also help you identify the correct parameter for a configuration task. This helps you to avoid creating multiple parameters with the same configuration data.

You can create a hierarchy that allows you to share parameters across different environments, as shown in the following examples that use passwords in development and staging environment.

/DevTest/MyApp/database/db_password

You could then create a unique password for your production environment, as shown in the following example:

/prod/MyApp/database/db_password

You are not required to specify a parameter hierarchy. You can create parameters at level one. These are called root parameters. For backward compatibility, all parameters created in Parameter Store before hierarchies were released are root parameters. The systems treats both of the following parameters as root parameters.

/parameter-name

parameter-name

For an example of how to work with parameter hierarchies, see Manage Parameters Using Hierarchies.

Querying Parameters in a Hierarchy

Another benefit of using hierarchies is the ability to query for all parameters within a hierarchy by using the GetParametersByPath API action. For example, if you execute the following command from the AWS CLI, the system returns all parameters in the IIS level.

aws ssm get-parameters-by-path --path /Dev/Web/IIS

To view decrypted SecureString parameters in a hierarchy, you specify the path and the --with-decryption parameter, as shown in the following example.

aws ssm get-parameters-by-path --path /Prod/ERP/SAP --with-decryption

Restricting IAM Permissions Using Hierarchies

Using hierarchies and AWS Identity and Access Management (IAM) policies for Parameter Store API actions, you can provide or restrict access to all parameters in one level of a hierarchy. The following example policy allows a user or a group to access only the DescribeParameter API action for parameters in the Oracle level of the hierarchy.

Copy
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ssm:*" ], "Resource": "arn:aws:ssm:us-east-1:123456789012:parameter/*" }, { "Effect": "Deny", "Action": [ "ssm:GetParametersByPath" ], "Condition": { "StringEquals": { "ssm:Recursive": [ "true" ] } }, "Resource": "arn:aws:ssm:us-east-1:123456789012:parameter/Dev/ERP/Oracle/*" }, { "Effect": "Deny", "Action": [ "ssm:PutParameter" ], "Condition": { "StringEquals": { "ssm:Overwrite": [ "false" ] } }, "Resource": "arn:aws:ssm:us-east-1:123456789012:parameter/*" } ] }

Creating Systems Manager Parameters

You can create parameters by using the AWS CLI, AWS Tools for Windows PowerShell, or Amazon EC2 console, as described in this section.

When you create a parameter, you specify the following information:

  • Name: (Required) Specify a name to identify your parameter. Be aware of the following requirements and restrictions for Systems Manager parameter names:

    • Parameter names are case sensitive.

    • A parameter name must be unique within your AWS account. For example, Systems Manager treats the following as separate parameters:

      • /CMH/TestParam1

      • /TestParam1

      The following examples are also unique:

      • /CMH/TestParam1/Logpath1

      • /CMH/TestParam1

      The following examples are not unique:

      • /TestParam1

      • TestParam1

    • A parameter name can't be prefixed with "aws" or "ssm" (case-insensitive). For example, awsTestParameter, SSM-testparameter, or /aws/testparam1 will fail with an exception.

    • Parameter names can only include the following symbols and letters:

      a-zA-Z0-9_.-/

    • A parameter name can't include spaces.

    • If you specify a parameter hierarchy, the hierarchy can have a maximum depth of five levels. You can define a parameter at any level of the hierarchy. Both of the following examples are valid:

      /Level-1/Level-2/Level-3/Level-4/Level-5/parameter-name

      /Level-1/parameter-name

      Attempting to create the following parameter would fail with a HierarchyLevelLimitExceededException exception:

      /Level-1/Level-2/Level-3/Level-4/Level-5/Level-6/parameter-name

  • Data Type: (Required) Specify a data type to define how the system uses a parameter. Parameter Store currently supports the following data types: String, StringList, and SecureString.

    Note

    Items in a StringList must be separated by a comma (,). You can't use other punctuation or special character to escape items in the list. If you have a parameter value that requires a comma, then use the String data type.

  • Description (Optional, but recommended): Type a description to help you identify parameters and their intended use.

  • Value: (Required) Your parameter value.

  • Key ID: Key ID applies only to parameters that use the SecureString data type. Key ID can either be the default AWS Key Management Service (AWS KMS) key automatically assigned to your AWS account or a custom key. Note the following:

    • To use your default AWS KMS key, choose the SecureString data type, and do not specify the Key ID when you create the parameter. The system automatically populates Key ID with your default KMS key.

    • To use a custom KMS key, choose the SecureString data type with the Key ID parameter.

Note

You can use a period "." or an underscore "_" to group similar parameters. For example, you could group parameters as follows: prod.db.string and prod.domain.password.

After you create a parameter, you can specify it in your SSM documents, commands, or scripts using the following syntax (no space between brackets):

{{ssm:parameter_name}} or {{ ssm:parameter_name }}

Note

The name of a Systems Manager parameter can't be prefixed with "ssm" or "aws," but when you specify the parameter in an SSM document or a command, the syntax includes "ssm", as shown in the following examples

Valid: {{ssm:addUsers}}

Invalid: {{ssm:ssmAddUsers}}.

Create a Systems Manager parameter using the AWS CLI

Use the following procedure to create a parameter that uses either the String or StringList data type. The procedure for creating a SecureString parameter using the AWS CLI is described later in this topic.

Note

Parameters are only available in the Region where they were created.

To create a String or StringList parameter using the AWS CLI

  1. 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
  2. Execute the following command to create a parameter.

    Copy
    aws ssm put-parameter --name "a_name" --value "a value, or a comma-separated list of values" --type String or StringList

    If successful, the command has no output.

    Here is an example that uses the StringList data type.

    Copy
    aws ssm put-parameter --name /IAD/ERP/Oracle/addUsers --value "Milana,Mariana,Mark,Miguel" --type StringList

    Note

    Items in a StringList must be separated by a comma (,). You can't use other punctuation or special character to escape items in the list. If you have a parameter value that requires a comma, then use the String data type.

  3. Execute the following command to verify the details of the parameter.

    Copy
    aws ssm get-parameters --name "the name you specified"

    Here is an example that uses the name specified in the earlier example.

    Copy
    aws ssm get-parameters --name "/IAD/ERP/Oracle/addUsers"

To create a SecureString parameter using the AWS CLI

  1. Open the AWS CLI and run the following command to specify your credentials and a Region. You must either have administrator privileges in Amazon Elastic Compute Cloud (Amazon EC2), or you must have been granted the appropriate permission in IAM. For more information, see Systems Manager Prerequisites.

    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
  2. Execute the following command to create a parameter.

    Copy
    aws ssm put-parameter --name "a_name" --value "a value" --type SecureString --key-id "a custom KMS key ID"

    Note

    To use the default AWS KMS key assigned to your account, remove the key-id parameter from the command.

    Here is an example that uses an obfuscated name (elixir3131) for a password and a custom AWS KMS key.

    Copy
    aws ssm put-parameter --name /Finance/Payroll/elixir3131 --value "P@sSwW)rd" --type SecureString --key-id arn:aws:kms:us-east-1:123456789012:key/1a2b3c4d-1a2b-1a2b-1a2b-1a2b3c4d5e
  3. Execute the following command to verify the details of the parameter.

    Copy
    aws ssm get-parameters --name "the name you specified" --with-decryption

    Note

    If you don't specify the with-decryption parameter, or if you specify the no-with-decryption parameter, the command returns an encrypted GUID.

For more information about using the AWS CLI to create parameters, see Create and Use a Parameter in a Command (AWS CLI).

Create a Systems Manager parameter using AWS Tools for Windows

Use the following procedure to create a parameter that uses either the String or StringList data type. The procedure for creating a SecureString parameter using AWS Tools for Windows is described later in this topic.

Note

Parameters are only available in the Region where they were created.

To create a String or StringList parameter using AWS Tools for Windows

  1. Open AWS Tools for Windows PowerShell and execute the following command to specify your credentials. You must either have administrator privileges in Amazon EC2, or you must have been granted the appropriate permission in IAM. For more information, see Systems Manager Prerequisites.

    Copy
    Set-AWSCredentials –AccessKey key_name –SecretKey key_name
  2. Execute the following command to set the Region for your PowerShell session. The example uses the us-east-2 Region.

    Copy
    Set-DefaultAWSRegion -Region us-east-2
  3. Execute the following command to create a parameter.

    Copy
    Write-SSMParameter -Name "a name" -Value "a value, or a comma-separated list of values" -Type "String or StringList"

    If successful, the command has no output.

    Note

    Items in a StringList must be separated by a comma (,). You can't use other punctuation or special character to escape items in the list. If you have a parameter value that requires a comma, then use the String data type.

    Here is an example that uses a String data type.

    Copy
    Write-SSMParameter -Name "/IAD/Web/SQL/IPaddress" -Value "99.99.99.999" -Type "String"
  4. Execute the following command to verify the details of the parameter.

    Copy
    (Get-SSMParameterValue -Name "the name you specified").Parameters

To create a SecureString parameter using AWS Tools for Windows

  1. Open AWS Tools for Windows PowerShell and execute the following command to specify your credentials. You must either have administrator privileges in Amazon EC2, or you must have been granted the appropriate permission in IAM. For more information, see Systems Manager Prerequisites.

    Copy
    Set-AWSCredentials –AccessKey key_name –SecretKey key_name
  2. Execute the following command to set the Region for your PowerShell session. The example uses the us-east-2 region.

    Copy
    Set-DefaultAWSRegion -Region us-east-2
  3. Execute the following command to create a parameter.

    Copy
    Write-SSMParameter -Name "a name" -Value "a value" -Type "SecureString" -KeyId "a custom KMS key ID"

    If successful, the command has no output.

    Note

    To use the default AWS KMS key assigned to your account, remove the -KeyId parameter from the command.

    Here is an example that uses an obfuscated name (elixir3131) for a password and the user's default KMS key.

    Copy
    Write-SSMParameter -Name "/Finance/Payroll/elixir3131" -Value "P@sSwW)rd" -Type "SecureString"
  4. Execute the following command to verify the details of the parameter.

    Copy
    (Get-SSMParameterValue -Name "the name you specified" –WithDecryption $true).Parameters

Create a Systems Manager Parameter Using the Amazon EC2 Console

Use the following procedure to create a Systems Manager Parameter by using the Amazon EC2 console.

Note

Parameters are only available in the Region where they were created.

To create a parameter using the EC2 console

  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 hierachy and a parameter name. For example, type /Test/helloWorld.

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

  5. For Type, choose String, String List, or Secure String.

  6. In the Value box, type a value. For example, type MyFirstParameter. If you chose Secure String, the value is masked as you type.

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

  8. In the parameters list, choose the parameter you just created. Verify the details on the Description tab. If you created a SecureString parameter, choose Show to view the unencrypted value.

Tagging Systems Manager Parameters

Use the AddTagsToResource API to add tags to resources such as Amazon EC2 instances, Systems Manager Maintenance Windows, and Systems Manager parameters. Tags are used to organize parameters. For example, you can tag parameters for specific environments, departments, or users and groups. After you tag a parameter, you can restrict access to it by creating an IAM policy that specifies the tags that the user can access. For more information about restricting access to parameters by using tags, see Controlling Access to Parameters Using Tags.

For information about the Regions where Systems Manager is available, see regions.

To tag a parameter by using the AWS CLI

  1. 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 IAM. For more information, see Systems Manager Prerequisites.

    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
  2. Execute the following command to list parameters that you can tag.

    Copy
    aws ssm describe-parameters

    Note the name of a parameter that you want to tag.

  3. Execute the following command to tag a parameter.

    Copy
    aws ssm add-tags-to-resource --resource-type "Parameter" --resource-id "the parameter name" --tags "Key=a key, for example Environment,Value=a value, for example TEST"

    If successful, the command has no output.

  4. Execute the following command to verify the parameter tags.

    Copy
    aws ssm list-tags-for-resource --resource-type "Parameter" --resource-id "the parameter name"

To tag a parameter using AWS Tools for Windows

  1. Open AWS Tools for Windows PowerShell and execute the following command to specify your credentials. You must either have administrator privileges in Amazon EC2 or you must have been granted the appropriate permission in IAM. For more information, see Systems Manager Prerequisites.

    Copy
    Set-AWSCredentials –AccessKey key_name –SecretKey key_name
  2. Execute the following command to set the Region for your PowerShell session. The example uses the us-east-2 Region. Systems Manager is currently available in the following regions.

    Copy
    Set-DefaultAWSRegion -Region us-east-2
  3. Execute the following command to list parameters that you can tag.

    Copy
    Get-SSMParameterList
  4. Execute the following commands to tag a parameter.

    Copy
    $tag1 = New-Object Amazon.SimpleSystemsManagement.Model.Tag $tag1.Key = "Environment" $tag1.Value = "TEST" Add-SSMResourceTag -ResourceType "Parameter" -ResourceId "the parameter name" -Tag $tag1

    If successful, the command has no output.

  5. Execute the following command to verify the parameter tags.

    Copy
    Get-SSMResourceTag -ResourceType "Parameter" -ResourceId "the parameter name"