• The AWS Systems Manager CloudWatch Dashboard will no longer be available after April 30, 2026. Customers can continue to use Amazon CloudWatch console to view, create, and manage their Amazon CloudWatch dashboards, just as they do today. For more information, see [Amazon CloudWatch Dashboard documentation](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Dashboards.html).
# AWS Systems Manager Parameter Store
Parameter Store provides secure, hierarchical storage for configuration data management and secrets management. You can store data such as passwords, database strings, Amazon Machine Image (AMI) IDs, and license codes as parameter values. You can store values as plain text or encrypted data. You can reference Systems Manager parameters in your scripts, commands, SSM documents, and configuration and automation workflows by using the unique name that you specified when you created the parameter. To get started with Parameter Store, open the [Systems Manager console](https://console.aws.amazon.com//systems-manager/parameters). In the navigation pane, choose **Parameter Store**.
Parameter Store is also integrated with Secrets Manager. You can retrieve Secrets Manager secrets when using other AWS services that already support references to Parameter Store parameters. For more information, see [Referencing AWS Secrets Manager secrets from Parameter Store parameters](integration-ps-secretsmanager.md).
**Note**
To implement password rotation lifecycles, use AWS Secrets Manager. You can rotate, manage, and retrieve database credentials, API keys, and other secrets throughout their lifecycle using Secrets Manager. For more information, see [What is AWS Secrets Manager?](https://docs.aws.amazon.com//secretsmanager/latest/userguide/intro.html) in the *AWS Secrets Manager User Guide*.
## How can Parameter Store benefit my organization?
Parameter Store offers these benefits:
+ Use a secure, scalable, hosted secrets management service with no servers to manage.
+ Improve your security posture by separating your data from your code.
+ Store configuration data and encrypted strings in hierarchies and track versions.
+ Control and audit access at granular levels.
+ Store parameters reliably because Parameter Store is hosted in multiple Availability Zones in an AWS Region.
## Who should use Parameter Store?
+ Any AWS customer who wants to have a centralized way to manage configuration data.
+ Software developers who want to store different logins and reference streams.
+ Administrators who want to receive notifications when their secrets and passwords are or aren't changed.
## What are the features of Parameter Store?
+ **Change notification**
You can configure change notifications and invoke automated actions for both parameters and parameter policies. For more information, see [Setting up notifications or triggering actions based on Parameter Store events](sysman-paramstore-cwe.md).
+ **Organize parameters**
You can tag your parameters individually to help you identify one or more parameters based on the tags you've assigned to them. For example, you can tag parameters for specific environments or departments.
+ **Label versions**
You can associate an alias for versions of your parameter by creating labels. Labels can help you remember the purpose of a parameter version when there are multiple versions.
+ **Data validation**
You can create parameters that point to an Amazon Elastic Compute Cloud (Amazon EC2) instance and Parameter Store validates these parameters to make sure that it references expected resource type, that the resource exists, and that the customer has permission to use the resource. For example, you can create a parameter with Amazon Machine Image (AMI) ID as a value with `aws:ec2:image` data type, and Parameter Store performs an asynchronous validation operation to make sure that the parameter value meets the formatting requirements for an AMI ID, and that the specified AMI is available in your AWS account.
+ **Reference secrets**
Parameter Store is integrated with AWS Secrets Manager so that you can retrieve Secrets Manager secrets when using other AWS services that already support references to Parameter Store parameters.
+ **Share parameters with other accounts**
You can optionally centralize configuration data in a single AWS account and share parameters with other accounts that need to access them.
+ **Accessible from other AWS services**
You can use Parameter Store parameters with other Systems Manager tools and AWS services to retrieve secrets and configuration data from a central store. Parameters work with Systems Manager tools such as Run Command, Automation, and State Manager, tools in AWS Systems Manager. You can also reference parameters in a number of other AWS services, including the following:
+ Amazon Elastic Compute Cloud (Amazon EC2)
+ Amazon Elastic Container Service (Amazon ECS)
+ AWS Secrets Manager
+ AWS Lambda
+ AWS CloudFormation
+ AWS CodeBuild
+ AWS CodePipeline
+ AWS CodeDeploy
+ **Integrate with other AWS services**
Configure integration with the following AWS services for encryption, notification, monitoring, and auditing:
+ AWS Key Management Service (AWS KMS)
+ Amazon Simple Notification Service (Amazon SNS)
+ Amazon CloudWatch: For more information, see [Configuring EventBridge rules for parameters and parameter policies](sysman-paramstore-cwe.md#cwe-parameter-changes).
+ Amazon EventBridge: For more information, see [Monitoring Systems Manager status changes using Amazon SNS notifications](monitoring-sns-notifications.md) and [Reference: Amazon EventBridge event patterns and types for Systems Manager](reference-eventbridge-events.md).
+ AWS CloudTrail: For more information, see [Logging AWS Systems Manager API calls with AWS CloudTrail](monitoring-cloudtrail-logs.md).
## What is a parameter?
A Parameter Store parameter is any piece of data that is saved in Parameter Store, such as a block of text, a list of names, a password, an AMI ID, a license key, and so on. You can centrally and securely reference this data in your scripts, commands, and SSM documents.
When you reference a parameter, you specify the parameter name by using the following convention.
\$1\$1`ssm:parameter-name`\$1\$1
**Note**
Parameters can't be referenced or nested in the values of other parameters. You can't include `{{}}` or `{{ssm:parameter-name}}` in a parameter value.
Parameter Store provides support for three types of parameters: `String`, `StringList`, and `SecureString`.
With one exception, when you create or update a parameter, you enter the parameter value as plaintext, and Parameter Store performs no validation on the text you enter. For `String` parameters, however, you can specify the data type as `aws:ec2:image`, and Parameter Store validates that the value you enter is the proper format for an Amazon EC2 AMI; for example: `ami-12345abcdeEXAMPLE`.
### Parameter type: String
By default, the value of a `String` parameter consists of any block of text you enter. For example:
+ `abc123`
+ `Example Corp`
+ `
`
### Parameter type: StringList
The values of `StringList` parameters contain a comma-separated list of values, as shown in the following examples.
`Monday,Wednesday,Friday`
`CSV,TSV,CLF,ELF,JSON`
### Parameter type: SecureString
The value of a `SecureString` parameter is any sensitive data that needs to be stored and referenced in a secure manner. If you have data that you don't want users to alter or reference in plaintext, such as passwords or license keys, create those parameters using the `SecureString` data type.
**Important**
Don't store sensitive data in a `String` or `StringList` parameter. For all sensitive data that must remain encrypted, use only the `SecureString` parameter type.
For more information, see [Creating a SecureString parameter using the AWS CLI](param-create-cli.md#param-create-cli-securestring).
We recommend using `SecureString` parameters for the following scenarios:
+ You want to use data/parameters across AWS services without exposing the values as plaintext in commands, functions, agent logs, or CloudTrail logs.
+ You want to control who has access to sensitive data.
+ You want to be able to audit when sensitive data is accessed (CloudTrail).
+ You want to encrypt your sensitive data, and you want to bring your own encryption keys to manage access.
**Important**
Only the *value* of a `SecureString` parameter is encrypted. Parameter names, descriptions, and other properties aren't encrypted.
You can use the `SecureString` parameter type for textual data that you want to encrypt, such as passwords, application secrets, confidential configuration data, or any other types of data that you want to protect. `SecureString` data is encrypted and decrypted using an AWS KMS key. You can use either a default KMS key provided by AWS or create and use your own AWS KMS key. (Use your own AWS KMS key if you want to restrict user access to `SecureString` parameters. For more information, see [IAM permissions for using AWS default keys and customer managed keys](sysman-paramstore-access.md#ps-kms-permissions).)
You can also use `SecureString` parameters with other AWS services. In the following example, the Lambda function retrieves a `SecureString` parameter by using the [GetParameters](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_GetParameters.html) API.
```
import json
import boto3
ssm = boto3.client('ssm', 'us-east-2')
def get_parameters():
response = ssm.get_parameters(
Names=['LambdaSecureString'],WithDecryption=True
)
for parameter in response['Parameters']:
return parameter['Value']
def lambda_handler(event, context):
value = get_parameters()
print("value1 = " + value)
return value # Echo back the first key value
```
**AWS KMS encryption and pricing**
If you choose the `SecureString` parameter type when you create your parameter, Systems Manager uses AWS KMS to encrypt the parameter value.
**Important**
Parameter Store only supports [symmetric encryption KMS keys](https://docs.aws.amazon.com/kms/latest/developerguide/symm-asymm-choose-key-spec.html#symmetric-cmks). You can't use an [asymmetric encryption KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html) to encrypt your parameters. For help determining whether a KMS key is symmetric or asymmetric, see [Identifying symmetric and asymmetric KMS keys](https://docs.aws.amazon.com/kms/latest/developerguide/find-symm-asymm.html) in the *AWS Key Management Service Developer Guide*
There is no charge from Parameter Store to create a `SecureString` parameter, but charges for use of AWS KMS encryption do apply. For information, see [AWS Key Management Service pricing](https://aws.amazon.com/kms/pricing).
For more information about AWS managed keys and customer managed keys, see [AWS Key Management Service Concepts](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html) in the *AWS Key Management Service Developer Guide*. For more information about Parameter Store and AWS KMS encryption, see [How AWS Systems Manager Parameter Store Uses AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/services-parameter-store.html).
**Note**
To view an AWS managed key, use the AWS KMS `DescribeKey` operation. This AWS Command Line Interface (AWS CLI) example uses `DescribeKey` to view an AWS managed key.
```
aws kms describe-key --key-id alias/aws/ssm
```
**More info**
+ [Creating a SecureString parameter in Parameter Store and joining a node to a Domain (PowerShell)](sysman-param-securestring-walkthrough.md)
+ [Use Parameter Store to Securely Access Secrets and Config Data in CodeDeploy](https://aws.amazon.com/blogs/mt/use-parameter-store-to-securely-access-secrets-and-config-data-in-aws-codedeploy/)
+ [Interesting Articles on Amazon EC2 Systems Manager Parameter Store](https://aws.amazon.com/blogs/mt/interesting-articles-on-ec2-systems-manager-parameter-store/)
## Parameter size limits
Parameter Store has different size limits for parameter values depending on the parameter tier you use:
+ **Standard parameters**: Maximum value size of 4 KB
+ **Advanced parameters**: Maximum value size of 8 KB
If you need to store parameter values larger than 4 KB, you must use the advanced parameter tier. Advanced parameters provide additional capabilities but incur charges on your AWS account. For more information about parameter tiers and their features, see [Managing parameter tiers](parameter-store-advanced-parameters.md).
For a complete list of Parameter Store quotas and limits, see [AWS Systems Manager endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/ssm.html#parameter-store) in the *AWS General Reference*.
# Setting up Parameter Store
Before setting up parameters in Parameter Store, configure AWS Identity and Access Management (IAM) policies that provide users in your account with permission to perform the actions you specify.
This section includes information about how to manually configure these policies using the IAM console, and how to assign them to users and user groups. You can also create and assign policies to control which parameter actions can be run on a managed node.
This section also includes information about how to create Amazon EventBridge rules that let you receive notifications about changes to Systems Manager parameters. You can also use EventBridge rules to invoke other actions in AWS based on changes in Parameter Store.
**Topics**
+ [Restricting access to Parameter Store parameters using IAM policies](sysman-paramstore-access.md)
+ [Managing parameter tiers](parameter-store-advanced-parameters.md)
+ [Changing Parameter Store throughput](parameter-store-throughput.md)
+ [Setting up notifications or triggering actions based on Parameter Store events](sysman-paramstore-cwe.md)
# Restricting access to Parameter Store parameters using IAM policies
You restrict access to AWS Systems Manager parameters by using AWS Identity and Access Management (IAM). More specifically, you create IAM policies that restrict access to the following API operations:
+ [DeleteParameter](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_DeleteParameter.html)
+ [DeleteParameters](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_DeleteParameters.html)
+ [DescribeParameters](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_DescribeParameters.html)
+ [GetParameter](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_GetParameter.html)
+ [GetParameters](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_GetParameters.html)
+ [GetParameterHistory](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_GetParameterHistory.html)
+ [GetParametersByPath](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_GetParametersByPath.html)
+ [PutParameter](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_PutParameter.html)
When using IAM policies to restrict access to Systems Manager parameters, we recommend that you create and use *restrictive* IAM policies. For example, the following policy allows a user to call the `DescribeParameters` and `GetParameters` API operations for a limited set of resources. This means that the user can get information about and use all parameters that begin with `prod-*`.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:DescribeParameters"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"ssm:GetParameters"
],
"Resource": "arn:aws:ssm:us-east-1:111122223333:parameter/prod-*"
}
]
}
```
------
**Important**
If a user has access to a path, then the user can access all levels of that path. For example, if a user has permission to access path `/a`, then the user can also access `/a/b`. Even if a user has explicitly been denied access in IAM for parameter `/a/b`, they can still call the `GetParametersByPath` API operation recursively for `/a` and view `/a/b`.
For trusted administrators, you can provide access to all Systems Manager parameter API operations by using a policy similar to the following example. This policy gives the user full access to all production parameters that begin with `dbserver-prod-*`.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:PutParameter",
"ssm:DeleteParameter",
"ssm:GetParameterHistory",
"ssm:GetParametersByPath",
"ssm:GetParameters",
"ssm:GetParameter",
"ssm:DeleteParameters"
],
"Resource": "arn:aws:ssm:us-east-1:111122223333:parameter/dbserver-prod-*"
},
{
"Effect": "Allow",
"Action": "ssm:DescribeParameters",
"Resource": "*"
}
]
}
```
------
## Denying permissions
Each API is unique and has distinct operations and permissions that you can allow or deny individually. An explicit deny in any policy overrides the allow.
**Note**
The default AWS Key Management Service (AWS KMS) key has `Decrypt` permission for all IAM principals within the AWS account. If you want to have different access levels to `SecureString` parameters in your account, we don't recommend that you use the default key.
If you want all API operations retrieving parameter values to have the same behavior, then you can use a pattern like `GetParameter*` in a policy. The following example shows how to deny `GetParameter`, `GetParameters`, `GetParameterHistory`, and `GetParametersByPath` for all parameters beginning with `prod-*`.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Deny",
"Action": [
"ssm:GetParameter*"
],
"Resource": "arn:aws:ssm:us-east-1:111122223333:parameter/prod-*"
}
]
}
```
------
The following example shows how to deny some commands while allowing the user to perform other commands on all parameters that begin with `prod-*`.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Deny",
"Action": [
"ssm:PutParameter",
"ssm:DeleteParameter",
"ssm:DeleteParameters",
"ssm:DescribeParameters"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"ssm:GetParametersByPath",
"ssm:GetParameters",
"ssm:GetParameter",
"ssm:GetParameterHistory"
],
"Resource": "arn:aws:ssm:us-east-1:111122223333:parameter/prod-*"
}
]
}
```
------
**Note**
The parameter history includes all parameter versions, including the current one. Therefore, if a user is denied permission for `GetParameter`, `GetParameters`, and `GetParameterByPath` but is allowed permission for `GetParameterHistory`, they can see the current parameter, including `SecureString` parameters, using `GetParameterHistory`.
## Allowing only specific parameters to run on nodes
You can control access so that managed nodes can run only parameters that you specify.
If you choose the `SecureString` parameter type when you create your parameter, Systems Manager uses AWS KMS to encrypt the parameter value. AWS KMS encrypts the value by using either an AWS managed key or a customer managed key. For more information about AWS KMS and AWS KMS key, see the *[AWS Key Management Service Developer Guide](https://docs.aws.amazon.com/kms/latest/developerguide/)*.
You can view the AWS managed key by running the following command from the AWS CLI.
```
aws kms describe-key --key-id alias/aws/ssm
```
The following example allows nodes to get a parameter value only for parameters that begin with `prod-`. If the parameter is a `SecureString` parameter, then the node decrypts the string using AWS KMS.
**Note**
Instance policies, like in the following example, are assigned to the instance role in IAM. For more information about configuring access to Systems Manager features, including how to assign policies to users and instances, see [Managing EC2 instances with Systems Manager](systems-manager-setting-up-ec2.md).
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:GetParameters"
],
"Resource": [
"arn:aws:ssm:us-east-1:111122223333:parameter/prod-*"
]
},
{
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": [
"arn:aws:kms:us-east-1:111122223333:key/4914ec06-e888-4ea5-a371-5b88eEXAMPLE"
]
}
]
}
```
------
## IAM permissions for using AWS default keys and customer managed keys
Parameter Store `SecureString` parameters are encrypted and decrypted using AWS KMS keys. You can choose to encrypt your `SecureString` parameters using either an AWS KMS key or the default KMS key provided by AWS.
When using a customer managed key, the IAM policy that grants a user access to a parameter or parameter path must provide explicit `kms:Encrypt` permissions for the key. For example, the following policy allows a user to create, update, and view `SecureString` parameters that begin with `prod-` in the specified AWS Region and AWS account.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:PutParameter",
"ssm:GetParameter",
"ssm:GetParameters"
],
"Resource": [
"arn:aws:ssm:us-east-1:111122223333:parameter/prod-*"
]
},
{
"Effect": "Allow",
"Action": [
"kms:Decrypt",
"kms:Encrypt",
"kms:GenerateDataKey"
],
"Resource": [
"arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-12345EXAMPLE"
]
}
]
}
```
------
**Note**
The `kms:GenerateDataKey` permission is required for creating encrypted advanced parameters using the specified customer managed key.
By contrast, all users within the customer account have access to the default AWS managed key. If you use this default key to encrypt `SecureString` parameters and don't want users to work with `SecureString` parameters, their IAM policies must explicitly deny access to the default key, as demonstrated in the following policy example.
**Note**
You can locate the Amazon Resource Name (ARN) of the default key in the AWS KMS console on the [AWS managed keys](https://console.aws.amazon.com/kms/home#/kms/defaultKeys) page. The default key is identified with `aws/ssm` in the **Alias** column.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Deny",
"Action": [
"kms:Decrypt",
"kms:GenerateDataKey"
],
"Resource": [
"arn:aws:kms:us-east-1:111122223333:key/abcd1234-ab12-cd34-ef56-abcdeEXAMPLE"
]
}
]
}
```
------
If you require fine-grained access control over the `SecureString` parameters in your account, you should use a customer managed key to protect and restrict access to these parameters. We also recommend using AWS CloudTrail to monitor `SecureString` parameter activities.
For more information, see the following topics:
+ [Policy evaluation logic](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_evaluation-logic.html) in the *IAM User Guide*
+ [Using key policies in AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html) in the *AWS Key Management Service Developer Guide*
+ [Viewing events with CloudTrail Event history](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/view-cloudtrail-events.html) in the *AWS CloudTrail User Guide*
# Managing parameter tiers
Parameter Store includes *standard parameters * and *advanced parameters*. You individually configure parameters to use either the standard-parameter tier (the default tier) or the advanced-parameter tier.
You can change a standard parameter to an advanced parameter at any time. You *can’t* change an advanced parameter to a standard parameter for the following reasons:
+ Reverting would cause the system to truncate the size of the parameter from 8 KB to 4 KB, resulting in data loss.
+ Reverting would remove policies attached to the parameter.
+ Reverting would change the parameter encryption.
For information about encryption used by Parameter Store, see [How AWS Systems Manager Parameter Store uses AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/services-parameter-store.html) in the *AWS Key Management Service Developer Guide*.
**Note**
If you no longer need an advanced parameter, or if you no longer want to incur charges for an advanced parameter, delete it and recreate it as a new standard parameter.
## Standard and advanced parameters
The following table describes the differences between the tiers.
****
| | Standard | Advanced |
| --- | --- | --- |
| Total number of parameters allowed (per AWS account and AWS Region) | 10,000 | 100,000 |
| Maximum size of a parameter value | 4 KB | 8 KB |
| Parameter policies available | No | Yes For more information, see [Assigning parameter policies in Parameter Store](parameter-store-policies.md). |
| Cost | No additional charge | Charges apply For more information, see [AWS Systems Manager Pricing for Parameter Store](https://aws.amazon.com/systems-manager/pricing/#Parameter_Store). |
**Topics**
+ [Standard and advanced parameters](#parameter-store-advanced-parameters-table)
+ [Specifying a default parameter tier](ps-default-tier.md)
+ [Changing a standard parameter to an advanced parameter](parameter-store-advanced-parameters-enabling.md)
# Specifying a default parameter tier
When creating or updating a parameter using the `[https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_PutParameter.html](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_PutParameter.html)` operation, you can specify the parameter tier. Here is an AWS CLI example.
------
#### [ Linux & macOS ]
```
aws ssm put-parameter \
--name "default-ami" \
--type "String" \
--value "t2.micro" \
--tier "Standard"
```
------
#### [ Windows ]
```
aws ssm put-parameter ^
--name "default-ami" ^
--type "String" ^
--value "t2.micro" ^
--tier "Standard"
```
------
When you specify a tier in a create or update request, Parameter Store uses that tier. If no tier is specified, the default tier setting determines which tier is used.
By default, Parameter Store uses the standard parameter tier. If you enable the advanced parameter tier, you can set one of the following as the default:
+ **Advanced**: All parameters are created as advanced.
+ **Intelligent-Tiering**: Parameter Store evaluates each request and selects the appropriate tier.
With Intelligent-Tiering, Parameter Store creates a parameter in the standard tier unless the request includes options that require the advanced tier. If advanced features are requested, the parameter is created as advanced.
## About the default parameter tier
Be default, when you create a new parameter, Parameter Store assigns it to the Standard tier. Standard parameters are available at no cost, but there are size and feature restrictions, as described in [Standard and advanced parameters](parameter-store-advanced-parameters.md#parameter-store-advanced-parameters-table). If your use cases don't support standard parameters, you can set the Advanced tier as the default. The Advanced tier offers higher limits and extra features, at a cost. For more information, see [AWS Systems Manager Pricing for Parameter Store](https://aws.amazon.com/systems-manager/pricing/#Parameter_Store).
To maximize efficiency and reduce costs, you can set Intelligent-Tiering as the default. This feature determines whether to use the Standard or Advanced tier based on the content of the request. For example, if you run a command to create a parameter that meets all of the criteria for a standard parameter, Intelligent-Tiering creates the parameter in the Standard tier. If you run a command to create a parameter where one or more criteria don't meet the Standard-tier requirements, Intelligent-Tiering creates the parameter in the Advanced tier.
Intelligent-Tiering offers the following benefits:
**Cost control** – Intelligent-Tiering helps control your parameter-related costs by always creating standard parameters unless an advanced parameter is absolutely necessary.
**Automatic upgrade to the advanced-parameter tier** – When you make a change to your code that requires upgrading a standard parameter to an advanced parameter, Intelligent-Tiering handles the conversion for you. You don't need to change your code to handle the upgrade.
Here are some examples of automatic upgrades:
+ Your AWS CloudFormation templates provision numerous parameters when they're run. When this process causes you to reach the 10,000 parameter quota in the standard-parameter tier, Intelligent-Tiering automatically upgrades you to the advanced-parameter tier, and your CloudFormation processes aren't interrupted.
+ You store a certificate value in a parameter, rotate the certificate value regularly, and the content is less than the 4 KB quota of the standard-parameter tier. If a replacement certificate value exceeds 4 KB, Intelligent-Tiering automatically upgrades the parameter to the advanced-parameter tier.
+ You want to associate numerous existing standard parameters to a parameter policy, which requires the advanced-parameter tier. Instead of including the `--tier Advanced` option in calls to update parameters, Intelligent-Tiering automatically upgrades parameters to the advanced tier.
Intelligent-Tiering upgrades parameters from standard to advanced whenever advanced-parameter criteria are introduced.
**Note**
You can change Parameter Store default tier settings at any time.
# Configuring permissions to specify a Parameter Store default tier
Verify that you have permission in AWS Identity and Access Management (IAM) to change the default parameter tier in Parameter Store by doing one of the following:
+ Make sure that you attach the `AdministratorAccess` policy to your IAM entity (such as user, group, or role).
+ Make sure that you have permission to change the default tier setting by using the following API operations:
+ [GetServiceSetting](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_GetServiceSetting.html)
+ [UpdateServiceSetting](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_UpdateServiceSetting.html)
+ [ResetServiceSetting](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_ResetServiceSetting.html)
Grant the following permissions to the IAM entity to allow a user to view and change the default tier setting for parameters in a specific AWS Region in an AWS account.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:GetServiceSetting"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"ssm:UpdateServiceSetting"
],
"Resource": "arn:aws:ssm:us-east-1:111122223333:servicesetting/ssm/parameter-store/default-parameter-tier"
}
]
}
```
------
Administrators can specify read-only permission by assigning the following permissions.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:GetServiceSetting"
],
"Resource": "*"
},
{
"Effect": "Deny",
"Action": [
"ssm:ResetServiceSetting",
"ssm:UpdateServiceSetting"
],
"Resource": "*"
}
]
}
```
------
To provide access, add permissions to your users, groups, or roles:
+ Users and groups in AWS IAM Identity Center:
Create a permission set. Follow the instructions in [Create a permission set](https://docs.aws.amazon.com//singlesignon/latest/userguide/howtocreatepermissionset.html) in the *AWS IAM Identity Center User Guide*.
+ Users managed in IAM through an identity provider:
Create a role for identity federation. Follow the instructions in [Create a role for a third-party identity provider (federation)](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-idp.html) in the *IAM User Guide*.
+ IAM users:
+ Create a role that your user can assume. Follow the instructions in [Create a role for an IAM user](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-user.html) in the *IAM User Guide*.
+ (Not recommended) Attach a policy directly to a user or add a user to a user group. Follow the instructions in [Adding permissions to a user (console)](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_users_change-permissions.html#users_change_permissions-add-console) in the *IAM User Guide*.
# Specifying or changing the Parameter Store default tier using the console
The following procedure shows how to use the Systems Manager console to specify or change the default parameter tier for the current AWS account and AWS Region.
**Tip**
If you haven't created a parameter yet, you can use the AWS Command Line Interface (AWS CLI) or AWS Tools for Windows PowerShell to change the default parameter tier. For information, see [Specifying or changing the Parameter Store default tier using the AWS CLI](parameter-store-tier-changing-cli.md) and [Specifying or changing the Parameter Store default tier (PowerShell)](parameter-store-tier-changing-ps.md).
**To specify or change the Parameter Store default tier**
1. Open the AWS Systems Manager console at [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. In the navigation pane, choose **Parameter Store**.
1. Choose the **Settings** tab.
1. Choose **Manage settings**.
1. In the **Parameter default tier** section, choose an option. For information about these options, see [Specifying a default parameter tier](ps-default-tier.md).
1. If prompted, select the option to approve the changes and authorize charges. Choose **Save settings**.
If you want to change the default tier setting later, repeat this procedure and specify a different default tier option.
# Specifying or changing the Parameter Store default tier using the AWS CLI
The following procedure shows how to use the AWS CLI to change the default parameter tier setting for the current AWS account and AWS Region.
**To specify or change the Parameter Store default tier using the AWS CLI**
1. Open the AWS CLI and run the following command to change the default parameter tier setting for a specific AWS Region in an AWS account.
```
aws ssm update-service-setting --setting-id arn:aws:ssm:region:account-id:servicesetting/ssm/parameter-store/default-parameter-tier --setting-value tier-option
```
*region* represents the identifier for an AWS Region supported by AWS Systems Manager, such as `us-east-2` for the US East (Ohio) Region. For a list of supported *region* values, see the **Region** column in [Systems Manager service endpoints](https://docs.aws.amazon.com/general/latest/gr/ssm.html#ssm_region) in the *Amazon Web Services General Reference*.
*tier-option* values include `Standard`, `Advanced`, and `Intelligent-Tiering`. For information about these options, see [Specifying a default parameter tier](ps-default-tier.md).
There is no output if the command succeeds.
1. Run the following command to view the current default parameter tier service settings for Parameter Store in the current AWS account and AWS Region.
```
aws ssm get-service-setting --setting-id arn:aws:ssm:region:account-id:servicesetting/ssm/parameter-store/default-parameter-tier
```
The system returns information similar to the following.
```
{
"ServiceSetting": {
"SettingId": "/ssm/parameter-store/default-parameter-tier",
"SettingValue": "Advanced",
"LastModifiedDate": 1556551683.923,
"LastModifiedUser": "arn:aws:sts::123456789012:assumed-role/Administrator/Jasper",
"ARN": "arn:aws:ssm:us-east-2:123456789012:servicesetting/ssm/parameter-store/default-parameter-tier",
"Status": "Customized"
}
}
```
If you want to change the default tier setting again, repeat this procedure and specify a different `SettingValue` option.
# Specifying or changing the Parameter Store default tier (PowerShell)
The following procedure shows how to use the Tools for Windows PowerShell to change the default parameter tier setting for a specific AWS Region in an Amazon Web Services account.
**To specify or change the Parameter Store default tier using PowerShell**
1. Change the Parameter Store default tier in the current AWS account and AWS Region using the AWS Tools for PowerShell (Tools for PowerShell).
```
Update-SSMServiceSetting -SettingId "arn:aws:ssm:region:account-id:servicesetting/ssm/parameter-store/default-parameter-tier" -SettingValue "tier-option" -Region region
```
*region* represents the identifier for an AWS Region supported by AWS Systems Manager, such as `us-east-2` for the US East (Ohio) Region. For a list of supported *region* values, see the **Region** column in [Systems Manager service endpoints](https://docs.aws.amazon.com/general/latest/gr/ssm.html#ssm_region) in the *Amazon Web Services General Reference*.
*tier-option* values include `Standard`, `Advanced`, and `Intelligent-Tiering`. For information about these options, see [Specifying a default parameter tier](ps-default-tier.md).
There is no output if the command succeeds.
1. Run the following command to view the current default parameter tier service settings for Parameter Store in the current AWS account and AWS Region.
```
Get-SSMServiceSetting -SettingId "arn:aws:ssm:region:account-id:servicesetting/ssm/parameter-store/default-parameter-tier" -Region region
```
*region* represents the identifier for an AWS Region supported by AWS Systems Manager, such as `us-east-2` for the US East (Ohio) Region. For a list of supported *region* values, see the **Region** column in [Systems Manager service endpoints](https://docs.aws.amazon.com/general/latest/gr/ssm.html#ssm_region) in the *Amazon Web Services General Reference*.
The system returns information similar to the following.
```
ARN : arn:aws:ssm:us-east-2:123456789012:servicesetting/ssm/parameter-store/default-parameter-tier
LastModifiedDate : 4/29/2019 3:35:44 PM
LastModifiedUser : arn:aws:sts::123456789012:assumed-role/Administrator/Jasper
SettingId : /ssm/parameter-store/default-parameter-tier
SettingValue : Advanced
Status : Customized
```
If you want to change the default tier setting again, repeat this procedure and specify a different `SettingValue` option.
# Changing a standard parameter to an advanced parameter
Use the following procedure to change an existing standard parameter to an advanced parameter. For information about how to create a new advanced parameter, see [Creating Parameter Store parameters in Systems Manager](sysman-paramstore-su-create.md).
**To change a standard parameter to an advanced parameter**
1. Open the AWS Systems Manager console at [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. In the navigation pane, choose **Parameter Store**.
1. Choose a parameter, and then choose **Edit**.
1. For **Description**, enter information about this parameter.
1. Choose **Advanced**.
1. For **Value**, enter the value of this parameter. Advanced parameters have a maximum value limit of 8 KB.
1. Choose **Save changes**.
# Changing Parameter Store throughput
Parameter Store throughput defines the number of API transactions per second (TPS) that Systems Manager can process for [GetParameter](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_GetParameter.html), [GetParameters](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_GetParameters.html), and [PutParameter](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_PutParameter.html) API calls for your AWS account and Region. By default, Parameter Store is configured with a standard throughput quota suitable for low- to moderate-volume workloads. Applications that retrieve configuration data infrequently or operate at smaller scale can typically use this default setting without additional cost.
For higher-volume workloads, you can enable higher throughput, which increases the maximum number of supported transactions per second for your account and Region, at a cost. Increased throughput allows you to operate Parameter Store at higher volumes to support applications and workloads that need concurrent access to multiple parameters. If you're experiencing `ThrottlingException: Rate exceeded` errors, we recommend enabling higher throughput.
Throughput operates independently of parameter tiers, but the two are often used together to meet performance and scale requirements:
Standard parameters (default tier) are designed for most workloads. They support up to 10,000 parameters per Region, with values up to 4 KB, and incur no additional storage cost. Advanced parameters support larger values (up to 8 KB), higher parameter counts (up to 100,000), and additional features such as parameter policies. These capabilities come with additional charges.
While parameter tiers control storage limits and feature availability, throughput settings control request volume. For example, you might use standard parameters with default throughput for simple applications, or combine advanced parameters with higher throughput to support large-scale, high-frequency access patterns. In general, increasing throughput is necessary when your application exceeds default TPS limits (for example, during bursts of concurrent reads or writes), regardless of which parameter tier you use.
You can enable or disable higher throughput at any time from the Parameter Store **Settings** page or by using the AWS CLI.
For more information about maximum throughput and other Parameter Store quotas, see [AWS Systems Manager endpoints and quotas](https://docs.aws.amazon.com//general/latest/gr/ssm.html#limits_ssm).
**Important**
Increasing the throughput quota incurs a charge on your AWS account. For more information, see [AWS Systems Manager Pricing](https://aws.amazon.com/systems-manager/pricing/).
**Topics**
+ [Increasing throughput using the console](#parameter-store-throughput-increasing)
+ [Increasing throughput using the AWS CLI](#parameter-store-throughput-increasing-cli)
+ [Increasing throughput (PowerShell)](#parameter-store-throughput-increasing-ps)
## Increasing throughput using the console
The following procedure describes how to use the Systems Manager console to increase the number of transactions per second that Parameter Store can process for the current AWS account and AWS Region.
**To increase Parameter Store throughput using the console**
**Tip**
If you haven't created a parameter yet, you can use the AWS Command Line Interface (AWS CLI) or AWS Tools for Windows PowerShell to increase throughput. For information, see [Increasing throughput using the AWS CLI](#parameter-store-throughput-increasing-cli) and [Increasing throughput (PowerShell)](#parameter-store-throughput-increasing-ps).
1. Open the AWS Systems Manager console at [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. In the navigation pane, choose **Parameter Store**.
1. Choose the **Settings** tab.
1. Choose the **Manage settings**.
1. In the **Parameter throughput** section, choose an option.
1. If prompted, select the option to approve the changes and authorize charges. Choose **Save settings**.
## Increasing throughput using the AWS CLI
The following procedure shows how to use the AWS CLI to increase the number of transactions per second that Parameter Store can process for the current AWS account and AWS Region.
**To increase Parameter Store throughput using the AWS CLI**
1. Open the AWS CLI and run the following command to increase the transactions per second that Parameter Store can process in the current AWS account and AWS Region.
```
aws ssm update-service-setting --setting-id arn:aws:ssm:region:account-id:servicesetting/ssm/parameter-store/high-throughput-enabled --setting-value true
```
There is no output if the command succeeds.
1. Run the following command to view the current throughput service settings for Parameter Store in the current AWS account and AWS Region.
```
aws ssm get-service-setting --setting-id arn:aws:ssm:region:account-id:servicesetting/ssm/parameter-store/high-throughput-enabled
```
The system returns information similar to the following:
```
{
"ServiceSetting": {
"SettingId": "/ssm/parameter-store/high-throughput-enabled",
"SettingValue": "true",
"LastModifiedDate": 1556551683.923,
"LastModifiedUser": "arn:aws:sts::123456789012:assumed-role/Administrator/Jasper",
"ARN": "arn:aws:ssm:us-east-2:123456789012:servicesetting/ssm/parameter-store/high-throughput-enabled",
"Status": "Customized"
}
}
```
## Increasing throughput (PowerShell)
The following procedure shows how to use the Tools for Windows PowerShell to increase the number of transactions per second that Parameter Store can process for the current AWS account and AWS Region.
**To increase Parameter Store throughput using PowerShell**
1. Increase Parameter Store throughput in the current AWS account and AWS Region using the AWS Tools for PowerShell (Tools for PowerShell).
```
Update-SSMServiceSetting -SettingId "arn:aws:ssm:region:account-id:servicesetting/ssm/parameter-store/high-throughput-enabled" -SettingValue "true" -Region region
```
There is no output if the command succeeds.
1. Run the following command to view the current throughput service settings for Parameter Store in the current AWS account and AWS Region.
```
Get-SSMServiceSetting -SettingId "arn:aws:ssm:region:account-id:servicesetting/ssm/parameter-store/high-throughput-enabled" -Region region
```
The systems returns information similar to the following:
```
ARN : arn:aws:ssm:us-east-2:123456789012:servicesetting/ssm/parameter-store/high-throughput-enabled
LastModifiedDate : 4/29/2019 3:35:44 PM
LastModifiedUser : arn:aws:sts::123456789012:assumed-role/Administrator/Jasper
SettingId : /ssm/parameter-store/high-throughput-enabled
SettingValue : true
Status : Customized
```
# Setting up notifications or triggering actions based on Parameter Store events
The topics in this section explain how to use Amazon EventBridge and Amazon Simple Notification Service (Amazon SNS) to notify you about changes to AWS Systems Manager parameters. You can create an EventBridge rule to notify you when a parameter or a parameter label version is created, updated, or deleted. Events are emitted on a best effort basis. You can be notified about changes or status related to parameter policies, such as when a parameter expires, is going to expire, or hasn't changed for a specified period of time.
**Note**
Parameter policies are available for parameters that use the advanced parameters tier. Charges apply. For more information, see [Assigning parameter policies in Parameter Store](parameter-store-policies.md) and [Managing parameter tiers](parameter-store-advanced-parameters.md).
The topics in this section also explain how to initiate other actions on a target for specific parameter events. For example, you can run an AWS Lambda function to recreate a parameter automatically when it expires or is deleted. You can set up a notification to invoke a Lambda function when your database password is updated. The Lambda function can force your database connections to reset or reconnect with the new password. EventBridge also supports running Run Command commands and Automation executions, and actions in many other AWS services. Run Command and Automation are both tools in AWS Systems Manager. For more information, see the *[Amazon EventBridge User Guide](https://docs.aws.amazon.com/eventbridge/latest/userguide/)*.
**Before You Begin**
Create any resources you need to specify the target action for the rule you create. For example, if the rule you create is for sending a notification, first create an Amazon SNS topic. For more information, see [Getting started with Amazon SNS](https://docs.aws.amazon.com/sns/latest/dg/sns-getting-started.htmlGettingStarted.html) in the *Amazon Simple Notification Service Developer Guide*.
## Configuring EventBridge rules for parameters and parameter policies
This topic explains the following:
+ How to create an EventBridge rule that invokes a target based on events that happen to one or more parameters in your AWS account.
+ How to create EventBridge rules that invoke targets based on events that happen to one or more parameter policies in your AWS account. When you create an advanced parameter, you specify when a parameter expires, when to receive notification before a parameter expires, and how long to wait before notification should be sent that a parameter hasn't changed. You set up notification for these events using the following procedure. For more information, see [Assigning parameter policies in Parameter Store](parameter-store-policies.md) and [Managing parameter tiers](parameter-store-advanced-parameters.md).
**To configure an EventBridge rule for a Systems Manager parameter or parameter policy**
1. Open the Amazon EventBridge console at [https://console.aws.amazon.com/events/](https://console.aws.amazon.com/events/).
1. In the navigation pane, choose **Rules**, and then choose **Create rule**.
-or-
If the EventBridge home page opens first, choose **Create rule**.
1. Enter a name and description for the rule.
A rule can't have the same name as another rule in the same Region and on the same event bus.
1. For **Event bus**, choose the event bus that you want to associate with this rule. If you want this rule to initiate on matching events that come from your own AWS account, select **default **. When an AWS service in your account emits an event, it always goes to your account’s default event bus.
1. For **Rule type**, leave the default **Rule with an event pattern** selected.
1. Choose **Next**.
1. For **Event source**, leave the default **AWS events or EventBridge partner events** selected. You can skip the **Sample event** section.
1. For **Event pattern**, do the following:
+ Choose **Custom patterns (JSON editor)**.
+ For **Event pattern**, paste one of the following content in the box, depending on whether you are creating a rule for a parameter or a parameter policy:
------
#### [ Parameter ]
```
{
"source": [
"aws.ssm"
],
"detail-type": [
"Parameter Store Change"
],
"detail": {
"name": [
"parameter-1-name",
"/parameter-2-name/level-2",
"/parameter-3-name/level-2/level-3"
],
"operation": [
"Create",
"Update",
"Delete",
"LabelParameterVersion"
]
}
}
```
------
#### [ Parameter policy ]
```
{
"source": [
"aws.ssm"
],
"detail-type": [
"Parameter Store Policy Action"
],
"detail": {
"parameter-name": [
"parameter-1-name",
"/parameter-2-name/level-2",
"/parameter-3-name/level-2/level-3"
],
"policy-type": [
"Expiration",
"ExpirationNotification",
"NoChangeNotification"
]
}
}
```
------
+ Modify the contents for the parameters and the operations you want to act on, as shown in the following samples.
------
#### [ Parameter ]
With this example, an action is taken when either of the parameters named /`Oncall` and `/Project/Teamlead` are updated:
```
{
"source": [
"aws.ssm"
],
"detail-type": [
"Parameter Store Change"
],
"detail": {
"name": [
"/Oncall",
"/Project/Teamlead"
],
"operation": [
"Update"
]
}
}
```
------
#### [ Parameter policy ]
With this example, an action is taken whenever the parameter named /`OncallDuties` expires and is deleted:
```
{
"source": [
"aws.ssm"
],
"detail-type": [
"Parameter Store Policy Action"
],
"detail": {
"parameter-name": [
"/OncallDuties"
],
"policy-type": [
"Expiration"
]
}
}
```
------
1. Choose **Next**.
1. For **Target 1**, choose a target type and a supported resource. For example, if you choose **SNS topic**, make a selection for **Topic**. If you choose **CodePipeline**, enter a pipeline ARN for **Pipeline ARN**. Provide additional configuration values as required.
**Tip**
Choose **Add another target** if you require additional targets for the rule.
1. Choose **Next**.
1. (Optional) Enter one or more tags for the rule. For more information, see [Amazon EventBridge tags](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-tagging.html) in the *Amazon EventBridge User Guide*.
1. Choose **Next**.
1. Choose **Create rule**.
**More info**
+ [Use parameter labels for easy configuration update across environments](https://aws.amazon.com/blogs/mt/use-parameter-labels-for-easy-configuration-update-across-environments/)
+ [Tutorial: Use EventBridge to relay events to AWS Systems Manager Run Command](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-ec2-run-command.html) in the *Amazon EventBridge User Guide*
+ [Tutorial: Set AWS Systems Manager Automation as an EventBridge target](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-ssm-automation-as-target.html) in the *Amazon EventBridge User Guide*
# Working with Parameter Store
This section describes how to organize and create tag parameters, and how to create different versions of parameters.
You can use the AWS Systems Manager console, the AWS Command Line Interface (AWS CLI), the AWS Tools for PowerShell, and the AWS SDKs to create and work with parameters. For more information about parameters, see [What is a parameter?](systems-manager-parameter-store.md#what-is-a-parameter).
**Topics**
+ [Creating Parameter Store parameters in Systems Manager](sysman-paramstore-su-create.md)
+ [Searching for Parameter Store parameters in Systems Manager](parameter-search.md)
+ [Assigning parameter policies in Parameter Store](parameter-store-policies.md)
+ [Working with parameter hierarchies in Parameter Store](sysman-paramstore-hierarchies.md)
+ [Preventing access to Parameter Store API operations](parameter-store-policy-conditions.md)
+ [Working with parameter labels in Parameter Store](sysman-paramstore-labels.md)
+ [Working with parameter versions in Parameter Store](sysman-paramstore-versions.md)
+ [Working with shared parameters in Parameter Store](parameter-store-shared-parameters.md)
+ [Working with parameters in Parameter Store using Run Command commands](sysman-param-runcommand.md)
+ [Using native parameter support in Parameter Store for Amazon Machine Image IDs](parameter-store-ec2-aliases.md)
+ [Deleting parameters from Parameter Store](deleting-parameters.md)
# Creating Parameter Store parameters in Systems Manager
Use the information in the following topics to help you create Systems Manager parameters using the AWS Systems Manager console, the AWS Command Line Interface (AWS CLI), or AWS Tools for Windows PowerShell (Tools for Windows PowerShell).
This section demonstrates how to create, store, and run parameters with Parameter Store in a test environment. It also demonstrates how to use Parameter Store with other Systems Manager tools in AWS services. For more information, see [What is a parameter?](systems-manager-parameter-store.md#what-is-a-parameter)
## Understanding requirements and constraints for parameter names
Use the information in this topic to help you specify valid values for parameter names when you create a parameter.
This information supplements the details in the topic [PutParameter](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_PutParameter.html) in the *AWS Systems Manager API Reference*, which also provides information about the values **AllowedPattern**, **Description**, **KeyId**, **Overwrite**, **Type**, and **Value**.
The requirements and constraints for parameter names include the following:
+ **Case sensitivity**: Parameter names are case sensitive.
+ **Spaces**: Parameter names can't include spaces.
+ **Valid characters**: Parameter names can consist of the following symbols and letters only: `a-zA-Z0-9_.-`
In addition, the slash character ( / ) is used to delineate hierarchies in parameter names. For example: `/Dev/Production/East/Project-ABC/MyParameter`
+ **Valid AMI format**: When you choose `aws:ec2:image` as the data type for a `String` parameter, the ID you enter must validate for the AMI ID format `ami-12345abcdeEXAMPLE`.
+ **Fully qualified**: When you create or reference a parameter in a hierarchy, include a leading forward slash character (/) . When you reference a parameter that is part of a hierarchy, specify the entire hierarchy path including the initial slash (/).
+ Fully qualified parameter names: `MyParameter1`, `/MyParameter2`, `/Dev/Production/East/Project-ABC/MyParameter`
+ Not fully qualified parameter name: `MyParameter3/L1`
+ **Length**: The maximum length for a parameter name that you specify is 1011 characters. This count of 1011 characters includes the characters in the ARN that precede the name you specify, such as the 45 characters in `arn:aws:ssm:us-east-2:111122223333:parameter/`.
+ **Prefixes**: A parameter name can't be prefixed with "`aws`" or "`ssm`" (case-insensitive). For example, attempts to create parameters with the following names fail with an exception:
+ `awsTestParameter`
+ `SSM-testparameter`
+ `/aws/testparam1`
**Note**
When you specify a parameter in an SSM document, command, or script, include `ssm` as part of the syntax. For example, \$1\$1ssm:*parameter-name*\$1\$1 and \$1\$1 ssm:*parameter-name* \$1\$1, such as `{{ssm:MyParameter}}`, and `{{ ssm:MyParameter }}.`
+ **Uniqueness**: A parameter name must be unique within an AWS Region. For example, Systems Manager treats the following as separate parameters, if they exist in the same Region:
+ `/Test/TestParam1`
+ `/TestParam1`
The following examples are also unique:
+ `/Test/TestParam1/Logpath1`
+ `/Test/TestParam1`
The following examples, however, if in the same Region, aren't unique:
+ `/TestParam1`
+ `TestParam1`
+ **Hierarchy depth**: If you specify a parameter hierarchy, the hierarchy can have a maximum depth of fifteen levels. You can define a parameter at any level of the hierarchy. Both of the following examples are structurally valid:
+ `/Level-1/L2/L3/L4/L5/L6/L7/L8/L9/L10/L11/L12/L13/L14/parameter-name`
+ `parameter-name`
Attempting to create the following parameter would fail with a `HierarchyLevelLimitExceededException` exception:
+ `/Level-1/L2/L3/L4/L5/L6/L7/L8/L9/L10/L11/L12/L13/L14/L15/L16/parameter-name`
**Important**
If a user has access to a path, then the user can access all levels of that path. For example, if a user has permission to access path `/a`, then the user can also access `/a/b`. Even if a user has explicitly been denied access in AWS Identity and Access Management (IAM) for parameter `/a/b`, they can still call the [GetParametersByPath](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_GetParametersByPath.html) API operation recursively for `/a` and view `/a/b`.
**Topics**
+ [Understanding requirements and constraints for parameter names](#sysman-parameter-name-constraints)
+ [Creating a Parameter Store parameter using the console](parameter-create-console.md)
+ [Creating a Parameter Store parameter using the AWS CLI](param-create-cli.md)
+ [Creating a Parameter Store parameter using Tools for Windows PowerShell](param-create-ps.md)
# Creating a Parameter Store parameter using the console
You can use the AWS Systems Manager console to create and run `String`, `StringList`, and `SecureString` parameter types. After deleting a parameter, wait for at least 30 seconds to create a parameter with the same name.
**Note**
Parameters are only available in the AWS Region where they were created.
The following procedure walks you through the process of creating a parameter in the Parameter Store console. You can create `String`, `StringList`, and `SecureString` parameter types from the console.
**To create a parameter**
1. Open the AWS Systems Manager console at [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. In the navigation pane, choose **Parameter Store**.
1. Choose **Create parameter**.
1. In the **Name** box, enter a hierarchy and a name. For example, enter **/Test/helloWorld**.
For more information about parameter hierarchies, see [Working with parameter hierarchies in Parameter Store](sysman-paramstore-hierarchies.md).
1. In the **Description** box, type a description that identifies this parameter as a test parameter.
1. For **Parameter tier** choose either **Standard** or **Advanced**. For more information about advanced parameters, see [Managing parameter tiers](parameter-store-advanced-parameters.md).
1. For **Type**, choose **String**, **StringList**, or **SecureString**.
+ If you choose **String**, the **Data type** field is displayed. If you're creating a parameter to hold the resource ID for an Amazon Machine Image (AMI), select `aws:ec2:image`. Otherwise, keep the default `text` selected.
+ If you choose **SecureString,** the **KMS Key ID** field is displayed. If you don't provide an AWS Key Management Service AWS KMS key ID, an AWS KMS key Amazon Resource Name (ARN), an alias name, or an alias ARN, then the system uses `alias/aws/ssm`, which is the AWS managed key for Systems Manager. If you don't want to use this key, then you can use a customer managed key. For more information about AWS managed keys and customer managed keys, see [AWS Key Management Service Concepts](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html) in the *AWS Key Management Service Developer Guide*. For more information about Parameter Store and AWS KMS encryption, see [How AWS Systems Manager Parameter Store Uses AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/services-parameter-store.html).
**Important**
Parameter Store only supports [symmetric encryption KMS keys](https://docs.aws.amazon.com/kms/latest/developerguide/symm-asymm-choose-key-spec.html#symmetric-cmks). You can't use an [asymmetric encryption KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html) to encrypt your parameters. For help determining whether a KMS key is symmetric or asymmetric, see [Identifying symmetric and asymmetric KMS keys](https://docs.aws.amazon.com/kms/latest/developerguide/find-symm-asymm.html) in the *AWS Key Management Service Developer Guide*
+ When creating a `SecureString` parameter in the console by using the `key-id` parameter with either a customer managed key alias name or an alias ARN, specify the prefix `alias/` before the alias. Following is an ARN example.
```
arn:aws:kms:us-east-2:123456789012:alias/abcd1234-ab12-cd34-ef56-abcdeEXAMPLE
```
Following is an alias name example.
```
alias/MyAliasName
```
1. In the **Value** box, type a value. For example, type **This is my first parameter** or **ami-0dbf5ea29aEXAMPLE**.
**Note**
Parameters can't be referenced or nested in the values of other parameters. You can't include `{{}}` or `{{ssm:parameter-name}}` in a parameter value.
If you chose **SecureString**, the value of the parameter is masked by default ("\$1\$1\$1\$1\$1\$1") when you view it later on the parameter **Overview** tab, as shown in the following illlustration. Choose **Show** to display the parameter value.
![\[A SecureString parameter's value is masked with the option to display the value.\]](http://docs.aws.amazon.com/systems-manager/latest/userguide/images/ps-overview-show-secstring.png)
1. (Optional) In the **Tags** area, apply one or more tag key-value pairs to the parameter.
Tags are optional metadata that you assign to a resource. Tags allow you to categorize a resource in different ways, such as by purpose, owner, or environment. For example, you might want to tag a Systems Manager parameter to identify the type of resource to which it applies, the environment, or the type of configuration data referenced by the parameter. In this case, you could specify the following key-value pairs:
+ `Key=Resource,Value=S3bucket`
+ `Key=OS,Value=Windows`
+ `Key=ParameterType,Value=LicenseKey`
1. Choose **Create parameter**.
1. In the parameters list, choose the name of the parameter you just created. Verify the details on the **Overview** tab. If you created a `SecureString` parameter, choose **Show** to view the unencrypted value.
**Note**
You can’t change an advanced parameter to a standard parameter. If you no longer need an advanced parameter, or if you no longer want to incur charges for an advanced parameter, delete it and recreate it as a new standard parameter.
**Note**
You can't change the type of an existing parameter (for example, from `String` to `SecureString`) using the console. To change a parameter's type, you must use the AWS CLI or s with the `--overwrite` option. For more information, see [Creating a Parameter Store parameter using the AWS CLI](param-create-cli.md).
# Creating a Parameter Store parameter using the AWS CLI
You can use the AWS Command Line Interface (AWS CLI) to create `String`, `StringList`, and `SecureString` parameter types. After deleting a parameter, wait for at least 30 seconds to create a parameter with the same name.
Parameters can't be referenced or nested in the values of other parameters. You can't include `{{}}` or `{{ssm:parameter-name}}` in a parameter value.
**Note**
Parameters are only available in the AWS Region where they were created.
**Topics**
+ [Creating a `String` parameter using the AWS CLI](#param-create-cli-string)
+ [Creating a StringList parameter using the AWS CLI](#param-create-cli-stringlist)
+ [Creating a SecureString parameter using the AWS CLI](#param-create-cli-securestring)
+ [Creating a multi-line parameter using the AWS CLI](#param-create-cli-multiline)
## Creating a `String` parameter using the AWS CLI
1. Install and configure the AWS Command Line Interface (AWS CLI), if you haven't already.
For information, see [Installing or updating the latest version of the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
1. Run the following command to create a `String`-type parameter. Replace each *example resource placeholder* with your own information.
------
#### [ Linux & macOS ]
```
aws ssm put-parameter \
--name "parameter-name" \
--value "parameter-value" \
--type String \
--tags "Key=tag-key,Value=tag-value"
```
------
#### [ Windows ]
```
aws ssm put-parameter ^
--name "parameter-name" ^
--value "parameter-value" ^
--type String ^
--tags "Key=tag-key,Value=tag-value"
```
------
-or-
Run the following command to create a parameter that contains an Amazon Machine Image (AMI) ID as the parameter value.
------
#### [ Linux & macOS ]
```
aws ssm put-parameter \
--name "parameter-name" \
--value "an-AMI-id" \
--type String \
--data-type "aws:ec2:image" \
--tags "Key=tag-key,Value=tag-value"
```
------
#### [ Windows ]
```
aws ssm put-parameter ^
--name "parameter-name" ^
--value "an-AMI-id" ^
--type String ^
--data-type "aws:ec2:image" ^
--tags "Key=tag-key,Value=tag-value"
```
------
The `--name` option supports hierarchies. For information about hierarchies, see [Working with parameter hierarchies in Parameter Store](sysman-paramstore-hierarchies.md).
The `--data-type` option must be specified only if you are creating a parameter that contains an AMI ID. It validates that the parameter value you enter is a properly formatted Amazon Elastic Compute Cloud (Amazon EC2) AMI ID. For all other parameters, the default data type is `text` and it's optional to specify a value. For more information, see [Using native parameter support in Parameter Store for Amazon Machine Image IDs](parameter-store-ec2-aliases.md).
**Important**
If successful, the command returns the version number of the parameter. **Exception**: If you have specified `aws:ec2:image` as the data type, a new version number in the response doesn't mean that the parameter value has been validated yet. For more information, see [Using native parameter support in Parameter Store for Amazon Machine Image IDs](parameter-store-ec2-aliases.md).
The following example adds two key-value pair tags to a parameter.
------
#### [ Linux & macOS ]
```
aws ssm put-parameter \
--name parameter-name \
--value "parameter-value" \
--type "String" \
--tags '[{"Key":"Region","Value":"East"},{"Key":"Environment", "Value":"Production"}]'
```
------
#### [ Windows ]
```
aws ssm put-parameter ^
--name parameter-name ^
--value "parameter-value" ^
--type "String" ^
--tags [{\"Key\":\"Region1\",\"Value\":\"East1\"},{\"Key\":\"Environment1\",\"Value\":\"Production1\"}]
```
------
The following example uses a parameter hierarchy in the name to create a plaintext `String` parameter. It returns the version number of the parameter. For more information about parameter hierarchies, see [Working with parameter hierarchies in Parameter Store](sysman-paramstore-hierarchies.md).
------
#### [ Linux & macOS ]
**Parameter not in a hierarchy**
```
aws ssm put-parameter \
--name "golden-ami" \
--type "String" \
--value "ami-12345abcdeEXAMPLE"
```
**Parameter in a hierarchy**
```
aws ssm put-parameter \
--name "/amis/linux/golden-ami" \
--type "String" \
--value "ami-12345abcdeEXAMPLE"
```
------
#### [ Windows ]
**Parameter not in a hierarchy**
```
aws ssm put-parameter ^
--name "golden-ami" ^
--type "String" ^
--value "ami-12345abcdeEXAMPLE"
```
**Parameter in a hierarchy**
```
aws ssm put-parameter ^
--name "/amis/windows/golden-ami" ^
--type "String" ^
--value "ami-12345abcdeEXAMPLE"
```
------
1. Run the following command to view the latest parameter value and verify the details of your new parameter.
```
aws ssm get-parameters --names "/Test/IAD/helloWorld"
```
The system returns information like the following.
```
{
"InvalidParameters": [],
"Parameters": [
{
"Name": "/Test/IAD/helloWorld",
"Type": "String",
"Value": "My updated parameter value",
"Version": 2,
"LastModifiedDate": "2020-02-25T15:55:33.677000-08:00",
"ARN": "arn:aws:ssm:us-east-2:123456789012:parameter/Test/IAD/helloWorld"
}
]
}
```
Run the following command to change the parameter value. It returns the version number of the parameter.
```
aws ssm put-parameter --name "/Test/IAD/helloWorld" --value "My updated 1st parameter" --type String --overwrite
```
Run the following command to view the parameter value history.
```
aws ssm get-parameter-history --name "/Test/IAD/helloWorld"
```
Run 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"
```
Run the following command if you only want to retrieve the parameter Value.
```
aws ssm get-parameter --name testDataTypeParameter --query "Parameter.Value"
```
Run the following command if you only want to retrieve the parameter Value using `get-parameters`.
```
aws ssm get-parameters --names "testDataTypeParameter" --query "Parameters[*].Value"
```
Run 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": [
{
"Name": "helloworld",
"Type": "String",
"LastModifiedUser": "arn:aws:iam::123456789012:user/JohnDoe",
"LastModifiedDate": 1494529763.156,
"Version": 1,
"Tier": "Standard",
"Policies": []
}
]
}
```
## Creating a StringList parameter using the AWS CLI
1. Install and configure the AWS Command Line Interface (AWS CLI), if you haven't already.
For information, see [Installing or updating the latest version of the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
1. Run the following command to create a parameter. Replace each *example resource placeholder* with your own information.
------
#### [ Linux & macOS ]
```
aws ssm put-parameter \
--name "parameter-name" \
--value "a-comma-separated-list-of-values" \
--type StringList \
--tags "Key=tag-key,Value=tag-value"
```
------
#### [ Windows ]
```
aws ssm put-parameter ^
--name "parameter-name" ^
--value "a-comma-separated-list-of-values" ^
--type StringList ^
--tags "Key=tag-key,Value=tag-value"
```
------
**Note**
If successful, the command returns the version number of the parameter.
This example adds two key-value pair tags to a parameter. (Depending on the operating system type on your local machine, run one of the following commands. The version to run from a local Windows machine includes the escape characters ("\$1") that you need to run the command from your command line tool.)
Here is a `StringList` example that uses a parameter hierarchy.
------
#### [ Linux & macOS ]
```
aws ssm put-parameter \
--name /IAD/ERP/Oracle/addUsers \
--value "Milana,Mariana,Mark,Miguel" \
--type StringList
```
------
#### [ Windows ]
```
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 characters to escape items in the list. If you have a parameter value that requires a comma, then use the `String` type.
1. Run the `get-parameters` command to verify the details of the parameter. For example:
```
aws ssm get-parameters --name "/IAD/ERP/Oracle/addUsers"
```
## Creating a SecureString parameter using the AWS CLI
Use the following procedure to create a `SecureString` parameter. Replace each *example resource placeholder* with your own information.
**Important**
Only the *value* of a `SecureString` parameter is encrypted. Parameter names, descriptions, and other properties aren't encrypted.
**Important**
Parameter Store only supports [symmetric encryption KMS keys](https://docs.aws.amazon.com/kms/latest/developerguide/symm-asymm-choose-key-spec.html#symmetric-cmks). You can't use an [asymmetric encryption KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html) to encrypt your parameters. For help determining whether a KMS key is symmetric or asymmetric, see [Identifying symmetric and asymmetric KMS keys](https://docs.aws.amazon.com/kms/latest/developerguide/find-symm-asymm.html) in the *AWS Key Management Service Developer Guide*
1. Install and configure the AWS Command Line Interface (AWS CLI), if you haven't already.
For information, see [Installing or updating the latest version of the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
1. Run **one** of the following commands to create a parameter that uses the `SecureString` data type.
------
#### [ Linux & macOS ]
**Create a `SecureString` parameter using the default AWS managed key **
```
aws ssm put-parameter \
--name "parameter-name" \
--value "parameter-value" \
--type "SecureString"
```
**Create a `SecureString` parameter that uses a customer managed key**
```
aws ssm put-parameter \
--name "parameter-name" \
--value "a-parameter-value, for example P@ssW%rd#1" \
--type "SecureString"
--tags "Key=tag-key,Value=tag-value"
```
**Create a `SecureString` parameter that uses a custom AWS KMS key**
```
aws ssm put-parameter \
--name "parameter-name" \
--value "a-parameter-value, for example P@ssW%rd#1" \
--type "SecureString" \
--key-id "your-account-ID/the-custom-AWS KMS-key" \
--tags "Key=tag-key,Value=tag-value"
```
------
#### [ Windows ]
**Create a `SecureString` parameter using the default AWS managed key**
```
aws ssm put-parameter ^
--name "parameter-name" ^
--value "parameter-value" ^
--type "SecureString"
```
**Create a `SecureString` parameter that uses a customer managed key**
```
aws ssm put-parameter ^
--name "parameter-name" ^
--value "a-parameter-value, for example P@ssW%rd#1" ^
--type "SecureString" ^
--tags "Key=tag-key,Value=tag-value"
```
**Create a `SecureString` parameter that uses a custom AWS KMS key**
```
aws ssm put-parameter ^
--name "parameter-name" ^
--value "a-parameter-value, for example P@ssW%rd#1" ^
--type "SecureString" ^
--key-id " ^
--tags "Key=tag-key,Value=tag-value"account-ID/the-custom-AWS KMS-key"
```
------
If you create a `SecureString` parameter by using the AWS managed key key in your account and Region, then you *don't* have to provide a value for the `--key-id` parameter.
**Note**
To use the AWS KMS key assigned to your AWS account and AWS Region, remove the `key-id` parameter from the command. For more information about AWS KMS keys, see [AWS Key Management Service Concepts](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#aws-managed-cmk) in the *AWS Key Management Service Developer Guide*.
To use a customer managed key instead of the AWS managed key assigned to your account, specify the key by using the `--key-id` parameter. The parameter supports the following KMS parameter formats.
+ Key Amazon Resource Name (ARN) example:
`arn:aws:kms:us-east-2:123456789012:key/key-id`
+ Alias ARN example:
`arn:aws:kms:us-east-2:123456789012:alias/alias-name`
+ Key ID example:
`12345678-1234-1234-1234-123456789012`
+ Alias Name example:
`alias/MyAliasName`
You can create a customer managed key by using the AWS Management Console or the AWS KMS API. The following AWS CLI commands create a customer managed key in the current AWS Region of your AWS account.
```
aws kms [create-key](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html)
```
Use a command in the following format to create a `SecureString` parameter using the key you just created.
The following example uses an obfuscated name (`3l3vat3131`) for a password parameter and an AWS KMS key.
------
#### [ Linux & macOS ]
```
aws ssm put-parameter \
--name /Finance/Payroll/3l3vat3131 \
--value "P@sSwW)rd" \
--type SecureString \
--key-id arn:aws:kms:us-east-2:123456789012:key/1a2b3c4d-1a2b-1a2b-1a2b-1a2b3c4d5e
```
------
#### [ Windows ]
```
aws ssm put-parameter ^
--name /Finance/Payroll/3l3vat3131 ^
--value "P@sSwW)rd" ^
--type SecureString ^
--key-id arn:aws:kms:us-east-2:123456789012:key/1a2b3c4d-1a2b-1a2b-1a2b-1a2b3c4d5e
```
------
1. Run the following command to verify the details of the parameter.
If you don't specify the `with-decryption` parameter, or if you specify the `no-with-decryption` parameter, the command returns an encrypted GUID.
------
#### [ Linux & macOS ]
```
aws ssm get-parameters \
--name "the-parameter-name-you-specified" \
--with-decryption
```
------
#### [ Windows ]
```
aws ssm get-parameters ^
--name "the-parameter-name-you-specified" ^
--with-decryption
```
------
1. Run the following command to view the parameter metadata.
------
#### [ Linux & macOS ]
```
aws ssm describe-parameters \
--filters "Key=Name,Values=the-name-that-you-specified"
```
------
#### [ Windows ]
```
aws ssm describe-parameters ^
--filters "Key=Name,Values=the-name-that-you-specified"
```
------
1. Run the following command to change the parameter value if you're **not** using a customer managed AWS KMS key.
------
#### [ Linux & macOS ]
```
aws ssm put-parameter \
--name "the-name-that-you-specified" \
--value "a-new-parameter-value" \
--type "SecureString" \
--overwrite
```
------
#### [ Windows ]
```
aws ssm put-parameter ^
--name "the-name-that-you-specified" ^
--value "a-new-parameter-value" ^
--type "SecureString" ^
--overwrite
```
------
-or-
Run one of the following commands to change the parameter value if you **are** using a customer managed AWS KMS key.
------
#### [ Linux & macOS ]
```
aws ssm put-parameter \
--name "the-name-that-you-specified" \
--value "a-new-parameter-value" \
--type "SecureString" \
--key-id "the-KMSkey-ID" \
--overwrite
```
```
aws ssm put-parameter \
--name "the-name-that-you-specified" \
--value "a-new-parameter-value" \
--type "SecureString" \
--key-id "account-alias/the-KMSkey-ID" \
--overwrite
```
------
#### [ Windows ]
```
aws ssm put-parameter ^
--name "the-name-that-you-specified" ^
--value "a-new-parameter-value" ^
--type "SecureString" ^
--key-id "the-KMSkey-ID" ^
--overwrite
```
```
aws ssm put-parameter ^
--name "the-name-that-you-specified" ^
--value "a-new-parameter-value" ^
--type "SecureString" ^
--key-id "account-alias/the-KMSkey-ID" ^
--overwrite
```
------
1. Run the following command to view the latest parameter value.
------
#### [ Linux & macOS ]
```
aws ssm get-parameters \
--name "the-name-that-you-specified" \
--with-decryption
```
------
#### [ Windows ]
```
aws ssm get-parameters ^
--name "the-name-that-you-specified" ^
--with-decryption
```
------
1. Run the following command to view the parameter value history.
------
#### [ Linux & macOS ]
```
aws ssm get-parameter-history \
--name "the-name-that-you-specified"
```
------
#### [ Windows ]
```
aws ssm get-parameter-history ^
--name "the-name-that-you-specified"
```
------
**Note**
You can manually create a parameter with an encrypted value. In this case, because the value is already encrypted, you don’t have to choose the `SecureString` parameter type. If you do choose `SecureString`, your parameter is doubly encrypted.
By default, all `SecureString` values are displayed as cipher-text. To decrypt a `SecureString` value, a user must have permission to call the AWS KMS [Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) API operation. For information about configuring AWS KMS access control, see [Authentication and Access Control for AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/control-access.html) in the *AWS Key Management Service Developer Guide*.
**Important**
If you change the KMS key alias for the KMS key used to encrypt a parameter, then you must also update the key alias the parameter uses to reference AWS KMS. This only applies to the KMS key alias; the key ID that an alias attaches to stays the same unless you delete the whole key.
## Creating a multi-line parameter using the AWS CLI
You can use the AWS CLI to create a parameter with line breaks. Use line breaks to break up the text in longer parameter values for better legibility or, for example, update multi-paragraph parameter content for a web page. You can include the content in a JSON file and use the `--cli-input-json` option, using line break characters like `\n`, as shown in the following example.
1. Install and configure the AWS Command Line Interface (AWS CLI), if you haven't already.
For information, see [Installing or updating the latest version of the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
1. Run the following command to create a multi-line parameter.
------
#### [ Linux & macOS ]
```
aws ssm put-parameter \
--name "MultiLineParameter" \
--type String \
--cli-input-json file://MultiLineParameter.json
```
------
#### [ Windows ]
```
aws ssm put-parameter ^
--name "MultiLineParameter" ^
--type String ^
--cli-input-json file://MultiLineParameter.json
```
------
The following example shows the contents of the file `MultiLineParameter.json`.
```
{
"Value": "Paragraph One\nParagraph Two\nParagraph Three"
}
```
The saved parameter value is stored as follows.
```
Paragraph One
Paragraph Two
Paragraph Three
```
# Creating a Parameter Store parameter using Tools for Windows PowerShell
You can use AWS Tools for Windows PowerShell to create `String`, `StringList`, and `SecureString` parameter types. After deleting a parameter, wait for at least 30 seconds to create a parameter with the same name.
Parameters can't be referenced or nested in the values of other parameters. You can't include `{{}}` or `{{ssm:parameter-name}}` in a parameter value.
**Note**
Parameters are only available in the AWS Region where they were created.
**Topics**
+ [Creating a String parameter (Tools for Windows PowerShell)](#param-create-ps-string)
+ [Creating a StringList parameter (Tools for Windows PowerShell)](#param-create-ps-stringlist)
+ [Creating a SecureString parameter (Tools for Windows PowerShell)](#param-create-ps-securestring)
## Creating a String parameter (Tools for Windows PowerShell)
1. Install and configure the AWS Tools for PowerShell (Tools for Windows PowerShell), if you haven't already.
For information, see [Installing the AWS Tools for PowerShell](https://docs.aws.amazon.com/powershell/latest/userguide/pstools-getting-set-up.html).
1. Run the following command to create a parameter that contains a plain text value. Replace each *example resource placeholder* with your own information.
```
Write-SSMParameter `
-Name "parameter-name" `
-Value "parameter-value" `
-Type "String"
```
-or-
Run the following command to create a parameter that contains an Amazon Machine Image (AMI) ID as the parameter value.
**Note**
To create a parameter with a tag, create the service.model.tag before hand as a variable. Here is an example.
```
$tag = New-Object Amazon.SimpleSystemsManagement.Model.Tag
$tag.Key = "tag-key"
$tag.Value = "tag-value"
```
```
Write-SSMParameter `
-Name "parameter-name" `
-Value "an-AMI-id" `
-Type "String" `
-DataType "aws:ec2:image" `
-Tags $tag
```
The `-DataType` option must be specified only if you are creating a parameter that contains an AMI ID. For all other parameters, the default data type is `text`. For more information, see [Using native parameter support in Parameter Store for Amazon Machine Image IDs](parameter-store-ec2-aliases.md).
Here is an example that uses a parameter hierarchy.
```
Write-SSMParameter `
-Name "/IAD/Web/SQL/IPaddress" `
-Value "99.99.99.999" `
-Type "String" `
-Tags $tag
```
1. Run the following command to verify the details of the parameter.
```
(Get-SSMParameterValue -Name "the-parameter-name-you-specified").Parameters
```
## Creating a StringList parameter (Tools for Windows PowerShell)
1. Install and configure the AWS Tools for PowerShell (Tools for Windows PowerShell), if you haven't already.
For information, see [Installing the AWS Tools for PowerShell](https://docs.aws.amazon.com/powershell/latest/userguide/pstools-getting-set-up.html).
1. Run the following command to create a StringList parameter. Replace each *example resource placeholder* with your own information.
**Note**
To create a parameter with a tag, create the service.model.tag before hand as a variable. Here is an example.
```
$tag = New-Object Amazon.SimpleSystemsManagement.Model.Tag
$tag.Key = "tag-key"
$tag.Value = "tag-value"
```
```
Write-SSMParameter `
-Name "parameter-name" `
-Value "a-comma-separated-list-of-values" `
-Type "StringList" `
-Tags $tag
```
If successful, the command returns the version number of the parameter.
Here is an example.
```
Write-SSMParameter `
-Name "stringlist-parameter" `
-Value "Milana,Mariana,Mark,Miguel" `
-Type "StringList" `
-Tags $tag
```
**Note**
Items in a `StringList` must be separated by a comma (,). You can't use other punctuation or special characters to escape items in the list. If you have a parameter value that requires a comma, then use the `String` type.
1. Run the following command to verify the details of the parameter.
```
(Get-SSMParameterValue -Name "the-parameter-name-you-specified").Parameters
```
## Creating a SecureString parameter (Tools for Windows PowerShell)
Before you create a `SecureString` parameter, read about the requirements for this type of parameter. For more information, see [Creating a SecureString parameter using the AWS CLI](param-create-cli.md#param-create-cli-securestring).
**Important**
Only the *value* of a `SecureString` parameter is encrypted. Parameter names, descriptions, and other properties aren't encrypted.
**Important**
Parameter Store only supports [symmetric encryption KMS keys](https://docs.aws.amazon.com/kms/latest/developerguide/symm-asymm-choose-key-spec.html#symmetric-cmks). You can't use an [asymmetric encryption KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html) to encrypt your parameters. For help determining whether a KMS key is symmetric or asymmetric, see [Identifying symmetric and asymmetric KMS keys](https://docs.aws.amazon.com/kms/latest/developerguide/find-symm-asymm.html) in the *AWS Key Management Service Developer Guide*
1. Install and configure the AWS Tools for PowerShell (Tools for Windows PowerShell), if you haven't already.
For information, see [Installing the AWS Tools for PowerShell](https://docs.aws.amazon.com/powershell/latest/userguide/pstools-getting-set-up.html).
1. Run the following command to create a parameter. Replace each *example resource placeholder* with your own information.
**Note**
To create a parameter with a tag, first create the service.model.tag as a variable. Here is an example.
```
$tag = New-Object Amazon.SimpleSystemsManagement.Model.Tag
$tag.Key = "tag-key"
$tag.Value = "tag-value"
```
```
Write-SSMParameter `
-Name "parameter-name" `
-Value "parameter-value" `
-Type "SecureString" `
-KeyId "an AWS KMS key ID, an AWS KMS key ARN, an alias name, or an alias ARN" `
-Tags $tag
```
If successful, the command returns the version number of the parameter.
**Note**
To use the AWS managed key assigned to your account, remove the `-KeyId` parameter from the command.
Here is an example that uses an obfuscated name (3l3vat3131) for a password parameter and an AWS managed key.
```
Write-SSMParameter `
-Name "/Finance/Payroll/3l3vat3131" `
-Value "P@sSwW)rd" `
-Type "SecureString"`
-Tags $tag
```
1. Run the following command to verify the details of the parameter.
```
(Get-SSMParameterValue -Name "the-parameter-name-you-specified" –WithDecryption $true).Parameters
```
By default, all `SecureString` values are displayed as cipher-text. To decrypt a `SecureString` value, a user must have permission to call the AWS KMS [Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) API operation. For information about configuring AWS KMS access control, see [Authentication and Access Control for AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/control-access.html) in the *AWS Key Management Service Developer Guide*.
**Important**
If you change the KMS key alias for the KMS key used to encrypt a parameter, then you must also update the key alias the parameter uses to reference AWS KMS. This only applies to the KMS key alias; the key ID that an alias attaches to stays the same unless you delete the whole key.
# Searching for Parameter Store parameters in Systems Manager
When you have a lot of parameters in your account, it can be difficult to find information about a single or several parameters at a time. In this case, you can use filter tools to search for the ones you need information about, according to search criteria you specify. You can use the AWS Systems Manager console, the AWS Command Line Interface (AWS CLI), the AWS Tools for PowerShell, or the [DescribeParameters](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_DescribeParameters.html) API to search for parameters.
**Topics**
+ [Searching for a parameter using the console](#parameter-search-console)
+ [Searching for a parameter using the AWS CLI](#parameter-search-cli)
## Searching for a parameter using the console
1. Open the AWS Systems Manager console at [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. In the navigation pane, choose **Parameter Store**.
1. Select in the search box and choose how you want to search. For example, `Type` or `Name`.
1. Provide information for the search type you selected. For example:
+ If you're searching by `Type`, choose from `String`, `StringList`, or `SecureString`.
+ If you're searching by `Name`, choose `contains`, `equals`, or `begins-with`, and then enter all or part of a parameter name.
**Note**
In the console, the default search type for `Name` is `contains`.
1. Press **Enter**.
The list of parameters is updated with the results of your search.
**Note**
Your search might contain more results than are displayed on the first page of results. Use the right arrow (**>**) at the topic of the parameter list (if available) to view the next set of results.
## Searching for a parameter using the AWS CLI
Use the `describe-parameters` command to view information about one or more parameters in the AWS CLI.
The following examples demonstrate various options you can use to view information about the parameters in your AWS account. For more information about these options, see [https://docs.aws.amazon.com/cli/latest/reference/ssm/describe-parameters.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/describe-parameters.html) in the *AWS Command Line Interface User Guide*.
1. Install and configure the AWS Command Line Interface (AWS CLI), if you haven't already.
For information, see [Installing or updating the latest version of the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
1. Replace the sample values in the following commands with values reflecting parameters that have been created in your account.
------
#### [ Linux & macOS ]
```
aws ssm describe-parameters \
--parameter-filters "Key=Name,Values=MyParameterName"
```
------
#### [ Windows ]
```
aws ssm describe-parameters ^
--parameter-filters "Key=Name,Values=MyParameterName"
```
------
**Note**
For `describe-parameters`, the default search type for `Name` is `Equals`. In your parameter filters, specifying `"Key=Name,Values=MyParameterName"` is the same as specifying `"Key=Name,Option=Equals,Values=MyParameterName"`.
```
aws ssm describe-parameters \
--parameter-filters "Key=Name,Option=Contains,Values=Product"
```
```
aws ssm describe-parameters \
--parameter-filters "Key=Type,Values=String"
```
```
aws ssm describe-parameters \
--parameter-filters "Key=Path,Values=/Production/West"
```
```
aws ssm describe-parameters \
--parameter-filters "Key=Tier,Values=Standard"
```
```
aws ssm describe-parameters \
--parameter-filters "Key=tag:tag-key,Values=tag-value"
```
```
aws ssm describe-parameters \
--parameter-filters "Key=KeyId,Values=key-id"
```
**Note**
In the last example, *key-id* represents the ID of an AWS Key Management Service (AWS KMS) key used to encrypt a `SecureString` parameter created in your account. Alternatively, you can enter **alias/aws/ssm** to use the default AWS KMS key for your account. For more information, see [Creating a SecureString parameter using the AWS CLI](param-create-cli.md#param-create-cli-securestring).
If successful, the command returns output similar to the following.
```
{
"Parameters": [
{
"Name": "/Production/West/Manager",
"Type": "String",
"LastModifiedDate": 1573438580.703,
"LastModifiedUser": "arn:aws:iam::111122223333:user/Mateo.Jackson",
"Version": 1,
"Tier": "Standard",
"Policies": []
},
{
"Name": "/Production/West/TeamLead",
"Type": "String",
"LastModifiedDate": 1572363610.175,
"LastModifiedUser": "arn:aws:iam::111122223333:user/Mateo.Jackson",
"Version": 1,
"Tier": "Standard",
"Policies": []
},
{
"Name": "/Production/West/HR",
"Type": "String",
"LastModifiedDate": 1572363680.503,
"LastModifiedUser": "arn:aws:iam::111122223333:user/Mateo.Jackson",
"Version": 1,
"Tier": "Standard",
"Policies": []
}
]
}
```
# Assigning parameter policies in Parameter Store
Parameter policies help you manage a growing set of parameters by allowing you to assign specific criteria to a parameter such as an expiration date or *time to live*. Parameter policies are especially helpful in forcing you to update or delete passwords and configuration data stored in Parameter Store, a tool in AWS Systems Manager. Parameter Store offers the following types of policies: `Expiration`, `ExpirationNotification`, and `NoChangeNotification`.
**Note**
To implement password rotation lifecycles, use AWS Secrets Manager. You can rotate, manage, and retrieve database credentials, API keys, and other secrets throughout their lifecycle using Secrets Manager. For more information, see [What is AWS Secrets Manager?](https://docs.aws.amazon.com//secretsmanager/latest/userguide/intro.html) in the *AWS Secrets Manager User Guide*.
Parameter Store enforces parameter policies by using asynchronous, periodic scans. After you create a policy, you don't need to perform additional actions to enforce the policy. Parameter Store independently performs the action defined by the policy according to the criteria you specified.
**Note**
Parameter policies are available for parameters that use the advanced parameters tier. For more information, see [Managing parameter tiers](parameter-store-advanced-parameters.md).
A parameter policy is a JSON array, as shown in the following table. You can assign a policy when you create a new advanced parameter, or you can apply a policy by updating a parameter. Parameter Store supports the following types of parameter policies.
| Policy | Details | Examples |
| --- | --- | --- |
| **Expiration** | This policy deletes the parameter. You can specify a specific date and time by using either the `ISO_INSTANT` format or the `ISO_OFFSET_DATE_TIME` format. To change when you want the parameter to be deleted, update the policy. Updating a *parameter* doesn't affect the expiration date or time of the policy attached to it. When the expiration date and time is reached, Parameter Store deletes the parameter. This example uses the `ISO_INSTANT` format. You can also specify a date and time by using the `ISO_OFFSET_DATE_TIME` format. Here is an example: `2019-11-01T22:13:48.87+10:30:00` . | {
"Type": "Expiration",
"Version": "1.0",
"Attributes": {
"Timestamp": "2018-12-02T21:34:33.000Z"
}
} |
| **ExpirationNotification** | This policy initiates an event in Amazon EventBridge (EventBridge) that notifies you about the expiration. By using this policy, you can receive notifications before the expiration time is reached, in units of days or hours. | {
"Type": "ExpirationNotification",
"Version": "1.0",
"Attributes": {
"Before": "15",
"Unit": "Days"
}
} |
| **NoChangeNotification** | This policy initiates an event in EventBridge if a parameter has *not* been modified for a specified period of time. This policy type is useful when, for example, a password needs to be changed within a period of time. This policy determines when to send a notification by reading the `LastModifiedTime` attribute of the parameter. If you change or edit a parameter, the system resets the notification time period based on the new value of `LastModifiedTime`. | {
"Type": "NoChangeNotification",
"Version": "1.0",
"Attributes": {
"After": "20",
"Unit": "Days"
}
} |
You can assign multiple policies to a parameter. For example, you can assign `Expiration` and `ExpirationNotification` policies so that the system initiates an EventBridge event to notify you about the impending deletion of a parameter. You can assign a maximum of ten (10) policies to a parameter.
The following example shows the request syntax for a [PutParameter](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_PutParameter.html) API request that assigns four policies to a new `SecureString` parameter named `ProdDB3`.
```
{
"Name": "ProdDB3",
"Description": "Parameter with policies",
"Value": "P@ssW*rd21",
"Type": "SecureString",
"Overwrite": "True",
"Policies": [
{
"Type": "Expiration",
"Version": "1.0",
"Attributes": {
"Timestamp": "2018-12-02T21:34:33.000Z"
}
},
{
"Type": "ExpirationNotification",
"Version": "1.0",
"Attributes": {
"Before": "30",
"Unit": "Days"
}
},
{
"Type": "ExpirationNotification",
"Version": "1.0",
"Attributes": {
"Before": "15",
"Unit": "Days"
}
},
{
"Type": "NoChangeNotification",
"Version": "1.0",
"Attributes": {
"After": "20",
"Unit": "Days"
}
}
]
}
```
## Adding policies to an existing parameter
This section includes information about how to add policies to an existing parameter by using the AWS Systems Manager console, the AWS Command Line Interface (AWS CLI), and AWS Tools for Windows PowerShell . For information about how to create a new parameter that includes policies, see [Creating Parameter Store parameters in Systems Manager](sysman-paramstore-su-create.md).
**Topics**
+ [Adding policies to an existing parameter using the console](#sysman-paramstore-policy-create-console)
+ [Adding policies to an existing parameter using the AWS CLI](#sysman-paramstore-policy-create-cli)
+ [Adding policies to an existing parameter (Tools for Windows PowerShell)](#sysman-paramstore-policy-create-ps)
### Adding policies to an existing parameter using the console
Use the following procedure to add policies to an existing parameter by using the Systems Manager console.
**To add policies to an existing parameter**
1. Open the AWS Systems Manager console at [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. In the navigation pane, choose **Parameter Store**.
1. Choose the option next to the parameter that you want to update to include policies, and then choose **Edit**.
1. Choose **Advanced**.
1. (Optional) In the **Parameter policies** section, choose **Enabled**. You can specify an expiration date and one or more notification policies for this parameter.
1. Choose **Save changes**.
**Important**
Parameter Store preserves policies on a parameter until you either overwrite the policies with new policies or remove the policies.
To remove all policies from an existing parameter, edit the parameter and apply an empty policy by using brackets and curly braces, as follows: `[{}]`
If you add a new policy to a parameter that already has policies, then Systems Manager overwrites the policies attached to the parameter. The existing policies are deleted. If you want to add a new policy to a parameter that already has one or more policies, copy and paste the original policies, type the new policy, and then save your changes.
### Adding policies to an existing parameter using the AWS CLI
Use the following procedure to add policies to an existing parameter by using the AWS CLI.
**To add policies to an existing parameter**
1. Install and configure the AWS Command Line Interface (AWS CLI), if you haven't already.
For information, see [Installing or updating the latest version of the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
1. Run the following command to add policies to an existing parameter. Replace each *example resource placeholder* with your own information.
------
#### [ Linux & macOS ]
```
aws ssm put-parameter
--name "parameter name" \
--value 'parameter value' \
--type parameter type \
--overwrite \
--policies "[{policies-enclosed-in-brackets-and-curly-braces}]"
```
------
#### [ Windows ]
```
aws ssm put-parameter
--name "parameter name" ^
--value 'parameter value' ^
--type parameter type ^
--overwrite ^
--policies "[{policies-enclosed-in-brackets-and-curly-braces}]"
```
------
Here is an example that includes an expiration policy that deletes the parameter after 15 days. The example also includes a notification policy that generates an EventBridge event five (5) days before the parameter is deleted. Last, it includes a `NoChangeNotification` policy if no changes are made to this parameter after 60 days. The example uses an obfuscated name (`3l3vat3131`) for a password and an AWS Key Management Service AWS KMS key. For more information about AWS KMS keys, see [AWS Key Management Service Concepts](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#aws-managed-cmk) in the *AWS Key Management Service Developer Guide*.
------
#### [ Linux & macOS ]
```
aws ssm put-parameter \
--name "/Finance/Payroll/3l3vat3131" \
--value "P@sSwW)rd" \
--type "SecureString" \
--overwrite \
--policies "[{\"Type\":\"Expiration\",\"Version\":\"1.0\",\"Attributes\":{\"Timestamp\":\"2020-05-13T00:00:00.000Z\"}},{\"Type\":\"ExpirationNotification\",\"Version\":\"1.0\",\"Attributes\":{\"Before\":\"5\",\"Unit\":\"Days\"}},{\"Type\":\"NoChangeNotification\",\"Version\":\"1.0\",\"Attributes\":{\"After\":\"60\",\"Unit\":\"Days\"}}]"
```
------
#### [ Windows ]
```
aws ssm put-parameter ^
--name "/Finance/Payroll/3l3vat3131" ^
--value "P@sSwW)rd" ^
--type "SecureString" ^
--overwrite ^
--policies "[{\"Type\":\"Expiration\",\"Version\":\"1.0\",\"Attributes\":{\"Timestamp\":\"2020-05-13T00:00:00.000Z\"}},{\"Type\":\"ExpirationNotification\",\"Version\":\"1.0\",\"Attributes\":{\"Before\":\"5\",\"Unit\":\"Days\"}},{\"Type\":\"NoChangeNotification\",\"Version\":\"1.0\",\"Attributes\":{\"After\":\"60\",\"Unit\":\"Days\"}}]"
```
------
1. Run the following command to verify the details of the parameter. Replace *parameter name* with your own information.
------
#### [ Linux & macOS ]
```
aws ssm describe-parameters \
--parameter-filters "Key=Name,Values=parameter name"
```
------
#### [ Windows ]
```
aws ssm describe-parameters ^
--parameter-filters "Key=Name,Values=parameter name"
```
------
**Important**
Parameter Store retains policies for a parameter until you either overwrite the policies with new policies or remove the policies.
To remove all policies from an existing parameter, edit the parameter and apply an empty policy of brackets and curly braces. Replace each *example resource placeholder* with your own information. For example:
```
aws ssm put-parameter \
--name parameter name \
--type parameter type \
--value 'parameter value' \
--policies "[{}]"
```
```
aws ssm put-parameter ^
--name parameter name ^
--type parameter type ^
--value 'parameter value' ^
--policies "[{}]"
```
If you add a new policy to a parameter that already has policies, then Systems Manager overwrites the policies attached to the parameter. The existing policies are deleted. If you want to add a new policy to a parameter that already has one or more policies, copy and paste the original policies, type the new policy, and then save your changes.
### Adding policies to an existing parameter (Tools for Windows PowerShell)
Use the following procedure to add policies to an existing parameter by using Tools for Windows PowerShell. Replace each *example resource placeholder* with your own information.
**To add policies to an existing parameter**
1. Open Tools for Windows PowerShell and run the following command to specify your credentials. You must either have administrator permissions in Amazon Elastic Compute Cloud (Amazon EC2), or you must have been granted the appropriate permission in AWS Identity and Access Management (IAM).
```
Set-AWSCredentials `
–AccessKey access-key-name `
–SecretKey secret-key-name
```
1. Run the following command to set the Region for your PowerShell session. The example uses the US East (Ohio) Region (us-east-2).
```
Set-DefaultAWSRegion `
-Region us-east-2
```
1. Run the following command to add policies to an existing parameter. Replace each *example resource placeholder* with your own information.
```
Write-SSMParameter `
-Name "parameter name" `
-Value "parameter value" `
-Type "parameter type" `
-Policies "[{policies-enclosed-in-brackets-and-curly-braces}]" `
-Overwrite
```
Here is an example that includes an expiration policy that deletes the parameter at midnight (GMT) on May 13, 2020. The example also includes a notification policy that generates an EventBridge event five (5) days before the parameter is deleted. Last, it includes a `NoChangeNotification` policy if no changes are made to this parameter after 60 days. The example uses an obfuscated name (`3l3vat3131`) for a password and an AWS managed key.
```
Write-SSMParameter `
-Name "/Finance/Payroll/3l3vat3131" `
-Value "P@sSwW)rd" `
-Type "SecureString" `
-Policies "[{\"Type\":\"Expiration\",\"Version\":\"1.0\",\"Attributes\":{\"Timestamp\":\"2018-05-13T00:00:00.000Z\"}},{\"Type\":\"ExpirationNotification\",\"Version\":\"1.0\",\"Attributes\":{\"Before\":\"5\",\"Unit\":\"Days\"}},{\"Type\":\"NoChangeNotification\",\"Version\":\"1.0\",\"Attributes\":{\"After\":\"60\",\"Unit\":\"Days\"}}]" `
-Overwrite
```
1. Run the following command to verify the details of the parameter. Replace *parameter name* with your own information.
```
(Get-SSMParameterValue -Name "parameter name").Parameters
```
**Important**
Parameter Store preserves policies on a parameter until you either overwrite the policies with new policies or remove the policies.
To remove all policies from an existing parameter, edit the parameter and apply an empty policy of brackets and curly braces. For example:
```
Write-SSMParameter `
-Name "parameter name" `
-Value "parameter value" `
-Type "parameter type" `
-Policies "[{}]"
```
If you add a new policy to a parameter that already has policies, then Systems Manager overwrites the policies attached to the parameter. The existing policies are deleted. If you want to add a new policy to a parameter that already has one or more policies, copy and paste the original policies, type the new policy, and then save your changes.
# Working with parameter hierarchies in Parameter Store
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 (/).
**Topics**
+ [Understanding parameter hierarchy through examples](#ps-hierarchy-examples)
+ [Querying parameters in a hierarchy](#ps-hierarchy-queries)
+ [Managing parameters using hierarchies using the AWS CLI](#sysman-paramstore-walk-hierarchy)
## Understanding parameter hierarchy through examples
The following example 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 15 levels. We suggest that you create hierarchies that reflect an existing hierarchical structure in your environment, as shown in the following examples:
+ Your [Continuous integration](https://aws.amazon.com/devops/continuous-integration/) and [Continuous delivery](https://aws.amazon.com/devops/continuous-delivery/) environment (CI/CD workflows)
`/Dev/DBServer/MySQL/db-string`
`/Staging/DBServer/MySQL/db-string`
`/Prod/DBServer/MySQL/db-string`
+ Your applications that use containers
```
/MyApp/.NET/Libraries/my-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/my-password`
You could then create a unique password for your production environment, as shown in the following example:
`/prod/MyApp/database/my-password`
You aren't 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`
## Querying parameters in a hierarchy
Another benefit of using hierarchies is the ability to query for all parameters *under* a certain level in a hierarchy by using the [GetParametersByPath](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_GetParametersByPath.html) API operation. For example, if you run the following command from the AWS Command Line Interface (AWS CLI), the system returns all parameters under the `Oncall` level:
```
aws ssm get-parameters-by-path --path /Dev/Web/Oncall
```
Sample output:
```
{
"Parameters": [
{
"Name": "/Dev/Web/Oncall/Week1",
"Type": "String",
"Value": "John Doe",
"Version": 1,
"LastModifiedDate": "2024-11-22T07:18:53.510000-08:00",
"ARN": "arn:aws:ssm:us-east-2:123456789012:parameter/Dev/Web/Oncall/Week1",
"DataType": "text"
},
{
"Name": "/Dev/Web/Oncall/Week2",
"Type": "String",
"Value": "Mary Major",
"Version": 1,
"LastModifiedDate": "2024-11-22T07:21:25.325000-08:00",
"ARN": "arn:aws:ssm:us-east-2:123456789012:parameter/Dev/Web/Oncall/Week2",
"DataType": "text"
}
]
}
```
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
```
## Managing parameters using hierarchies using the AWS CLI
This procedure shows how to work with parameters and parameter hierarchies by using the AWS CLI.
**To manage parameters using hierarchies**
1. Install and configure the AWS Command Line Interface (AWS CLI), if you haven't already.
For information, see [Installing or updating the latest version of the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
1. Run the following command to create a parameter that uses the `allowedPattern` parameter and the `String` parameter type. The allowed pattern in this example means the value for the parameter must be between 1 and 4 digits long.
------
#### [ Linux & macOS ]
```
aws ssm put-parameter \
--name "/MyService/Test/MaxConnections" \
--value 100 --allowed-pattern "\d{1,4}" \
--type String
```
------
#### [ Windows ]
```
aws ssm put-parameter ^
--name "/MyService/Test/MaxConnections" ^
--value 100 --allowed-pattern "\d{1,4}" ^
--type String
```
------
The command returns the version number of the parameter.
1. Run the following command to *attempt* to overwrite the parameter you just created with a new value.
------
#### [ Linux & macOS ]
```
aws ssm put-parameter \
--name "/MyService/Test/MaxConnections" \
--value 10,000 \
--type String \
--overwrite
```
------
#### [ Windows ]
```
aws ssm put-parameter ^
--name "/MyService/Test/MaxConnections" ^
--value 10,000 ^
--type String ^
--overwrite
```
------
The system returns the following error because the new value doesn't 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}
```
1. Run the following command to create a `SecureString` parameter that uses an AWS managed key. The allowed pattern in this example means the user can specify any character, and the value must be between 8 and 20 characters.
------
#### [ Linux & macOS ]
```
aws ssm put-parameter \
--name "/MyService/Test/my-password" \
--value "p#sW*rd33" \
--allowed-pattern ".{8,20}" \
--type SecureString
```
------
#### [ Windows ]
```
aws ssm put-parameter ^
--name "/MyService/Test/my-password" ^
--value "p#sW*rd33" ^
--allowed-pattern ".{8,20}" ^
--type SecureString
```
------
1. Run the following commands to create more parameters that use the hierarchy structure from the previous step.
------
#### [ Linux & macOS ]
```
aws ssm put-parameter \
--name "/MyService/Test/DBname" \
--value "SQLDevDb" \
--type String
```
```
aws ssm put-parameter \
--name "/MyService/Test/user" \
--value "SA" \
--type String
```
```
aws ssm put-parameter \
--name "/MyService/Test/userType" \
--value "SQLuser" \
--type String
```
------
#### [ Windows ]
```
aws ssm put-parameter ^
--name "/MyService/Test/DBname" ^
--value "SQLDevDb" ^
--type String
```
```
aws ssm put-parameter ^
--name "/MyService/Test/user" ^
--value "SA" ^
--type String
```
```
aws ssm put-parameter ^
--name "/MyService/Test/userType" ^
--value "SQLuser" ^
--type String
```
------
1. Run the following command to get the value of two parameters.
------
#### [ Linux & macOS ]
```
aws ssm get-parameters \
--names "/MyService/Test/user" "/MyService/Test/userType"
```
------
#### [ Windows ]
```
aws ssm get-parameters ^
--names "/MyService/Test/user" "/MyService/Test/userType"
```
------
1. Run the following command to query for all parameters under a single level.
------
#### [ Linux & macOS ]
```
aws ssm get-parameters-by-path \
--path "/MyService/Test"
```
------
#### [ Windows ]
```
aws ssm get-parameters-by-path ^
--path "/MyService/Test"
```
------
1. Run the following command to delete two parameters.
------
#### [ Linux & macOS ]
```
aws ssm delete-parameters \
--names "/IADRegion/Dev/user" "/IADRegion/Dev/userType"
```
------
#### [ Windows ]
```
aws ssm delete-parameters ^
--names "/IADRegion/Dev/user" "/IADRegion/Dev/userType"
```
------
# Preventing access to Parameter Store API operations
Using service-specific *[conditions](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition.html)* supported by Systems Manager for AWS Identity and Access Management (IAM) policies, you can explicity allow or deny access to Parameter Store API operations and content. By using these conditions, you can allow only certain IAM Entities (users and roles) in your organization to call certain API actions, or prevent certain IAM Entities from running them. This includes actions run through the Parameter Store console, the AWS Command Line Interface (AWS CLI), and SDKs.
Systems Manager currently supports three conditions that are specific to Parameter Store.
**Topics**
+ [Preventing changes to existing parameters using `ssm:Overwrite`](#overwrite-condition)
+ [Preventing creation or updates to parameters that use a parameter policy using `ssm:Policies`](#parameter-policies-condition)
+ [Preventing access to levels in a hierarchical parameter using `ssm:Recursive`](#recursive-condition)
## Preventing changes to existing parameters using `ssm:Overwrite`
Use the `ssm:Overwrite` condition to control whether IAM Entities can update existing parameters.
In the following sample policy, the `"Allow"` statement grants permission to create parameters by running the `PutParameter` API operation in the AWS account 123456789012 in the US East (Ohio) Region (us-east-2).
However, the `"Deny"` statement prevents Entities from changing values of *existing* parameters because the `Overwrite` option is explicitly denied for the `PutParameter` operation. Therefore, Entities that are assigned this policy can create parameters, but not make changes to existing parameters.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:PutParameter"
],
"Resource": "arn:aws:ssm:us-east-1:111122223333:parameter/*"
},
{
"Effect": "Deny",
"Action": [
"ssm:PutParameter"
],
"Condition": {
"StringEquals": {
"ssm:Overwrite": [
"true"
]
}
},
"Resource": "arn:aws:ssm:us-east-1:111122223333:parameter/*"
}
]
}
```
------
## Preventing creation or updates to parameters that use a parameter policy using `ssm:Policies`
User the `ssm:Policies` condition to control whether Entities can create parameters that include a parameter policy and update existing parameters that include a parameter policy.
In the following policy example, the `"Allow"` statement grants general permission to create parameters, but the `"Deny"` statement prevents Entities from creating or updating parameters that include a parameter policy in the the AWS account 123456789012 in the US East (Ohio) Region (us-east-2). Entities can still create or update parameters that aren't assigned a parameter policy.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:PutParameter"
],
"Resource": "arn:aws:ssm:us-east-1:111122223333:parameter/*"
},
{
"Effect": "Deny",
"Action": [
"ssm:PutParameter"
],
"Condition": {
"StringEquals": {
"ssm:Policies": [
"true"
]
}
},
"Resource": "arn:aws:ssm:us-east-1:111122223333:parameter/*"
}
]
}
```
------
## Preventing access to levels in a hierarchical parameter using `ssm:Recursive`
Use the `ssm:Recursive` condition to control whether IAM Entities can view or reference levels in a hierarchical parameter. You can provide or restrict access to all parameters beyond a specific level of a hierarchy.
In the following example policy, the `"Allow"` statement provides access to Parameter Store operations on all parameters in the path `/Code/Departments/Finance/*` for the AWS account 123456789012 in the US East (Ohio) Region (us-east-2).
After this, the `"Deny"` statement prevents IAM Entities from viewing or retrieving parameter data at or below the level of `/Code/Departments/*`. Entities can still, however, still create or update parameters in that path. The example has been constructed to illustrate that recursively denying access below a certain level in a parameter hierarchy takes precedence over more permissive access in the same policy.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:*"
],
"Resource": "arn:aws:ssm:us-east-1:111122223333:parameter/*"
},
{
"Effect": "Deny",
"Action": [
"ssm:GetParametersByPath"
],
"Condition": {
"StringEquals": {
"ssm:Recursive": [
"true"
]
}
},
"Resource": "arn:aws:ssm:us-east-1:111122223333:parameter/Code/Departments/*"
}
]
}
```
------
**Important**
If a user has access to a path, then the user can access all levels of that path. For example, if a user has permission to access path `/a`, then the user can also access `/a/b`. This is true unless the user has explicitly been denied access in IAM for parameter `/b`, as illustrated above.
# Working with parameter labels in Parameter Store
A parameter label is a user-defined alias to help you manage different versions of a parameter. When you modify a parameter, AWS Systems Manager automatically saves a new version and increments the version number by one. A label can help you remember the purpose of a parameter version when there are multiple versions.
For example, let's say you have a parameter called `/MyApp/DB/ConnectionString`. The value of the parameter is a connection string to a MySQL server in a local database in a test environment. After you finish updating the application, you want the parameter to use a connection string for a production database. You change the value of `/MyApp/DB/ConnectionString`. Systems Manager automatically creates version two with the new connection string. To help you remember the purpose of each version, you attach a label to each parameter. For version one, you attach the label *Test* and for version two you attach the label *Production*.
You can move labels from one version of a parameter to another version. For example, if you create version 3 of the `/MyApp/DB/ConnectionString` parameter with a connection string for a new production database, then you can move the *Production* label from version 2 of the parameter to version 3 of the parameter.
Parameter labels are a lightweight alternative to parameter tags. Your organization might have strict guidelines for tags that must be applied to different AWS resources. In contrast, a label is simply a text association for a specific version of a parameter.
Similar to tags, you can query parameters by using labels. You can view a list of specific parameter versions that all use the same label if you query your parameter set by using the [GetParametersByPath](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_GetParametersByPath.html) API operation, as described later in this section.
**Note**
If you run a command that specifies a version of a parameter that doesn't exist, the command fails. It doesn't fall back to the latest or default value of the parameter.
**Label requirements and restrictions**
Parameter labels have the following requirements and restrictions:
+ A version of a parameter can have a maximum of 10 labels.
+ You can't attach the same label to different versions of the same parameter. For example, if version 1 of the parameter has the label *Production*, then you can't attach *Production* to version 2.
+ You can move a label from one version of a parameter to another.
+ You can't create a label when you create a parameter. You must attach a label to a specific version of a parameter.
+ If you no longer want to use a parameter label, then you can move it to a different version of a parameter or delete it.
+ A label can have a maximum of 100 characters.
+ Labels can contain letters (case sensitive), numbers, periods (.), hyphens (-), or underscores (\$1).
+ Labels can't begin with a number, "aws", or "ssm" (not case sensitive). If a label doesn't meet these requirements, then the label isn't attached to the parameter version and the system displays it in the list of `InvalidLabels`.
**Topics**
+ [Working with parameter labels using the console](#sysman-paramstore-labels-console)
+ [Working with parameter labels using the AWS CLI](#sysman-paramstore-labels-cli)
## Working with parameter labels using the console
This section describes how to perform the following tasks by using the Systems Manager console.
+ [Creating a parameter label using the console](#sysman-paramstore-labels-console-create)
+ [Viewing labels attached to a parameter using the console](#sysman-paramstore-labels-console-view)
+ [Moving a parameter label using the console](#sysman-paramstore-labels-console-move)
+ [Deleting parameter labels using the console](#systems-manager-parameter-store-labels-console-delete)
### Creating a parameter label using the console
The following procedure describes how to attach a label to a specific version of an *existing* parameter by using the Systems Manager console. You can't attach a label when you create a parameter.
**To attach a label to a parameter version**
1. Open the AWS Systems Manager console at [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. In the navigation pane, choose **Parameter Store**.
1. Choose the name of a parameter to open the details page for that parameter.
1. Choose the **History** tab.
1. Choose the parameter version for which you want to attach a label.
1. Choose **Manage labels**.
1. Choose **Add new label**.
1. In the text box, enter the label name. To add more labels, choose **Add new label**. You can attach a maximum of ten labels.
1. When you're finished, choose **Save changes**.
### Viewing labels attached to a parameter using the console
A parameter version can have a maximum of ten labels. The following procedure describes how to view all labels attached to a parameter version by using the Systems Manager console.
**To view labels attached to a parameter version**
1. Open the AWS Systems Manager console at [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. In the navigation pane, choose **Parameter Store**.
1. Choose the name of a parameter to open the details page for that parameter.
1. Choose the **History** tab.
1. Locate the parameter version for which you want to view all attached labels. The **Labels** column shows all labels attached to the parameter version.
### Moving a parameter label using the console
The following procedure describes how to move a parameter label to a different version of the same parameter by using the Systems Manager console.
**To move a label to a different parameter version**
1. Open the AWS Systems Manager console at [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. In the navigation pane, choose **Parameter Store**.
1. Choose the name of a parameter to open the details page for that parameter.
1. Choose the **History** tab.
1. Choose the parameter version for which you want to move the label.
1. Choose **Manage labels**.
1. Choose **Add new label**.
1. In the text box, enter the label name.
1. When you're finished, choose **Save changes**.
### Deleting parameter labels using the console
The following procedure describes how to delete one or multiple parameter labels using the Systems Manager console.
**To delete labels from a parameter**
1. Open the AWS Systems Manager console at [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. In the navigation pane, choose **Parameter Store**.
1. Choose the name of a parameter to open the details page for that parameter.
1. Choose the **History** tab.
1. Choose the parameter version for which you want to delete labels.
1. Choose **Manage labels**.
1. Choose **Remove**. next to each label you want to delete.
1. When you're finished, choose **Save changes**.
1. Confirm that your changes are correct, enter `Confirm` in the text box, and choose **Confirm**.
## Working with parameter labels using the AWS CLI
This section describes how to perform the following tasks by using the AWS Command Line Interface (AWS CLI).
+ [Creating a new parameter label using the AWS CLI](#sysman-paramstore-labels-cli-create)
+ [Viewing labels for a parameter using the AWS CLI](#sysman-paramstore-labels-cli-view)
+ [Viewing a list of parameters that are assigned a label using the AWS CLI](#sysman-paramstore-labels-cli-view-param)
+ [Moving a parameter label using the AWS CLI](#sysman-paramstore-labels-cli-move)
+ [Deleting parameter labels using the AWS CLI](#systems-manager-parameter-store-labels-cli-delete)
### Creating a new parameter label using the AWS CLI
The following procedure describes how to attach a label to a specific version of an *existing* parameter by using the AWS CLI. You can't attach a label when you create a parameter.
**To create a parameter label**
1. Install and configure the AWS Command Line Interface (AWS CLI), if you haven't already.
For information, see [Installing or updating the latest version of the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
1. Run the following command to view a list of parameters for which you have permission to attach a label.
**Note**
Parameters are only available in the AWS Region where they were created. If you don't see a parameter for which you want to attach a label, then verify your Region.
```
aws ssm describe-parameters
```
Note the name of a parameter for which you want to attach a label.
1. Run the following command to view all versions of the parameter.
```
aws ssm get-parameter-history --name "parameter-name"
```
Note the parameter version for which you want to attach a label.
1. Run the following command to retrieve information about a parameter by version number.
```
aws ssm get-parameters --names "parameter-name:version-number"
```
Here is an example.
```
aws ssm get-parameters --names "/Production/SQLConnectionString:3"
```
1. Run one of the following commands to attach a label to a version of a parameter. If you attach multiple labels, separate label names with a space.
**Attach a label to the latest version of a parameter**
```
aws ssm label-parameter-version --name parameter-name --labels label-name
```
**Attach a label to a specific version of a parameter**
```
aws ssm label-parameter-version --name parameter-name --parameter-version version-number --labels label-name
```
Here are some examples.
```
aws ssm label-parameter-version --name /config/endpoint --labels production east-region finance
```
```
aws ssm label-parameter-version --name /config/endpoint --parameter-version 3 --labels MySQL-test
```
**Note**
If the output shows the label you created in the `InvalidLabels` list, then the label doesn't meet the requirements described earlier in this topic. Review the requirements and try again. If the `InvalidLabels` list is empty, then your label was successfully applied to the version of the parameter.
1. You can view the details of the parameter by using either a version number or a label name. Run the following command and specify the label you created in the previous step.
```
aws ssm get-parameter --name parameter-name:label-name --with-decryption
```
The command returns information like the following.
```
{
"Parameter": {
"Version": version-number,
"Type": "parameter-type",
"Name": "parameter-name",
"Value": "parameter-value",
"Selector": ":label-name"
}
}
```
**Note**
*Selector* in the output is either the version number or the label that you specified in the `Name` input field.
### Viewing labels for a parameter using the AWS CLI
You can use the [GetParameterHistory](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_GetParameterHistory.html) API operation to view the full history and all labels attached to a specified parameter. Or, you can use the [GetParametersByPath](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_GetParametersByPath.html) API operation to view a list of all parameters that are assigned a specific label.
**To view labels for a parameter by using the GetParameterHistory API operation**
1. Run the following command to view a list of parameters for which you can view labels.
**Note**
Parameters are only available in the Region where they were created. If you don't see a parameter for which you want to move a label, then verify your Region.
```
aws ssm describe-parameters
```
Note the name of the parameter you want to view the labels of.
1. Run the following command to view all versions of the parameter.
```
aws ssm get-parameter-history --name parameter-name --with-decryption
```
The system returns information like the following.
```
{
"Parameters": [
{
"Name": "/Config/endpoint",
"LastModifiedDate": 1528932105.382,
"Labels": [
"Deprecated"
],
"Value": "MyTestService-June-Release.example.com",
"Version": 1,
"LastModifiedUser": "arn:aws:iam::123456789012:user/test",
"Type": "String"
},
{
"Name": "/Config/endpoint",
"LastModifiedDate": 1528932111.222,
"Labels": [
"Current"
],
"Value": "MyTestService-July-Release.example.com",
"Version": 2,
"LastModifiedUser": "arn:aws:iam::123456789012:user/test",
"Type": "String"
}
]
}
```
### Viewing a list of parameters that are assigned a label using the AWS CLI
You can use the [GetParametersByPath](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_GetParametersByPath.html) API operation to view a list of all parameters in a path that are assigned a specific label.
Run the following command to view a list of parameters in a path that are assigned a specific label. Replace each *example resource placeholder* with your own information.
```
aws ssm get-parameters-by-path \
--path parameter-path \
--parameter-filters Key=Label,Values=label-name,Option=Equals \
--max-results a-number \
--with-decryption --recursive
```
The system returns information like the following. For this example, the user searched under the `/Config` path.
```
{
"Parameters": [
{
"Version": 3,
"Type": "SecureString",
"Name": "/Config/DBpwd",
"Value": "MyS@perGr&pass33"
},
{
"Version": 2,
"Type": "String",
"Name": "/Config/DBusername",
"Value": "TestUserDB"
},
{
"Version": 2,
"Type": "String",
"Name": "/Config/endpoint",
"Value": "MyTestService-July-Release.example.com"
}
]
}
```
### Moving a parameter label using the AWS CLI
The following procedure describes how to move a parameter label to a different version of the same parameter.
**To move a parameter label**
1. Run the following command to view all versions of the parameter. Replace *parameter name* with your own information.
```
aws ssm get-parameter-history \
--name "parameter name"
```
Note the parameter versions you want to move the label to and from.
1. Run the following command to assign an existing label to a different version of a parameter. Replace each *example resource placeholder* with your own information.
```
aws ssm label-parameter-version \
--name parameter name \
--parameter-version version number \
--labels name-of-existing-label
```
**Note**
If you want to move an existing label to the latest version of a parameter, then remove `--parameter-version` from the command.
### Deleting parameter labels using the AWS CLI
The following procedure describes how to delete parameter labels by using the AWS CLI.
**To delete a parameter label**
1. Run the following command to view all versions of the parameter. Replace *parameter name* with your own information.
```
aws ssm get-parameter-history \
--name "parameter name"
```
The system returns information like the following.
```
{
"Parameters": [
{
"Name": "foo",
"DataType": "text",
"LastModifiedDate": 1607380761.11,
"Labels": [
"l3",
"l2"
],
"Value": "test",
"Version": 1,
"LastModifiedUser": "arn:aws:iam::123456789012:user/test",
"Policies": [],
"Tier": "Standard",
"Type": "String"
},
{
"Name": "foo",
"DataType": "text",
"LastModifiedDate": 1607380763.11,
"Labels": [
"l1"
],
"Value": "test",
"Version": 2,
"LastModifiedUser": "arn:aws:iam::123456789012:user/test",
"Policies": [],
"Tier": "Standard",
"Type": "String"
}
]
}
```
Note the parameter version for which you want to delete a label or labels.
1. Run the following command to delete the labels you choose from that parameter. Replace each *example resource placeholder* with your own information.
```
aws ssm unlabel-parameter-version \
--name parameter name \
--parameter-version version \
--labels label 1,label 2,label 3
```
The system returns information like the following.
```
{
"InvalidLabels": ["invalid"],
"DeletedLabels" : ["Prod"]
}
```
# Working with parameter versions in Parameter Store
Each time you edit the value of a parameter, Parameter Store, a tool in AWS Systems Manager creates a new *version* of the parameter and retains the previous versions. When you initially create a parameter, Parameter Store assigns version `1` to that parameter. When you change the value of the parameter, Parameter Store automatically increments the version number by one. You can view the details, including the values, of all versions in a parameter's history.
You can also specify the version of a parameter to use in API commands and SSM documents; for example: `ssm:MyParameter:3`. You can specify a parameter name and a specific version number in API calls and SSM documents. If you don't specify a version number, the system automatically uses the latest version. If you specify the number for a version that doesn't exist, the system returns an error rather than falling back to the latest or default version of the parameter.
You can use parameter versions to see the number of times a parameter changed over a period of time. Parameter versions also provide a layer of protection if a parameter value is accidentally changed.
You can create and maintain up to 100 versions of a parameter. After you have created 100 versions of a parameter, each time you create a new version, the oldest version of the parameter is removed from history to make room for the new version.
An exception to this is when there are already 100 parameter versions in history, and a parameter label is assigned to the oldest version of a parameter. In this case, that version isn't removed from history, and the request to create a new parameter version fails. This safeguard is to prevent parameter versions with mission critical labels assigned to them from being deleted. To continue creating new parameters, first move the label from the oldest version of the parameter to a newer one for use in your operations. For information about moving parameter labels, see [Moving a parameter label using the console](sysman-paramstore-labels.md#sysman-paramstore-labels-console-move) and [Moving a parameter label using the AWS CLI](sysman-paramstore-labels.md#sysman-paramstore-labels-cli-move).
The following procedures show you how to edit a parameter and then verify that you created a new version. You can use the `get-parameter` and `get-parameters` commands to view parameter versions. For examples on using these commands, see [GetParameter](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_GetParameter.html#API_GetParameter_Examples) and [GetParameters](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_GetParameters.html#API_GetParameters_Examples) in the *AWS Systems Manager API Reference*
**Topics**
+ [Creating a new version of a parameter using the console](#sysman-paramstore-version-console)
+ [Referencing a parameter version](#reference-parameter-version)
## Creating a new version of a parameter using the console
You can use the Systems Manager console to create a new version of a parameter and view the version history of a parameter.
**To create a new version of a parameter**
1. Open the AWS Systems Manager console at [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. In the navigation pane, choose **Parameter Store**.
1. Choose the name of a parameter that you created earlier. For information about creating a new parameter, see [Creating Parameter Store parameters in Systems Manager](sysman-paramstore-su-create.md).
1. Choose **Edit**.
1. In the **Value** box, enter a new value, and then choose **Save changes**.
1. Choose the name of the parameter you just updated. On the **Overview** tab, verify that the version number incremented by 1, and verify the new value.
1. To view the history of all versions of a parameter, choose the **History** tab.
## Referencing a parameter version
You can reference specific parameter versions in commands, API calls, and SSM documents by using the following format: ssm:`parameter-name:version-number`.
In the following example, the Amazon Elastic Compute Cloud (Amazon EC2) `run-instances command` uses version 3 of the parameter `golden-ami`.
------
#### [ Linux & macOS ]
```
aws ec2 run-instances \
--image-id resolve:ssm:/golden-ami:3 \
--count 1 \
--instance-type t2.micro \
--key-name my-key-pair \
--security-groups my-security-group
```
------
#### [ Windows ]
```
aws ec2 run-instances ^
--image-id resolve:ssm:/golden-ami:3 ^
--count 1 ^
--instance-type t2.micro ^
--key-name my-key-pair ^
--security-groups my-security-group
```
------
**Note**
Using `resolve` and a parameter value only works with the `--image-id` option and a parameter that contains an Amazon Machine Image (AMI) as its value. For more information, see [Using native parameter support in Parameter Store for Amazon Machine Image IDs](parameter-store-ec2-aliases.md).
Here is an example for specifying version 2 of a parameter named `MyRunCommandParameter` in an SSM document.
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: Run a shell script or specify the commands to run.
parameters:
commands:
type: String
description: "(Required) Specify a shell script or a command to run."
displayType: textarea
default: "{{ssm:MyRunCommandParameter:2}}"
mainSteps:
- action: aws:runShellScript
name: RunScript
inputs:
runCommand:
- "{{commands}}"
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "Run a shell script or specify the commands to run.",
"parameters": {
"commands": {
"type": "String",
"description": "(Required) Specify a shell script or a command to run.",
"displayType": "textarea",
"default": "{{ssm:MyRunCommandParameter:2}}"
}
},
"mainSteps": [
{
"action": "aws:runShellScript",
"name": "RunScript",
"inputs": {
"runCommand": [
"{{commands}}"
]
}
}
]
}
```
------
# Working with shared parameters in Parameter Store
Sharing advanced parameters simplifies configuration data management in a multi-account environment. You can centrally store and manage your parameters and share them with other AWS accounts that need to reference them.
Parameter Store integrates with AWS Resource Access Manager (AWS RAM) to enable advanced parameter sharing. AWS RAM is a service that enables you to share resources with other AWS accounts or through AWS Organizations.
With AWS RAM, you share resources that you own by creating a resource share. A resource share specifies the resources to share, permissions to grant, and the consumers with whom to share. Consumers can include:
+ Specific AWS accounts inside or outside of its organization in AWS Organizations
+ An organizational unit inside its organization in AWS Organizations
+ Its entire organization in AWS Organizations
For more information about AWS RAM, see the *[AWS RAM User Guide](https://docs.aws.amazon.com/ram/latest/userguide/)*.
This topic explains how to share parameters that you own, and how to use parameters that are shared with you.
**Topics**
+ [Prerequisites for sharing parameters](#prereqs)
+ [Sharing a parameter](#share)
+ [Stop sharing a shared parameter](#unshare)
+ [Identifying shared parameters](#identify)
+ [Accessing shared parameters](#accessing)
+ [Permissions sets for sharing parameters](#sharing-permissions)
+ [Maximum throughput for shared parameters](#throughput)
+ [Pricing for shared parameters](#pricing)
+ [Cross-account access for closed AWS accounts](#closed-accounts)
## Prerequisites for sharing parameters
The following prerequisites must be met before you can share parameters from your account:
+ To share a parameter, you must own it in your AWS account. You can't share a parameter that has been shared with you.
+ To share a parameter, it must be in the advanced parameter tier. For information about parameter tiers, see [Managing parameter tiers](parameter-store-advanced-parameters.md). For information about changing an existing standard parameter to an advanced parameter, see [Changing a standard parameter to an advanced parameter](parameter-store-advanced-parameters-enabling.md).
+ To share a `SecureString` parameter, it must be encrypted with a customer managed key, and you must share the key separately through AWS Key Management Service. AWS managed keys cannot be shared. Parameters encrypted with the default AWS managed key can be updated to use a customer managed key instead. For AWS KMS key definitions, see [AWS KMS concepts](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-mgmt) in the *AWS Key Management Service Developer Guide*.
+ To share a parameter with your organization or an organizational unit in AWS Organizations, you must enable sharing with AWS Organizations. For more information, see [Enable Sharing with AWS Organizations](https://docs.aws.amazon.com/ram/latest/userguide/getting-started-sharing.html#getting-started-sharing-orgs) in the *AWS RAM User Guide*.
## Sharing a parameter
To share a parameter, you must add it to a resource share. A resource share is an AWS RAM resource that lets you share your resources across AWS accounts. A resource share specifies the resources to share, and the consumers with whom they are shared.
When you share a parameter that you own with other AWS accounts, you can choose from two AWS managed permissions to grant the consumers. For more information, see [Permissions sets for sharing parameters](#sharing-permissions).
If you are part of an organization in AWS Organizations and sharing within your organization is enabled, you can grant consumers in your organization access from the AWS RAM console to the shared parameter. Otherwise, consumers receive an invitation to join the resource share and are granted access to the shared parameter after accepting the invitation.
You can share a parameter that you own using the AWS RAM console, or the AWS CLI.
**Note**
While you can share a parameter using the Systems Manager [PutResourcePolicy](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_PutResourcePolicy.html) API operation, we recommend using AWS Resource Access Manager (AWS RAM) instead. This is because using `PutResourcePolicy` requires the extra step of promoting the parameter to a standard Resource Share using the AWS RAM [PromoteResourceShareCreatedFromPolicy](https://docs.aws.amazon.com/ram/latest/APIReference/API_PromoteResourceShareCreatedFromPolicy.html) API operation. Otherwise, the parameter won't be returned by the Systems Manager [DescribeParameters](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_DescribeParameters.html) API operation using the `--shared` option.
**To share a parameter that you own using the AWS RAM console**
See [Creating a resource share in AWS RAM](https://docs.aws.amazon.com/ram/latest/userguide/working-with-sharing.html#working-with-sharing-create) in the *AWS RAM User Guide*.
Make the following selections as you complete the procedure:
+ In the Step 1 page, for **Resources**, select `Parameter Store Advanced Parameter`, and then select the box of each parameter in the advanced parameter tier that you want to share.
+ In the Step 2 page, for **Managed permissions**, choose the permission to grant consumers, as described in [Permissions sets for sharing parameters](#sharing-permissions) later in this topic.
Choose other options based on your parameter sharing objectives.
**To share a parameter that you own using the AWS CLI**
Use the [https://docs.aws.amazon.com/cli/latest/reference/ram/create-resource-share.html](https://docs.aws.amazon.com/cli/latest/reference/ram/create-resource-share.html) command to add parameters to a new resource share.
Use the [https://docs.aws.amazon.com/cli/latest/reference/ram/associate-resource-share.html](https://docs.aws.amazon.com/cli/latest/reference/ram/associate-resource-share.html) command to add parameters to an existing resource share.
The following example creates a new resource share to share parameters with consumers in an organization and in an individual account.
```
aws ram create-resource-share \
--name "MyParameter" \
--resource-arns "arn:aws:ssm:us-east-2:123456789012:parameter/MyParameter" \
--principals "arn:aws:organizations::123456789012:ou/o-63bEXAMPLE/ou-46xi-rEXAMPLE" "987654321098"
```
## Stop sharing a shared parameter
When you stop sharing a shared parameter, the consumer account can no longer access the parameter.
To stop sharing a parameter that you own, you must remove it from the resource share. You can do this using the Systems Manager console, AWS RAM console, or the AWS CLI.
**To stop sharing a parameter that you own using the AWS RAM console**
See [Update a resource share in AWS RAM](https://docs.aws.amazon.com/ram/latest/userguide/working-with-sharing-update.html) in the *AWS RAM User Guide*.
**To stop sharing a parameter that you own using the AWS CLI**
Use the [disassociate-resource-share](https://docs.aws.amazon.com/cli/latest/reference/ram/disassociate-resource-share.html) command.
## Identifying shared parameters
Owners and consumers can identify shared parameters using the AWS CLI.
**To identify shared parameters using the AWS CLI**
To identify shared parameters using the AWS CLI, you can choose from the Systems Manager `[https://docs.aws.amazon.com/cli/latest/reference/ssm/describe-parameters.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/describe-parameters.html)` command and the AWS RAM `[list-resources](https://docs.aws.amazon.com/cli/latest/reference/ram/list-resources.html)` command.
When you use the `--shared` option with `describe-parameters`, the command returns the parameters that are shared with you.
The following is an example:
```
aws ssm describe-parameters --shared
```
## Accessing shared parameters
Consumers can access shared parameters using the AWS command line tools, and AWS SDKs. For consumer accounts, parameters shared with that account aren't included in the **My parameters** page.
**CLI Example: Accessing shared parameter details using the AWS CLI**
To access shared parameter details using the AWS CLI, you can use the [https://docs.aws.amazon.com/cli/latest/reference/ssm/get-parameter.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/get-parameter.html) or [https://docs.aws.amazon.com/cli/latest/reference/ssm/get-parameters.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/get-parameters.html) commands. You must specify the full parameter ARN as the `--name` in order to retrieve the parameter from another account.
The following is an example.
```
aws ssm get-parameter \
--name arn:aws:ssm:us-east-2:123456789012:parameter/MySharedParameter
```
**Supported and unsupported integrations for shared parameters**
Currently, you can use shared parameters in the following integration scenarios:
+ AWS CloudFormation [template parameters](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/parameters-section-structure.html#aws-ssm-parameter-types)
+ The [AWS Parameters and Secrets Lambda extension](ps-integration-lambda-extensions.md)
+ [Amazon Elastic Compute Cloud (EC2) launch templates](https://docs.aws.amazon.com/autoscaling/ec2/userguide/using-systems-manager-parameters.html)
+ Values for `ImageID` with the [EC2 RunInstances command](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_RunInstances.html) to create instances from an Amazon Machine Image (AMI)
+ [Retrieving parameter values in runbooks](https://repost.aws/knowledge-center/systems-manager-parameter-store) for Automation, a tool in Systems Manager
The following scenarios and integrated services do not currently support the use of shared parameters:
+ [Parameters in commands](sysman-param-runcommand.md) in Run Command, a tool in Systems Manager
+ AWS CloudFormation [dynamic references](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/dynamic-references.html)
+ The [values of environment variables](https://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html#build-spec.env.parameter-store) in AWS CodeBuild
+ The [values of environment variables](https://docs.aws.amazon.com/apprunner/latest/dg/env-variable.html) in AWS App Runner
+ The [value of a secret](https://docs.aws.amazon.com/AmazonECS/latest/userguide/secrets-envvar-ssm-paramstore.html) in Amazon Elastic Container Service
## Permissions sets for sharing parameters
Consumer accounts receive read-only access to the parameters you share with them. The consumer can't update or delete the parameter. The consumer can't share the parameter with a third account.
When you create a resource share in AWS Resource Access Manager for sharing your parameters, you can choose from two AWS managed permission sets to grant this read-only access:
**AWSRAMDefaultPermissionSSMParameterReadOnly**
Allowed actions: `DescribeParameters`, `GetParameter`, `GetParameters`
**AWSRAMPermissionSSMParameterReadOnlyWithHistory**
Allowed actions: `DescribeParameters`, `GetParameter`, `GetParameters`, `GetParameterHistory`
When you folllow the steps in [Creating a resource share in AWS RAM](https://docs.aws.amazon.com/ram/latest/userguide/working-with-sharing.html#working-with-sharing-create) in the *AWS RAM User Guide*, choose `Parameter Store Advanced Parameters` as the resource type and either of these managed permissions, depending on whether you want users to view parameter history or not.
**Note**
If you're retrieving shared parameters programmatically (for example, using AWS Lambda) you might need to add the `ssm:GetResourcePolicies` and `ssm:PutResourcePolicy` permissions to any IAM roles calling AWS Resource Access Manager API actions.
## Maximum throughput for shared parameters
Systems Manager limits the maximum throughput (transactions per second) for the [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_GetParameter.html](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_GetParameter.html) and [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_GetParameters.html](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_GetParameters.html). operations. Throughput is enforced at the individual account level. Therefore, each account that consumes a shared parameter can use its maximum allowed throughput without being affected by other accounts. For more information about maximum throughput for parameters, see the following topics:
+ [Increasing Parameter Store throughput](https://docs.aws.amazon.com/systems-manager/latest/userguide/parameter-store-throughput.html)
+ [Systems Manager Service quotas](https://docs.aws.amazon.com/general/latest/gr/ssm.html#limits_ssm) in the *Amazon Web Services General Reference*.
## Pricing for shared parameters
Cross-account sharing is only available in the advanced parameter tier. For advanced parameters, charges are incurred at the current price for the *storage* and *API usage* for each advanced parameter. The owning account is charged for storage of the advanced parameter. Any consuming account that makes an API call to a shared advanced parameter is charged for the parameter usage.
For example, if Account A creates an advanced parameter, `MyAdvancedParameter`, that account is charged USD 0.05 per month to store the parameter.
Account A then shares `MyAdvancedParameter` with Account B and Account C. During a month, the three accounts make calls to `MyAdvancedParameter`. The following table illustrates the charges they would incur for the number of calls each makes.
**Note**
The charges in the following table are for illustration only. To verify current pricing, see [AWS Systems Manager Pricing for Parameter Store](https://aws.amazon.com/systems-manager/pricing/#Parameter_Store).
| Account | Number of calls | Charges |
| --- | --- | --- |
| Account A (owning account) | 10,000 calls | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/systems-manager/latest/userguide/parameter-store-shared-parameters.html) |
| Account B (consuming account) | 20,000 calls | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/systems-manager/latest/userguide/parameter-store-shared-parameters.html) |
| Account C (consuming account) | 30,000 calls | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/systems-manager/latest/userguide/parameter-store-shared-parameters.html) |
## Cross-account access for closed AWS accounts
If the AWS account that owns a shared parameter is closed, all consuming accounts lose access to the shared parameter. If the owning account is reopened within 90 days after the account is closed, consuming accounts regain access to the previously shared parameters. For more information about reopening an account during the Post-Closure Period, see [Accessing your AWS account after you close it](https://docs.aws.amazon.com/accounts/latest/reference/manage-acct-closing.html#accessing-after-closure) in the *AWS Account Management Reference Guide*.
# Working with parameters in Parameter Store using Run Command commands
You can work with parameters in Run Command, a tool in AWS Systems Manager. For more information, see [AWS Systems Manager Run Command](run-command.md).
## Running a String parameter using the console
The following procedure walks you through the process of running a command that uses a `String` parameter.
**To run a String parameter using Parameter Store**
1. Open the AWS Systems Manager console at [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. In the navigation pane, choose **Run Command**.
1. Choose **Run command**.
1. In the **Command document** list, choose `AWS-RunPowerShellScript` (Windows) or `AWS-RunShellScript` (Linux).
1. For **Command parameters**, enter **echo \$1\$1ssm:*parameter-name*\$1\$1**. For example: **echo \$1\$1ssm:/Test/helloWorld\$1\$1**.
1. In the **Targets** section, choose the managed nodes on which you want to run this operation by specifying tags, selecting instances or edge devices manually, or specifying a resource group.
**Tip**
If a managed node you expect to see isn't listed, see [Troubleshooting managed node availability](fleet-manager-troubleshooting-managed-nodes.md) for troubleshooting tips.
1. For **Other parameters**:
+ For **Comment**, enter information about this command.
+ For **Timeout (seconds)**, specify the number of seconds for the system to wait before failing the overall command execution.
1. For **Rate control**:
+ For **Concurrency**, specify either a number or a percentage of managed nodes on which to run the command at the same time.
**Note**
If you selected targets by specifying tags applied to managed nodes or by specifying AWS resource groups, and you aren't certain how many managed nodes are targeted, then restrict the number of targets that can run the document at the same time by specifying a percentage.
+ For **Error threshold**, specify when to stop running the command on other managed nodes after it fails on either a number or a percentage of nodes. For example, if you specify three errors, then Systems Manager stops sending the command when the fourth error is received. Managed nodes still processing the command might also send errors.
1. (Optional) For **Output options**, to save the command output to a file, select the **Write command output to an S3 bucket** box. Enter the bucket and prefix (folder) names in the boxes.
**Note**
The S3 permissions that grant the ability to write the data to an S3 bucket are those of the instance profile (for EC2 instances) or IAM service role (hybrid-activated machines) assigned to the instance, not those of the IAM user performing this task. For more information, see [Configure instance permissions required for Systems Manager](setup-instance-permissions.md) or [Create an IAM service role for a hybrid environment](hybrid-multicloud-service-role.md). In addition, if the specified S3 bucket is in a different AWS account, make sure that the instance profile or IAM service role associated with the managed node has the necessary permissions to write to that bucket.
1. In the **SNS notifications** section, if you want notifications sent about the status of the command execution, select the **Enable SNS notifications** check box.
For more information about configuring Amazon SNS notifications for Run Command, see [Monitoring Systems Manager status changes using Amazon SNS notifications](monitoring-sns-notifications.md).
1. Choose **Run**.
1. In the **Command ID** page, in the **Targets and outputs** area, select the button next to the ID of a node where you ran the command, and then choose **View output**. Verify that the output of the command is the value you provided for the parameter, such as **This is my first parameter**.
## Running a parameter using the AWS CLI
**Example 1: Simple command**
The following example command includes a Systems Manager parameter named `DNS-IP`. The value of this parameter is simply the IP address of a node. This example uses an AWS Command Line Interface (AWS CLI) command to echo the parameter value.
------
#### [ Linux & macOS ]
```
aws ssm send-command \
--document-name "AWS-RunShellScript" \
--document-version "1" \
--targets "Key=instanceids,Values=i-02573cafcfEXAMPLE" \
--parameters "commands='echo {{ssm:DNS-IP}}'" \
--timeout-seconds 600 \
--max-concurrency "50" \
--max-errors "0" \
--region us-east-2
```
------
#### [ Windows ]
```
aws ssm send-command ^
--document-name "AWS-RunPowerShellScript" ^
--document-version "1" ^
--targets "Key=instanceids,Values=i-02573cafcfEXAMPLE" ^
--parameters "commands='echo {{ssm:DNS-IP}}'" ^
--timeout-seconds 600 ^
--max-concurrency "50" ^
--max-errors "0" ^
--region us-east-2
```
------
The command returns information like the following.
```
{
"Command": {
"CommandId": "c70a4671-8098-42da-b885-89716EXAMPLE",
"DocumentName": "AWS-RunShellScript",
"DocumentVersion": "1",
"Comment": "",
"ExpiresAfter": "2023-12-26T15:19:17.771000-05:00",
"Parameters": {
"commands": [
"echo {{ssm:DNS-IP}}"
]
},
"InstanceIds": [],
"Targets": [
{
"Key": "instanceids",
"Values": [
"i-02573cafcfEXAMPLE"
]
}
],
"RequestedDateTime": "2023-12-26T14:09:17.771000-05:00",
"Status": "Pending",
"StatusDetails": "Pending",
"OutputS3Region": "us-east-2",
"OutputS3BucketName": "",
"OutputS3KeyPrefix": "",
"MaxConcurrency": "50",
"MaxErrors": "0",
"TargetCount": 0,
"CompletedCount": 0,
"ErrorCount": 0,
"DeliveryTimedOutCount": 0,
"ServiceRole": "",
"NotificationConfig": {
"NotificationArn": "",
"NotificationEvents": [],
"NotificationType": ""
},
"CloudWatchOutputConfig": {
"CloudWatchLogGroupName": "",
"CloudWatchOutputEnabled": false
},
"TimeoutSeconds": 600,
"AlarmConfiguration": {
"IgnorePollAlarmFailure": false,
"Alarms": []
},
"TriggeredAlarms": []
}
}
```
After a command execution completes, you can view more information about it using the following commands:
+ [https://docs.aws.amazon.com/cli/latest/reference/ssm/get-command-invocation.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/get-command-invocation.html) – View detailed information about the command execution.
+ [https://docs.aws.amazon.com/cli/latest/reference/ssm/link-cli-ref-list-command-invocations.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/link-cli-ref-list-command-invocations.html) – View the command execution status on a specific managed node.
+ [https://docs.aws.amazon.com/cli/latest/reference/ssm/link-cli-ref-list-commands.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/link-cli-ref-list-commands.html) – View the command execution status across managed nodes.
**Example 2: Decrypt a `SecureString` parameter value**
The next example command uses a `SecureString` parameter named **SecurePassword**. The command used in the `parameters` field retrieves and decrypts the value of the `SecureString` parameter, and then resets the local administrator password without having to pass the password in clear text.
------
#### [ Linux ]
```
aws ssm send-command \
--document-name "AWS-RunShellScript" \
--document-version "1" \
--targets "Key=instanceids,Values=i-02573cafcfEXAMPLE" \
--parameters '{"commands":["secure=$(aws ssm get-parameters --names SecurePassword --with-decryption --query Parameters[0].Value --output text --region us-east-2)","echo $secure | passwd myuser --stdin"]}' \
--timeout-seconds 600 \
--max-concurrency "50" \
--max-errors "0" \
--region us-east-2
```
------
#### [ Windows ]
```
aws ssm send-command ^
--document-name "AWS-RunPowerShellScript" ^
--document-version "1" ^
--targets "Key=instanceids,Values=i-02573cafcfEXAMPLE" ^
--parameters "commands=['$secure = (Get-SSMParameterValue -Names SecurePassword -WithDecryption $True).Parameters[0].Value','net user administrator $secure']" ^
--timeout-seconds 600 ^
--max-concurrency "50" ^
--max-errors "0" ^
--region us-east-2
```
------
**Example 3: Reference a parameter in an SSM document**
You can also reference Systems Manager parameters in the *Parameters* section of an SSM document, as shown in the following example.
```
{
"schemaVersion":"2.0",
"description":"Sample version 2.0 document v2",
"parameters":{
"commands" : {
"type": "StringList",
"default": ["{{ssm:parameter-name}}"]
}
},
"mainSteps":[
{
"action":"aws:runShellScript",
"name":"runShellScript",
"inputs":{
"runCommand": "{{commands}}"
}
}
]
}
```
Don't confuse the similar syntax for *local parameters* used in the `runtimeConfig` section of SSM documents with Parameter Store parameters. A local parameter isn't the same as a Systems Manager parameter. You can distinguish local parameters from Systems Manager parameters by the absence of the `ssm:` prefix.
```
"runtimeConfig":{
"aws:runShellScript":{
"properties":[
{
"id":"0.aws:runShellScript",
"runCommand":"{{ commands }}",
"workingDirectory":"{{ workingDirectory }}",
"timeoutSeconds":"{{ executionTimeout }}"
```
**Note**
SSM documents don't support references to `SecureString` parameters. This means that to use `SecureString` parameters with, for example, Run Command, you have to retrieve the parameter value before passing it to Run Command, as shown in the following examples.
```
value=$(aws ssm get-parameters --names parameter-name --with-decryption)
```
```
aws ssm send-command \
--name AWS-JoinDomain \
--parameters password=$value \
--instance-id instance-id
```
```
aws ssm send-command ^
--name AWS-JoinDomain ^
--parameters password=$value ^
--instance-id instance-id
```
```
$secure = (Get-SSMParameterValue -Names parameter-name -WithDecryption $True).Parameters[0].Value | ConvertTo-SecureString -AsPlainText -Force
```
```
$cred = New-Object System.Management.Automation.PSCredential -argumentlist user-name,$secure
```
# Using native parameter support in Parameter Store for Amazon Machine Image IDs
When you create a `String` parameter, you can specify the *data type* as `aws:ec2:image` to ensure that the parameter value you enter is a valid Amazon Machine Image (AMI) ID format.
Support for AMI ID formats allows you to avoid updating all your scripts and templates with a new ID each time the AMI that you want to use in your processes changes. You can create a parameter with the data type `aws:ec2:image`, and for its value, enter the ID of an AMI. This is the AMI you want to create new instances from. You then reference this parameter in your templates, commands, and scripts.
For example, you can specify the parameter that contains your preferred AMI ID when you run the Amazon Elastic Compute Cloud (Amazon EC2) `run-instances` command.
**Note**
The user who runs this command must have AWS Identity and Access Management (IAM) permissions that include the `ssm:GetParameters` API operation in order for the parameter value to be validated. Otherwise, the parameter creation process fails.
------
#### [ Linux & macOS ]
```
aws ec2 run-instances \
--image-id resolve:ssm:/golden-ami \
--count 1 \
--instance-type t2.micro \
--key-name my-key-pair \
--security-groups my-security-group
```
------
#### [ Windows ]
```
aws ec2 run-instances ^
--image-id resolve:ssm:/golden-ami ^
--count 1 ^
--instance-type t2.micro ^
--key-name my-key-pair ^
--security-groups my-security-group
```
------
You can also choose your preferred AMI when you create an instance using the Amazon EC2 console. For more information, see [Using a Systems Manager parameter to find an AMI](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/finding-an-ami.html#using-systems-manager-parameter-to-find-AMI) in the *Amazon EC2 User Guide*.
When it's time to use a different AMI in your instance creation workflow, you need only update the parameter with the new AMI value, and Parameter Store again validates that you have entered an ID in the proper format.
## Granting permissions to create a parameter of `aws:ec2:image` data type
Using AWS Identity and Access Management (IAM) policies, you can provide or restrict user access to Parameter Store API operations and content.
To create an `aws:ec2:image` data type parameter, the user must have both `ssm:PutParameter` and `ec2:DescribeImages` permissions.
The following example policy grants users permission to call the `PutParameter` API operation for `aws:ec2:image`. This means that the user can add a parameter of data type `aws:ec2:image` to the system.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "ssm:PutParameter",
"Resource": "*"
},
{
"Effect": "Allow",
"Action": "ec2:DescribeImages",
"Resource": "*"
}
]
}
```
------
## How AMI format validation works
When you specify `aws:ec2:image` as the data type for a parameter, Systems Manager doesn't create the parameter immediately. It instead performs an asynchronous validation operation to ensure that the parameter value meets the formatting requirements for an AMI ID, and that the specified AMI is available in your AWS account.
A parameter version number might be generated before the validation operation is complete. The operation might not be complete even if a parameter version number is generated.
To monitor whether your parameters are created successfully, we recommend using Amazon EventBridge to send you notifications about your `create` and `update` parameter operations. These notifications report whether a parameter operation was successful or not. If an operation fails, the notification includes an error message that indicates the reason for the failure.
```
{
"version": "0",
"id": "eed4a719-0fa4-6a49-80d8-8ac65EXAMPLE",
"detail-type": "Parameter Store Change",
"source": "aws.ssm",
"account": "111122223333",
"time": "2020-05-26T22:04:42Z",
"region": "us-east-2",
"resources": [
"arn:aws:ssm:us-east-2:111122223333:parameter/golden-ami"
],
"detail": {
"exception": "Unable to Describe Resource",
"dataType": "aws:ec2:image",
"name": "golden-ami",
"type": "String",
"operation": "Create"
}
}
```
For information about subscribing to Parameter Store events in EventBridge, see [Setting up notifications or triggering actions based on Parameter Store events](sysman-paramstore-cwe.md).
# Deleting parameters from Parameter Store
This topic describes how to delete parameters that you have created in Parameter Store, a tool in AWS Systems Manager.
**Warning**
Deleting a parameter removes all versions of it. Once deleted, the parameter and its versions can't be restored.
**To delete a parameter using the console**
1. Open the AWS Systems Manager console at [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. In the navigation pane, choose **Parameter Store**.
1. On the **My parameters** tab, select the check box next to each parameter to delete.
1. Choose **Delete**.
1. On the confirmation dialog, choose **Delete parameters**.
**To delete a parameter using the AWS CLI**
+ Run the following command:
```
aws ssm delete-parameter --name "my-parameter"
```
Replace *my-parameter* with the name of your parameter to be deleted.
For information about all options available for use with the `delete-parameter` command, see [https://docs.aws.amazon.com/cli/latest/reference/ssm/delete-parameter.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/delete-parameter.html) in the *AWS Systems Manager section of the AWS CLI Command Reference*.
# Working with public parameters in Parameter Store
Some AWS services publish information about common artifacts as AWS Systems Manager *public* parameters. For example, the Amazon Elastic Compute Cloud (Amazon EC2) service publishes information about Amazon Machine Images (AMIs) as public parameters.
**Topics**
+ [Discovering public parameters in Parameter Store](parameter-store-finding-public-parameters.md)
+ [Calling AMI public parameters in Parameter Store](parameter-store-public-parameters-ami.md)
+ [Calling the ECS optimized AMI public parameter in Parameter Store](parameter-store-public-parameters-ecs.md)
+ [Calling the EKS optimized AMI public parameter in Parameter Store](parameter-store-public-parameters-eks.md)
+ [Calling public parameters for AWS services, Regions, endpoints, Availability Zones, local zones, and Wavelength Zones in Parameter Store](parameter-store-public-parameters-global-infrastructure.md)
**Related AWS blog posts**
+ [Query for AWS Regions, Endpoints, and More Using AWS Systems Manager Parameter Store](https://aws.amazon.com/blogs/aws/new-query-for-aws-regions-endpoints-and-more-using-aws-systems-manager-parameter-store/)
+ [Query for the latest Amazon Linux AMI IDs using AWS Systems Manager Parameter Store](https://aws.amazon.com/blogs/compute/query-for-the-latest-amazon-linux-ami-ids-using-aws-systems-manager-parameter-store/)
+ [Query for the Latest Windows AMI Using AWS Systems Manager Parameter Store](https://aws.amazon.com/blogs/mt/query-for-the-latest-windows-ami-using-systems-manager-parameter-store/)
# Discovering public parameters in Parameter Store
You can search for public parameters using the Parameter Store console or the AWS Command Line Interface.
A public parameter name begins with `aws/service/list`. The next part of the name corresponds to the service that owns that parameter.
The following is a partial list of AWS services and other resources that provide public parameters:
+ `ami-amazon-linux-latest`
+ `ami-windows-latest`
+ `ec2-macos`
+ `appmesh`
+ `aws-for-fluent-bit`
+ `aws-sdk-pandas`
+ `bottlerocket`
+ `canonical`
+ `cloud9`
+ `datasync`
+ `deeplearning`
+ `ecs`
+ `eks`
+ `fis`
+ `freebsd`
+ `global-infrastructure`
+ `marketplace`
+ `neuron`
+ `powertools`
+ `sagemaker-distribution`
+ `storagegateway`
Not all public parameters are published to every AWS Region.
## Finding public parameters using the Parameter Store console
You must have at least one parameter in your AWS account and AWS Region before you can search for public parameters using the console.
**To find public parameters using the console**
1. Open the AWS Systems Manager console at [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. In the navigation pane, choose **Parameter Store**.
1. Choose the **Public parameters** tab.
1. Choose the **Select a service** dropdown. Choose the service whose parameters you want to use.
1. (Optional) Filter the parameters owned by the service you selected by entering more information into the search bar.
1. Choose the public parameter you want to use.
## Finding public parameters using the AWS CLI
Use `describe-parameters` for discovery of public parameters.
Use `get-parameters-by-path` to get the actual path for a service listed under `/aws/service/list`. To get the service's path, remove `/list` from the path. For example, `/aws/service/list/ecs` becomes `/aws/service/ecs`.
To retrieve a list of public parameters owned by different services in Parameter Store, run the following command.
```
aws ssm get-parameters-by-path --path /aws/service/list
```
The command returns information like the following. This example has been truncated for space.
```
{
"Parameters": [
{
"Name": "/aws/service/list/ami-al-latest",
"Type": "String",
"Value": "/aws/service/ami-al-latest/",
"Version": 1,
"LastModifiedDate": "2021-01-29T10:25:10.902000-08:00",
"ARN": "arn:aws:ssm:us-east-2::parameter/aws/service/list/ami-al-latest",
"DataType": "text"
},
{
"Name": "/aws/service/list/ami-windows-latest",
"Type": "String",
"Value": "/aws/service/ami-windows-latest/",
"Version": 1,
"LastModifiedDate": "2021-01-29T10:25:12.567000-08:00",
"ARN": "arn:aws:ssm:us-east-2::parameter/aws/service/list/ami-windows-latest",
"DataType": "text"
},
{
"Name": "/aws/service/list/aws-storage-gateway-latest",
"Type": "String",
"Value": "/aws/service/aws-storage-gateway-latest/",
"Version": 1,
"LastModifiedDate": "2021-01-29T10:25:09.903000-08:00",
"ARN": "arn:aws:ssm:us-east-2::parameter/aws/service/list/aws-storage-gateway-latest",
"DataType": "text"
},
{
"Name": "/aws/service/list/global-infrastructure",
"Type": "String",
"Value": "/aws/service/global-infrastructure/",
"Version": 1,
"LastModifiedDate": "2021-01-29T10:25:11.901000-08:00",
"ARN": "arn:aws:ssm:us-east-2::parameter/aws/service/list/global-infrastructure",
"DataType": "text"
}
]
}
```
If you want to view parameters owned by a specific service, choose the service from the list that was produced after running the earlier command. Then, make a `get-parameters-by-path` call using the name of your desired service.
For example, `/aws/service/global-infrastructure`. The path might be one-level (only calls parameters that match the exact values given) or recursive (contains elements in the path beyond what you have given).
**Note**
The `/aws/service/global-infrastructure` path is not supported for queries in all Regions. For information, see [Calling public parameters for AWS services, Regions, endpoints, Availability Zones, local zones, and Wavelength Zones in Parameter Store](parameter-store-public-parameters-global-infrastructure.md).
If no results are returned for the service you specify, add the `--recursive` flag and run the command again.
```
aws ssm get-parameters-by-path --path /aws/service/global-infrastructure
```
This returns all parameters owned by `global-infrastructure`. The following is an example.
```
{
"Parameters": [
{
"Name": "/aws/service/global-infrastructure/current-region",
"Type": "String",
"LastModifiedDate": "2019-06-21T05:15:34.252000-07:00",
"Version": 1,
"Tier": "Standard",
"Policies": [],
"DataType": "text"
},
{
"Name": "/aws/service/global-infrastructure/version",
"Type": "String",
"LastModifiedDate": "2019-02-04T06:59:32.875000-08:00",
"Version": 1,
"Tier": "Standard",
"Policies": [],
"DataType": "text"
}
]
}
```
You can also view parameters owned by a specific service by using the `Option:BeginsWith` filter.
```
aws ssm describe-parameters --parameter-filters "Key=Name, Option=BeginsWith, Values=/aws/service/ami-amazon-linux-latest"
```
The command returns information like the following. This example output has been truncated for space.
```
{
"Parameters": [
{
"Name": "/aws/service/ami-amazon-linux-latest/amzn-ami-hvm-x86_64-ebs",
"Type": "String",
"LastModifiedDate": "2021-01-26T13:39:40.686000-08:00",
"Version": 25,
"Tier": "Standard",
"Policies": [],
"DataType": "text"
},
{
"Name": "/aws/service/ami-amazon-linux-latest/amzn-ami-hvm-x86_64-gp2",
"Type": "String",
"LastModifiedDate": "2021-01-26T13:39:40.807000-08:00",
"Version": 25,
"Tier": "Standard",
"Policies": [],
"DataType": "text"
},
{
"Name": "/aws/service/ami-amazon-linux-latest/amzn-ami-hvm-x86_64-s3",
"Type": "String",
"LastModifiedDate": "2021-01-26T13:39:40.920000-08:00",
"Version": 25,
"Tier": "Standard",
"Policies": [],
"DataType": "text"
}
]
}
```
**Note**
The returned parameters might be different when you use `Option=BeginsWith` because it uses a different search pattern.
# Calling AMI public parameters in Parameter Store
Amazon Elastic Compute Cloud (Amazon EC2) Amazon Machine Image (AMI) public parameters are available for Amazon Linux 2, Amazon Linux 2023 (AL2023), macOS, and Windows Server from the following paths:
+ Amazon Linux 2, and Amazon Linux 2023: `/aws/service/ami-amazon-linux-latest`
+ macOS: `/aws/service/ec2-macos`
+ Windows Server: `/aws/service/ami-windows-latest`
## Calling AMI public parameters for Amazon Linux 2 and Amazon Linux 2023
You can view a list of all Amazon Linux 2 and Amazon Linux 2023 (AL2023) AMIs in the current AWS Region by using the following command in the AWS Command Line Interface (AWS CLI).
------
#### [ Linux & macOS ]
```
aws ssm get-parameters-by-path \
--path /aws/service/ami-amazon-linux-latest \
--query 'Parameters[].Name'
```
------
#### [ Windows ]
```
aws ssm get-parameters-by-path ^
--path /aws/service/ami-amazon-linux-latest ^
--query Parameters[].Name
```
------
The command returns information like the following.
```
[
"/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-6.1-arm64",
"/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-6.1-x86_64",
"/aws/service/ami-amazon-linux-latest/al2023-ami-minimal-kernel-6.1-arm64",
"/aws/service/ami-amazon-linux-latest/al2023-ami-minimal-kernel-6.1-x86_64",
"/aws/service/ami-amazon-linux-latest/al2023-ami-minimal-kernel-default-arm64",
"/aws/service/ami-amazon-linux-latest/amzn-ami-hvm-x86_64-gp2",
"/aws/service/ami-amazon-linux-latest/amzn-ami-hvm-x86_64-s3",
"/aws/service/ami-amazon-linux-latest/amzn2-ami-hvm-x86_64-ebs",
"/aws/service/ami-amazon-linux-latest/amzn2-ami-hvm-x86_64-gp2",
"/aws/service/ami-amazon-linux-latest/amzn2-ami-kernel-5.10-hvm-x86_64-ebs",
"/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-default-arm64",
"/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-default-x86_64",
"/aws/service/ami-amazon-linux-latest/al2023-ami-minimal-kernel-default-x86_64",
"/aws/service/ami-amazon-linux-latest/amzn-ami-hvm-x86_64-ebs",
"/aws/service/ami-amazon-linux-latest/amzn-ami-minimal-hvm-x86_64-ebs",
"/aws/service/ami-amazon-linux-latest/amzn-ami-minimal-hvm-x86_64-s3",
"/aws/service/ami-amazon-linux-latest/amzn2-ami-hvm-arm64-gp2",
"/aws/service/ami-amazon-linux-latest/amzn2-ami-kernel-5.10-hvm-arm64-gp2",
"/aws/service/ami-amazon-linux-latest/amzn2-ami-kernel-5.10-hvm-x86_64-gp2",
"/aws/service/ami-amazon-linux-latest/amzn2-ami-minimal-hvm-arm64-ebs",
"/aws/service/ami-amazon-linux-latest/amzn2-ami-minimal-hvm-x86_64-ebs"
]
```
You can view details about these AMIs, including the AMI IDs and Amazon Resource Names (ARNs), by using the following command.
------
#### [ Linux & macOS ]
```
aws ssm get-parameters-by-path \
--path "/aws/service/ami-amazon-linux-latest" \
--region region
```
------
#### [ Windows ]
```
aws ssm get-parameters-by-path ^
--path "/aws/service/ami-amazon-linux-latest" ^
--region region
```
------
*region* represents the identifier for an AWS Region supported by AWS Systems Manager, such as `us-east-2` for the US East (Ohio) Region. For a list of supported *region* values, see the **Region** column in [Systems Manager service endpoints](https://docs.aws.amazon.com/general/latest/gr/ssm.html#ssm_region) in the *Amazon Web Services General Reference*.
The command returns information like the following. This example output has been truncated for space.
```
{
"Parameters": [
{
"Name": "/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-6.1-arm64",
"Type": "String",
"Value": "ami-0b1b8b24a6c8e5d8b",
"Version": 69,
"LastModifiedDate": "2024-03-13T14:05:09.583000-04:00",
"ARN": "arn:aws:ssm:us-east-2::parameter/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-6.1-arm64",
"DataType": "text"
},
{
"Name": "/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-6.1-x86_64",
"Type": "String",
"Value": "ami-0e0bf53f6def86294",
"Version": 69,
"LastModifiedDate": "2024-03-13T14:05:09.890000-04:00",
"ARN": "arn:aws:ssm:us-east-2::parameter/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-6.1-x86_64",
"DataType": "text"
},
{
"Name": "/aws/service/ami-amazon-linux-latest/al2023-ami-minimal-kernel-6.1-arm64",
"Type": "String",
"Value": "ami-09951bb66f9e5b5a5",
"Version": 69,
"LastModifiedDate": "2024-03-13T14:05:10.197000-04:00",
"ARN": "arn:aws:ssm:us-east-2::parameter/aws/service/ami-amazon-linux-latest/al2023-ami-minimal-kernel-6.1-arm64",
"DataType": "text"
}
]
}
```
You can view details of a specific AMI by using the [GetParameters](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_GetParameters.html) API operation with the full AMI name, including the path. Here is an example command.
------
#### [ Linux & macOS ]
```
aws ssm get-parameters \
--names /aws/service/ami-amazon-linux-latest/al2023-ami-kernel-6.1-arm64 \
--region us-east-2
```
------
#### [ Windows ]
```
aws ssm get-parameters ^
--names /aws/service/ami-amazon-linux-latest/al2023-ami-kernel-6.1-arm64 ^
--region us-east-2
```
------
The command returns the following information.
```
{
"Parameters": [
{
"Name": "/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-6.1-arm64",
"Type": "String",
"Value": "ami-0b1b8b24a6c8e5d8b",
"Version": 69,
"LastModifiedDate": "2024-03-13T14:05:09.583000-04:00",
"ARN": "arn:aws:ssm:us-east-2::parameter/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-6.1-arm64",
"DataType": "text"
}
],
"InvalidParameters": []
}
```
## Calling AMI public parameters for macOS
You can view a list of all macOS AMIs in the current AWS Region by using the following command in the AWS CLI.
------
#### [ Linux & macOS ]
```
aws ssm get-parameters-by-path \
--path /aws/service/ec2-macos\
--query 'Parameters[].Name'
```
------
#### [ Windows ]
```
aws ssm get-parameters-by-path ^
--path /aws/service/ec2-macos ^
--query Parameters[].Name
```
------
The command returns information like the following.
```
[
"/aws/service/ec2-macos/sonoma/x86_64_mac/latest/image_id",
"/aws/service/ec2-macos/ventura/x86_64_mac/latest/image_id",
"/aws/service/ec2-macos/sonoma/arm64_mac/latest/image_id",
"/aws/service/ec2-macos/ventura/arm64_mac/latest/image_id"
]
```
You can view details about these AMIs, including the AMI IDs and Amazon Resource Names (ARNs), by using the following command.
------
#### [ Linux & macOS ]
```
aws ssm get-parameters-by-path \
--path "/aws/service/ec2-macos" \
--region region
```
------
#### [ Windows ]
```
aws ssm get-parameters-by-path ^
--path "/aws/service/ec2-macos" ^
--region region
```
------
*region* represents the identifier for an AWS Region supported by AWS Systems Manager, such as `us-east-2` for the US East (Ohio) Region. For a list of supported *region* values, see the **Region** column in [Systems Manager service endpoints](https://docs.aws.amazon.com/general/latest/gr/ssm.html#ssm_region) in the *Amazon Web Services General Reference*.
The command returns information like the following. This example output has been truncated for space.
```
{
"Parameters": [
...sample results pending...
]
}
```
You can view details of a specific AMI by using the [GetParameters](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_GetParameters.html) API operation with the full AMI name, including the path. Here is an example command.
------
#### [ Linux & macOS ]
```
aws ssm get-parameters \
--names /aws/service/ec2-macos/...pending... \
--region us-east-2
```
------
#### [ Windows ]
```
aws ssm get-parameters ^
--names /aws/service/ec2-macos/...pending... ^
--region us-east-2
```
------
The command returns the following information.
```
{
"Parameters": [
...sample results pending...
],
"InvalidParameters": []
}
```
## Calling AMI public parameters for Windows Server
You can view a list of all Windows Server AMIs in the current AWS Region by using the following command in the AWS CLI.
------
#### [ Linux & macOS ]
```
aws ssm get-parameters-by-path \
--path /aws/service/ami-windows-latest \
--query 'Parameters[].Name'
```
------
#### [ Windows ]
```
aws ssm get-parameters-by-path ^
--path /aws/service/ami-windows-latest ^
--query Parameters[].Name
```
------
The command returns information like the following. This example output has been truncated for space.
```
[
"/aws/service/ami-windows-latest/EC2LaunchV2-Windows_Server-2016-English-Full-Base",
"/aws/service/ami-windows-latest/Windows_Server-2016-English-Full-SQL_2014_SP3_Enterprise",
"/aws/service/ami-windows-latest/Windows_Server-2016-German-Full-Base",
"/aws/service/ami-windows-latest/Windows_Server-2016-Japanese-Full-SQL_2016_SP3_Standard",
"/aws/service/ami-windows-latest/Windows_Server-2016-Japanese-Full-SQL_2017_Web",
"/aws/service/ami-windows-latest/Windows_Server-2019-English-Core-EKS_Optimized-1.25",
"/aws/service/ami-windows-latest/Windows_Server-2019-Italian-Full-Base",
"/aws/service/ami-windows-latest/Windows_Server-2022-Japanese-Full-SQL_2019_Enterprise",
"/aws/service/ami-windows-latest/Windows_Server-2022-Portuguese_Brazil-Full-Base",
"/aws/service/ami-windows-latest/amzn2-ami-hvm-2.0.20191217.0-x86_64-gp2-mono",
"/aws/service/ami-windows-latest/Windows_Server-2016-English-Deep-Learning",
"/aws/service/ami-windows-latest/Windows_Server-2016-Japanese-Full-SQL_2016_SP3_Web",
"/aws/service/ami-windows-latest/Windows_Server-2016-Korean-Full-Base",
"/aws/service/ami-windows-latest/Windows_Server-2019-English-STIG-Core",
"/aws/service/ami-windows-latest/Windows_Server-2019-French-Full-Base",
"/aws/service/ami-windows-latest/Windows_Server-2019-Japanese-Full-SQL_2017_Enterprise",
"/aws/service/ami-windows-latest/Windows_Server-2019-Korean-Full-Base",
"/aws/service/ami-windows-latest/Windows_Server-2022-English-Full-SQL_2022_Web",
"/aws/service/ami-windows-latest/Windows_Server-2022-Italian-Full-Base",
"/aws/service/ami-windows-latest/amzn2-x86_64-SQL_2019_Express",
"/aws/service/ami-windows-latest/EC2LaunchV2-Windows_Server-2016-English-Core-Base",
"/aws/service/ami-windows-latest/Windows_Server-2016-English-Full-SQL_2019_Enterprise",
"/aws/service/ami-windows-latest/Windows_Server-2016-English-Full-SQL_2019_Standard",
"/aws/service/ami-windows-latest/Windows_Server-2016-Portuguese_Portugal-Full-Base",
"/aws/service/ami-windows-latest/Windows_Server-2019-English-Core-EKS_Optimized-1.24",
"/aws/service/ami-windows-latest/Windows_Server-2019-English-Deep-Learning",
"/aws/service/ami-windows-latest/Windows_Server-2019-English-Full-SQL_2017_Web",
"/aws/service/ami-windows-latest/Windows_Server-2019-Hungarian-Full-Base
]
```
You can view details about these AMIs, including the AMI IDs and Amazon Resource Names (ARNs), by using the following command.
------
#### [ Linux & macOS ]
```
aws ssm get-parameters-by-path \
--path "/aws/service/ami-windows-latest" \
--region region
```
------
#### [ Windows ]
```
aws ssm get-parameters-by-path ^
--path "/aws/service/ami-windows-latest" ^
--region region
```
------
*region* represents the identifier for an AWS Region supported by AWS Systems Manager, such as `us-east-2` for the US East (Ohio) Region. For a list of supported *region* values, see the **Region** column in [Systems Manager service endpoints](https://docs.aws.amazon.com/general/latest/gr/ssm.html#ssm_region) in the *Amazon Web Services General Reference*.
The command returns information like the following. This example output has been truncated for space.
```
{
"Parameters": [
{
"Name": "/aws/service/ami-windows-latest/EC2LaunchV2-Windows_Server-2016-English-Full-Base",
"Type": "String",
"Value": "ami-0a30b2e65863e2d16",
"Version": 36,
"LastModifiedDate": "2024-03-15T15:58:37.976000-04:00",
"ARN": "arn:aws:ssm:us-east-2::parameter/aws/service/ami-windows-latest/EC2LaunchV2-Windows_Server-2016-English-Full-Base",
"DataType": "text"
},
{
"Name": "/aws/service/ami-windows-latest/Windows_Server-2016-English-Full-SQL_2014_SP3_Enterprise",
"Type": "String",
"Value": "ami-001f20c053dd120ce",
"Version": 69,
"LastModifiedDate": "2024-03-15T15:53:58.905000-04:00",
"ARN": "arn:aws:ssm:us-east-2::parameter/aws/service/ami-windows-latest/Windows_Server-2016-English-Full-SQL_2014_SP3_Enterprise",
"DataType": "text"
},
{
"Name": "/aws/service/ami-windows-latest/Windows_Server-2016-German-Full-Base",
"Type": "String",
"Value": "ami-063be4935453e94e9",
"Version": 102,
"LastModifiedDate": "2024-03-15T15:51:12.003000-04:00",
"ARN": "arn:aws:ssm:us-east-2::parameter/aws/service/ami-windows-latest/Windows_Server-2016-German-Full-Base",
"DataType": "text"
}
]
}
```
You can view details of a specific AMI by using the [GetParameters](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_GetParameters.html) API operation with the full AMI name, including the path. Here is an example command.
------
#### [ Linux & macOS ]
```
aws ssm get-parameters \
--names /aws/service/ami-windows-latest/EC2LaunchV2-Windows_Server-2016-English-Full-Base \
--region us-east-2
```
------
#### [ Windows ]
```
aws ssm get-parameters ^
--names /aws/service/ami-windows-latest/EC2LaunchV2-Windows_Server-2016-English-Full-Base ^
--region us-east-2
```
------
The command returns the following information.
```
{
"Parameters": [
{
"Name": "/aws/service/ami-windows-latest/EC2LaunchV2-Windows_Server-2016-English-Full-Base",
"Type": "String",
"Value": "ami-0a30b2e65863e2d16",
"Version": 36,
"LastModifiedDate": "2024-03-15T15:58:37.976000-04:00",
"ARN": "arn:aws:ssm:us-east-2::parameter/aws/service/ami-windows-latest/EC2LaunchV2-Windows_Server-2016-English-Full-Base",
"DataType": "text"
}
],
"InvalidParameters": []
}
```
# Calling the ECS optimized AMI public parameter in Parameter Store
The Amazon Elastic Container Service (Amazon ECS) service publishes the name of the latest Amazon ECS optimized Amazon Machine Images (AMIs) as public parameters. Users are encouraged to use this AMI when creating a new Amazon Elastic Compute Cloud (Amazon EC2) cluster for Amazon ECS because the optimized AMIs include bug fixes and feature updates.
Use the following command to view the name of the latest Amazon ECS optimized AMI for Amazon Linux 2. To see commands for other operating systems, see [Retrieving Amazon ECS-Optimized AMI metadata ](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/retrieve-ecs-optimized_AMI.html) in the *Amazon Elastic Container Service Developer Guide*.
------
#### [ Linux & macOS ]
```
aws ssm get-parameters \
--names /aws/service/ecs/optimized-ami/amazon-linux-2/recommended
```
------
#### [ Windows ]
```
aws ssm get-parameters ^
--names /aws/service/ecs/optimized-ami/amazon-linux-2/recommended
```
------
The command returns information like the following.
```
{
"Parameters": [
{
"Name": "/aws/service/ecs/optimized-ami/amazon-linux-2/recommended",
"Type": "String",
"Value": "{\"schema_version\":1,\"image_name\":\"amzn2-ami-ecs-hvm-2.0.20210929-x86_64-ebs\",\"image_id\":\"ami-0c38a2329ed4dae9a\",\"os\":\"Amazon Linux 2\",\"ecs_runtime_version\":\"Docker version 20.10.7\",\"ecs_agent_version\":\"1.55.4\"}",
"Version": 73,
"LastModifiedDate": "2021-10-06T16:35:10.004000-07:00",
"ARN": "arn:aws:ssm:us-east-2::parameter/aws/service/ecs/optimized-ami/amazon-linux-2/recommended",
"DataType": "text"
}
],
"InvalidParameters": []
}
```
# Calling the EKS optimized AMI public parameter in Parameter Store
The Amazon Elastic Kubernetes Service (Amazon EKS) service publishes the name of the latest Amazon EKS optimized Amazon Machine Image (AMI) as a public parameter. We encourage you to use this AMI when adding nodes to an Amazon EKS cluster, as new releases include Kubernetes patches and security updates. Previously, to guarantee you were using the latest AMI meant checking the Amazon EKS documentation and manually updating any deployment templates or resources with the new AMI ID.
Use the following command to view the name of the latest Amazon EKS optimized AMI for Amazon Linux 2.
------
#### [ Linux & macOS ]
```
aws ssm get-parameters \
--names /aws/service/eks/optimized-ami/1.14/amazon-linux-2/recommended
```
------
#### [ Windows ]
```
aws ssm get-parameters ^
--names /aws/service/eks/optimized-ami/1.14/amazon-linux-2/recommended
```
------
The command returns information like the following.
```
{
"Parameters": [
{
"Name": "/aws/service/eks/optimized-ami/1.14/amazon-linux-2/recommended",
"Type": "String",
"Value": "{\"schema_version\":\"2\",\"image_id\":\"ami-08984d8491de17ca0\",\"image_name\":\"amazon-eks-node-1.14-v20201007\",\"release_version\":\"1.14.9-20201007\"}",
"Version": 24,
"LastModifiedDate": "2020-11-17T10:16:09.971000-08:00",
"ARN": "arn:aws:ssm:us-east-2::parameter/aws/service/eks/optimized-ami/1.14/amazon-linux-2/recommended",
"DataType": "text"
}
],
"InvalidParameters": []
}
```
# Calling public parameters for AWS services, Regions, endpoints, Availability Zones, local zones, and Wavelength Zones in Parameter Store
You can call the AWS Region, service, endpoint, Availability, and Wavelength Zones of public parameters by using the following path.
`/aws/service/global-infrastructure`
**Note**
Currently, the path `/aws/service/global-infrastructure` is supported for queries in the following AWS Regions only:
US East (N. Virginia) (us-east-1)
US East (Ohio) (us-east-2)
US West (N. California) (us-west-1)
US West (Oregon) (us-west-2)
Asia Pacific (Hong Kong) (ap-east-1)
Asia Pacific (Mumbai) (ap-south-1)
Asia Pacific (Seoul) (ap-northeast-2)
Asia Pacific (Singapore) (ap-southeast-1)
Asia Pacific (Sydney) (ap-southeast-2)
Asia Pacific (Tokyo) (ap-northeast-1)
Canada (Central) (ca-central-1)
Europe (Frankfurt) (eu-central-1)
Europe (Ireland) (eu-west-1)
Europe (London) (eu-west-2)
Europe (Paris) (eu-west-3)
Europe (Stockholm) (eu-north-1)
South America (São Paulo) (sa-east-1)
If you are working in a different [commercial Region](https://docs.aws.amazon.com/glossary/latest/reference/glos-chap.html#region), you can specify a supported Region in your query to view results. For example, if you are working in the Canada West (Calgary) (ca-west-1) Region, you could specify Canada (Central) (ca-central-1) in your query:
```
aws ssm get-parameters-by-path \
--path /aws/service/global-infrastructure/regions \
--region ca-central-1
```
**View active AWS Regions**
You can view a list of all active AWS Regions by using the following command in the AWS Command Line Interface (AWS CLI).
------
#### [ Linux & macOS ]
```
aws ssm get-parameters-by-path \
--path /aws/service/global-infrastructure/regions \
--query 'Parameters[].Name'
```
------
#### [ Windows ]
```
aws ssm get-parameters-by-path ^
--path /aws/service/global-infrastructure/regions ^
--query Parameters[].Name
```
------
The command returns information like the following.
```
[
"/aws/service/global-infrastructure/regions/af-south-1",
"/aws/service/global-infrastructure/regions/ap-east-1",
"/aws/service/global-infrastructure/regions/ap-northeast-3",
"/aws/service/global-infrastructure/regions/ap-south-2",
"/aws/service/global-infrastructure/regions/ca-central-1",
"/aws/service/global-infrastructure/regions/eu-central-2",
"/aws/service/global-infrastructure/regions/eu-west-2",
"/aws/service/global-infrastructure/regions/eu-west-3",
"/aws/service/global-infrastructure/regions/us-east-1",
"/aws/service/global-infrastructure/regions/us-gov-west-1",
"/aws/service/global-infrastructure/regions/ap-northeast-2",
"/aws/service/global-infrastructure/regions/ap-southeast-1",
"/aws/service/global-infrastructure/regions/ap-southeast-2",
"/aws/service/global-infrastructure/regions/ap-southeast-3",
"/aws/service/global-infrastructure/regions/cn-north-1",
"/aws/service/global-infrastructure/regions/cn-northwest-1",
"/aws/service/global-infrastructure/regions/eu-south-1",
"/aws/service/global-infrastructure/regions/eu-south-2",
"/aws/service/global-infrastructure/regions/us-east-2",
"/aws/service/global-infrastructure/regions/us-west-1",
"/aws/service/global-infrastructure/regions/ap-northeast-1",
"/aws/service/global-infrastructure/regions/ap-south-1",
"/aws/service/global-infrastructure/regions/ap-southeast-4",
"/aws/service/global-infrastructure/regions/ca-west-1",
"/aws/service/global-infrastructure/regions/eu-central-1",
"/aws/service/global-infrastructure/regions/il-central-1",
"/aws/service/global-infrastructure/regions/me-central-1",
"/aws/service/global-infrastructure/regions/me-south-1",
"/aws/service/global-infrastructure/regions/sa-east-1",
"/aws/service/global-infrastructure/regions/us-gov-east-1",
"/aws/service/global-infrastructure/regions/eu-north-1",
"/aws/service/global-infrastructure/regions/eu-west-1",
"/aws/service/global-infrastructure/regions/us-west-2"
]
```
**View available AWS services**
You can view a complete list of all available AWS services and sort them into alphabetical order by using the following command. This example output has been truncated for space.
------
#### [ Linux & macOS ]
```
aws ssm get-parameters-by-path \
--path /aws/service/global-infrastructure/services \
--query 'Parameters[].Name | sort(@)'
```
------
#### [ Windows ]
```
aws ssm get-parameters-by-path ^
--path /aws/service/global-infrastructure/services ^
--query "Parameters[].Name | sort(@)"
```
------
The command returns information like the following. This example has been truncated for space.
```
[
"/aws/service/global-infrastructure/services/accessanalyzer",
"/aws/service/global-infrastructure/services/account",
"/aws/service/global-infrastructure/services/acm",
"/aws/service/global-infrastructure/services/acm-pca",
"/aws/service/global-infrastructure/services/ahl",
"/aws/service/global-infrastructure/services/aiq",
"/aws/service/global-infrastructure/services/amazonlocationservice",
"/aws/service/global-infrastructure/services/amplify",
"/aws/service/global-infrastructure/services/amplifybackend",
"/aws/service/global-infrastructure/services/apigateway",
"/aws/service/global-infrastructure/services/apigatewaymanagementapi",
"/aws/service/global-infrastructure/services/apigatewayv2",
"/aws/service/global-infrastructure/services/appconfig",
"/aws/service/global-infrastructure/services/appconfigdata",
"/aws/service/global-infrastructure/services/appflow",
"/aws/service/global-infrastructure/services/appintegrations",
"/aws/service/global-infrastructure/services/application-autoscaling",
"/aws/service/global-infrastructure/services/application-insights",
"/aws/service/global-infrastructure/services/applicationcostprofiler",
"/aws/service/global-infrastructure/services/appmesh",
"/aws/service/global-infrastructure/services/apprunner",
"/aws/service/global-infrastructure/services/appstream",
"/aws/service/global-infrastructure/services/appsync",
"/aws/service/global-infrastructure/services/aps",
"/aws/service/global-infrastructure/services/arc-zonal-shift",
"/aws/service/global-infrastructure/services/artifact",
"/aws/service/global-infrastructure/services/athena",
"/aws/service/global-infrastructure/services/auditmanager",
"/aws/service/global-infrastructure/services/augmentedairuntime",
"/aws/service/global-infrastructure/services/aurora",
"/aws/service/global-infrastructure/services/autoscaling",
"/aws/service/global-infrastructure/services/aws-appfabric",
"/aws/service/global-infrastructure/services/awshealthdashboard",
```
**View supported Regions for an AWS service**
You can view a list of AWS Regions where a service is available. This example uses AWS Systems Manager (`ssm`).
------
#### [ Linux & macOS ]
```
aws ssm get-parameters-by-path \
--path /aws/service/global-infrastructure/services/ssm/regions \
--query 'Parameters[].Value'
```
------
#### [ Windows ]
```
aws ssm get-parameters-by-path ^
--path /aws/service/global-infrastructure/services/ssm/regions ^
--query Parameters[].Value
```
------
The command returns information like the following.
```
[
"ap-south-1",
"eu-central-1",
"eu-central-2",
"eu-west-1",
"eu-west-2",
"eu-west-3",
"il-central-1",
"me-south-1",
"us-east-2",
"us-gov-west-1",
"af-south-1",
"ap-northeast-3",
"ap-southeast-1",
"ap-southeast-4",
"ca-central-1",
"ca-west-1",
"cn-north-1",
"eu-north-1",
"eu-south-2",
"us-west-1",
"ap-east-1",
"ap-northeast-1",
"ap-northeast-2",
"ap-southeast-2",
"ap-southeast-3",
"cn-northwest-1",
"eu-south-1",
"me-central-1",
"us-gov-east-1",
"us-west-2",
"ap-south-2",
"sa-east-1",
"us-east-1"
]
```
**View the Regional endpoint for a service**
You can view a Regional endpoint for a service by using the following command. This command queries the US East (Ohio) (us-east-2) Region.
------
#### [ Linux & macOS ]
```
aws ssm get-parameter \
--name /aws/service/global-infrastructure/regions/us-east-2/services/ssm/endpoint \
--query 'Parameter.Value'
```
------
#### [ Windows ]
```
aws ssm get-parameter ^
--name /aws/service/global-infrastructure/regions/us-east-2/services/ssm/endpoint ^
--query Parameter.Value
```
------
The command returns information like the following.
```
"ssm.us-east-2.amazonaws.com"
```
**View complete Availability Zone details**
You can view Availability Zones by using the following command.
------
#### [ Linux & macOS ]
```
aws ssm get-parameters-by-path \
--path /aws/service/global-infrastructure/availability-zones/
```
------
#### [ Windows ]
```
aws ssm get-parameters-by-path ^
--path /aws/service/global-infrastructure/availability-zones/
```
------
The command returns information like the following. This example has been truncated for space.
```
{
"Parameters": [
{
"Name": "/aws/service/global-infrastructure/availability-zones/afs1-az3",
"Type": "String",
"Value": "afs1-az3",
"Version": 1,
"LastModifiedDate": "2020-04-21T12:05:35.375000-04:00",
"ARN": "arn:aws:ssm:us-east-2::parameter/aws/service/global-infrastructure/availability-zones/afs1-az3",
"DataType": "text"
},
{
"Name": "/aws/service/global-infrastructure/availability-zones/aps1-az2",
"Type": "String",
"Value": "aps1-az2",
"Version": 1,
"LastModifiedDate": "2020-04-03T16:13:57.351000-04:00",
"ARN": "arn:aws:ssm:us-east-2::parameter/aws/service/global-infrastructure/availability-zones/aps1-az2",
"DataType": "text"
},
{
"Name": "/aws/service/global-infrastructure/availability-zones/apse3-az1",
"Type": "String",
"Value": "apse3-az1",
"Version": 1,
"LastModifiedDate": "2021-12-13T08:51:38.983000-05:00",
"ARN": "arn:aws:ssm:us-east-2::parameter/aws/service/global-infrastructure/availability-zones/apse3-az1",
"DataType": "text"
}
]
}
```
**View Availability Zone names only**
You can view the names of Availability Zones only by using the following command.
------
#### [ Linux & macOS ]
```
aws ssm get-parameters-by-path \
--path /aws/service/global-infrastructure/availability-zones \
--query 'Parameters[].Name | sort(@)'
```
------
#### [ Windows ]
```
aws ssm get-parameters-by-path ^
--path /aws/service/global-infrastructure/availability-zones ^
--query "Parameters[].Name | sort(@)"
```
------
The command returns information like the following. This example has been truncated for space.
```
[
"/aws/service/global-infrastructure/availability-zones/afs1-az1",
"/aws/service/global-infrastructure/availability-zones/afs1-az2",
"/aws/service/global-infrastructure/availability-zones/afs1-az3",
"/aws/service/global-infrastructure/availability-zones/ape1-az1",
"/aws/service/global-infrastructure/availability-zones/ape1-az2",
"/aws/service/global-infrastructure/availability-zones/ape1-az3",
"/aws/service/global-infrastructure/availability-zones/apne1-az1",
"/aws/service/global-infrastructure/availability-zones/apne1-az2",
"/aws/service/global-infrastructure/availability-zones/apne1-az3",
"/aws/service/global-infrastructure/availability-zones/apne1-az4"
```
**View names of Availability Zones in a single Region**
You can view the names of the Availability Zones in one Region (`us-east-2`, in this example) using the following command.
------
#### [ Linux & macOS ]
```
aws ssm get-parameters-by-path \
--path /aws/service/global-infrastructure/regions/us-east-2/availability-zones \
--query 'Parameters[].Name | sort(@)'
```
------
#### [ Windows ]
```
aws ssm get-parameters-by-path ^
--path /aws/service/global-infrastructure/regions/us-east-2/availability-zones ^
--query "Parameters[].Name | sort(@)"
```
------
The command returns information like the following.
```
[
"/aws/service/global-infrastructure/regions/us-east-2/availability-zones/use2-az1",
"/aws/service/global-infrastructure/regions/us-east-2/availability-zones/use2-az2",
"/aws/service/global-infrastructure/regions/us-east-2/availability-zones/use2-az3"
```
**View Availability Zone ARNs only**
You can view the Amazon Resource Names (ARNs) of Availability Zones only by using the following command.
------
#### [ Linux & macOS ]
```
aws ssm get-parameters-by-path \
--path /aws/service/global-infrastructure/availability-zones \
--query 'Parameters[].ARN | sort(@)'
```
------
#### [ Windows ]
```
aws ssm get-parameters-by-path ^
--path /aws/service/global-infrastructure/availability-zones ^
--query "Parameters[].ARN | sort(@)"
```
------
The command returns information like the following. This example has been truncated for space.
```
[
"arn:aws:ssm:us-east-2::parameter/aws/service/global-infrastructure/availability-zones/afs1-az1",
"arn:aws:ssm:us-east-2::parameter/aws/service/global-infrastructure/availability-zones/afs1-az2",
"arn:aws:ssm:us-east-2::parameter/aws/service/global-infrastructure/availability-zones/afs1-az3",
"arn:aws:ssm:us-east-2::parameter/aws/service/global-infrastructure/availability-zones/ape1-az1",
"arn:aws:ssm:us-east-2::parameter/aws/service/global-infrastructure/availability-zones/ape1-az2",
"arn:aws:ssm:us-east-2::parameter/aws/service/global-infrastructure/availability-zones/ape1-az3",
"arn:aws:ssm:us-east-2::parameter/aws/service/global-infrastructure/availability-zones/apne1-az1",
```
**View local zone details**
You can view local zones by using the following command.
------
#### [ Linux & macOS ]
```
aws ssm get-parameters-by-path \
--path /aws/service/global-infrastructure/local-zones
```
------
#### [ Windows ]
```
aws ssm get-parameters-by-path ^
--path /aws/service/global-infrastructure/local-zones
```
------
The command returns information like the following. This example has been truncated for space.
```
{
"Parameters": [
{
"Name": "/aws/service/global-infrastructure/local-zones/afs1-los1-az1",
"Type": "String",
"Value": "afs1-los1-az1",
"Version": 1,
"LastModifiedDate": "2023-01-25T11:53:11.690000-05:00",
"ARN": "arn:aws:ssm:us-east-2::parameter/aws/service/global-infrastructure/local-zones/afs1-los1-az1",
"DataType": "text"
},
{
"Name": "/aws/service/global-infrastructure/local-zones/apne1-tpe1-az1",
"Type": "String",
"Value": "apne1-tpe1-az1",
"Version": 1,
"LastModifiedDate": "2024-03-15T12:35:41.076000-04:00",
"ARN": "arn:aws:ssm:us-east-2::parameter/aws/service/global-infrastructure/local-zones/apne1-tpe1-az1",
"DataType": "text"
},
{
"Name": "/aws/service/global-infrastructure/local-zones/aps1-ccu1-az1",
"Type": "String",
"Value": "aps1-ccu1-az1",
"Version": 1,
"LastModifiedDate": "2022-12-19T11:34:43.351000-05:00",
"ARN": "arn:aws:ssm:us-east-2::parameter/aws/service/global-infrastructure/local-zones/aps1-ccu1-az1",
"DataType": "text"
}
]
}
```
**View Wavelength Zone details**
You can view Wavelength Zones by using the following command.
------
#### [ Linux & macOS ]
```
aws ssm get-parameters-by-path \
--path /aws/service/global-infrastructure/wavelength-zones
```
------
#### [ Windows ]
```
aws ssm get-parameters-by-path ^
--path /aws/service/global-infrastructure/wavelength-zones
```
------
The command returns information like the following. This example has been truncated for space.
```
{
"Parameters": [
{
"Name": "/aws/service/global-infrastructure/wavelength-zones/apne1-wl1-nrt-wlz1",
"Type": "String",
"Value": "apne1-wl1-nrt-wlz1",
"Version": 3,
"LastModifiedDate": "2020-12-15T17:16:04.715000-05:00",
"ARN": "arn:aws:ssm:us-east-2::parameter/aws/service/global-infrastructure/wavelength-zones/apne1-wl1-nrt-wlz1",
"DataType": "text"
},
{
"Name": "/aws/service/global-infrastructure/wavelength-zones/apne2-wl1-sel-wlz1",
"Type": "String",
"Value": "apne2-wl1-sel-wlz1",
"Version": 1,
"LastModifiedDate": "2022-05-25T12:29:13.862000-04:00",
"ARN": "arn:aws:ssm:us-east-2::parameter/aws/service/global-infrastructure/wavelength-zones/apne2-wl1-sel-wlz1",
"DataType": "text"
},
{
"Name": "/aws/service/global-infrastructure/wavelength-zones/cac1-wl1-yto-wlz1",
"Type": "String",
"Value": "cac1-wl1-yto-wlz1",
"Version": 1,
"LastModifiedDate": "2022-04-26T09:57:44.495000-04:00",
"ARN": "arn:aws:ssm:us-east-2::parameter/aws/service/global-infrastructure/wavelength-zones/cac1-wl1-yto-wlz1",
"DataType": "text"
}
]
}
```
**View all parameters and values under a local zone**
You can view all parameter data for a local zone by using the following command.
------
#### [ Linux & macOS ]
```
aws ssm get-parameters-by-path \
--path "/aws/service/global-infrastructure/local-zones/usw2-lax1-az1/"
```
------
#### [ Windows ]
```
aws ssm get-parameters-by-path ^
--path "/aws/service/global-infrastructure/local-zones/use1-bos1-az1"
```
------
The command returns information like the following. This example has been truncated for space.
```
{
"Parameters": [
{
"Name": "/aws/service/global-infrastructure/local-zones/use1-bos1-az1/geolocationCountry",
"Type": "String",
"Value": "US",
"Version": 3,
"LastModifiedDate": "2020-12-15T14:16:17.641000-08:00",
"ARN": "arn:aws:ssm:us-east-2::parameter/aws/service/global-infrastructure/local-zones/use1-bos1-az1/geolocationCountry",
"DataType": "text"
},
{
"Name": "/aws/service/global-infrastructure/local-zones/use1-bos1-az1/geolocationRegion",
"Type": "String",
"Value": "US-MA",
"Version": 3,
"LastModifiedDate": "2020-12-15T14:16:17.794000-08:00",
"ARN": "arn:aws:ssm:us-east-2::parameter/aws/service/global-infrastructure/local-zones/use1-bos1-az1/geolocationRegion",
"DataType": "text"
},
{
"Name": "/aws/service/global-infrastructure/local-zones/use1-bos1-az1/location",
"Type": "String",
"Value": "US East (Boston)",
"Version": 1,
"LastModifiedDate": "2021-01-11T10:53:24.634000-08:00",
"ARN": "arn:aws:ssm:us-east-2::parameter/aws/service/global-infrastructure/local-zones/use1-bos1-az1/location",
"DataType": "text"
},
{
"Name": "/aws/service/global-infrastructure/local-zones/use1-bos1-az1/network-border-group",
"Type": "String",
"Value": "us-east-1-bos-1",
"Version": 3,
"LastModifiedDate": "2020-12-15T14:16:20.641000-08:00",
"ARN": "arn:aws:ssm:us-east-2::parameter/aws/service/global-infrastructure/local-zones/use1-bos1-az1/network-border-group",
"DataType": "text"
},
{
"Name": "/aws/service/global-infrastructure/local-zones/use1-bos1-az1/parent-availability-zone",
"Type": "String",
"Value": "use1-az4",
"Version": 3,
"LastModifiedDate": "2020-12-15T14:16:20.834000-08:00",
"ARN": "arn:aws:ssm:us-east-2::parameter/aws/service/global-infrastructure/local-zones/use1-bos1-az1/parent-availability-zone",
"DataType": "text"
},
{
"Name": "/aws/service/global-infrastructure/local-zones/use1-bos1-az1/parent-region",
"Type": "String",
"Value": "us-east-1",
"Version": 3,
"LastModifiedDate": "2020-12-15T14:16:20.721000-08:00",
"ARN": "arn:aws:ssm:us-east-2::parameter/aws/service/global-infrastructure/local-zones/use1-bos1-az1/parent-region",
"DataType": "text"
},
{
"Name": "/aws/service/global-infrastructure/local-zones/use1-bos1-az1/zone-group",
"Type": "String",
"Value": "us-east-1-bos-1",
"Version": 3,
"LastModifiedDate": "2020-12-15T14:16:17.983000-08:00",
"ARN": "arn:aws:ssm:us-east-2::parameter/aws/service/global-infrastructure/local-zones/use1-bos1-az1/zone-group",
"DataType": "text"
}
]
}
```
**View local zone parameter names only**
You can view just the names of local zone parameters by using the following command.
------
#### [ Linux & macOS ]
```
aws ssm get-parameters-by-path \
--path /aws/service/global-infrastructure/local-zones/usw2-lax1-az1 \
--query 'Parameters[].Name | sort(@)'
```
------
#### [ Windows ]
```
aws ssm get-parameters-by-path ^
--path /aws/service/global-infrastructure/local-zones/use1-bos1-az1 ^
--query "Parameters[].Name | sort(@)"
```
------
The command returns information like the following.
```
[
"/aws/service/global-infrastructure/local-zones/use1-bos1-az1/geolocationCountry",
"/aws/service/global-infrastructure/local-zones/use1-bos1-az1/geolocationRegion",
"/aws/service/global-infrastructure/local-zones/use1-bos1-az1/location",
"/aws/service/global-infrastructure/local-zones/use1-bos1-az1/network-border-group",
"/aws/service/global-infrastructure/local-zones/use1-bos1-az1/parent-availability-zone",
"/aws/service/global-infrastructure/local-zones/use1-bos1-az1/parent-region",
"/aws/service/global-infrastructure/local-zones/use1-bos1-az1/zone-group"
]
```
# Parameter Store walkthroughs
The walkthrough in this section shows you how to create, store, and run parameters with Parameter Store in a test environment. This walkthrough shows you how to use Parameter Store with other Systems Manager tools. You can also use Parameter Store with other AWS services. For more information, see [What is a parameter?](systems-manager-parameter-store.md#what-is-a-parameter).
**Topics**
+ [Creating a SecureString parameter in Parameter Store and joining a node to a Domain (PowerShell)](sysman-param-securestring-walkthrough.md)
# Creating a SecureString parameter in Parameter Store and joining a node to a Domain (PowerShell)
This walkthrough shows how to join a Windows Server node to a domain using AWS Systems Manager `SecureString` parameters and Run Command. The walkthrough uses typical domain parameters, such as the domain name and a domain user name. These values are passed as unencrypted string values. The domain password is encrypted using an AWS managed key and passed as an encrypted string.
**Prerequisites**
This walkthrough assumes that you already specified your domain name and DNS server IP address in the DHCP option set that is associated with your Amazon VPC. For information, see [Working with DHCP Options Sets](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_DHCP_Options.html#DHCPOptionSet) in the *Amazon VPC User Guide*.
**To create a `SecureString` parameter and join a node to a domain**
1. Enter parameters into the system using AWS Tools for Windows PowerShell.
In the following commands, replace each *user input placeholder* with your own information.
```
Write-SSMParameter -Name "domainName" -Value "DOMAIN-NAME" -Type String
Write-SSMParameter -Name "domainJoinUserName" -Value "DOMAIN\USERNAME" -Type String
Write-SSMParameter -Name "domainJoinPassword" -Value "PASSWORD" -Type SecureString
```
**Important**
Only the *value* of a `SecureString` parameter is encrypted. Parameter names, descriptions, and other properties aren't encrypted.
1. Attach the following AWS Identity and Access Management (IAM) policies to the IAM role permissions for your node:
+ **AmazonSSMManagedInstanceCore** – Required. This AWS managed policy allows a managed node to use Systems Manager service core functionality.
+ **AmazonSSMDirectoryServiceAccess** – Required. This AWS managed policy allows SSM Agent to access AWS Directory Service on your behalf for requests to join the domain by the managed node.
+ **A custom policy for S3 bucket access** – Required. SSM Agent, which is on your node and performs Systems Manager tasks, requires access to specific Amazon-owned Amazon Simple Storage Service (Amazon S3) buckets. In the custom S3 bucket policy that you create, you also provide access to S3 buckets of your own that are necessary for Systems Manager operations.
Examples: You can write output for Run Command commands or Session Manager sessions to an S3 bucket, and then use this output later for auditing or troubleshooting. You store access scripts or custom patch baseline lists in an S3 bucket, and then reference the script or list when you run a command, or when a patch baseline is applied.
For information about creating a custom policy for Amazon S3 bucket access, see [Create a custom S3 bucket policy for an instance profile](setup-instance-permissions.md#instance-profile-custom-s3-policy)
**Note**
Saving output log data in an S3 bucket is optional, but we recommend setting it up at the beginning of your Systems Manager configuration process if you have decided to use it. For more information, see [Create a Bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/CreatingABucket.html) in the *Amazon Simple Storage Service User Guide*.
+ **CloudWatchAgentServerPolicy** – Optional. This AWS managed policy allows you to run the CloudWatch agent on managed nodes. This policy makes it possible to read information on a node and write it to Amazon CloudWatch. Your instance profile needs this policy only if you use services such as Amazon EventBridge or CloudWatch Logs.
**Note**
Using CloudWatch and EventBridge features is optional, but we recommend setting them up at the beginning of your Systems Manager configuration process if you have decided to use them. For more information, see the *[Amazon EventBridge User Guide](https://docs.aws.amazon.com/eventbridge/latest/userguide/)* and the *[Amazon CloudWatch Logs User Guide](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/)*.
1. Edit the IAM role attached to the node and add the following policy. This policy gives the node permissions to call the `kms:Decrypt` and the `ssm:CreateDocument` API.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"kms:Decrypt",
"ssm:CreateDocument"
],
"Resource": [
"arn:aws:kms:us-east-1:111122223333:key/kms-key-id"
]
}
]
}
```
------
1. Copy and paste the following json text into a text editor and save the file as `JoinInstanceToDomain.json` in the following location: `c:\temp\JoinInstanceToDomain.json`.
```
{
"schemaVersion": "2.2",
"description": "Run a PowerShell script to securely join a Windows Server instance to a domain",
"mainSteps": [
{
"action": "aws:runPowerShellScript",
"name": "runPowerShellWithSecureString",
"precondition": {
"StringEquals": [
"platformType",
"Windows"
]
},
"inputs": {
"runCommand": [
"$domain = (Get-SSMParameterValue -Name domainName).Parameters[0].Value",
"if ((gwmi Win32_ComputerSystem).domain -eq $domain){write-host \"Computer is part of $domain, exiting\"; exit 0}",
"$username = (Get-SSMParameterValue -Name domainJoinUserName).Parameters[0].Value",
"$password = (Get-SSMParameterValue -Name domainJoinPassword -WithDecryption $True).Parameters[0].Value | ConvertTo-SecureString -asPlainText -Force",
"$credential = New-Object System.Management.Automation.PSCredential($username,$password)",
"Add-Computer -DomainName $domain -Credential $credential -ErrorAction SilentlyContinue -ErrorVariable domainjoinerror",
"if($?){Write-Host \"Instance joined to domain successfully. Restarting\"; exit 3010}else{Write-Host \"Instance failed to join domain with error:\" $domainjoinerror; exit 1 }"
]
}
}
]
}
```
1. Run the following command in Tools for Windows PowerShell to create a new SSM document.
```
$json = Get-Content C:\temp\JoinInstanceToDomain | Out-String
New-SSMDocument -Name JoinInstanceToDomain -Content $json -DocumentType Command
```
1. Run the following command in Tools for Windows PowerShell to join the node to the domain.
```
Send-SSMCommand -InstanceId instance-id -DocumentName JoinInstanceToDomain
```
If the command succeeds, the system returns information similar to the following.
```
WARNING: The changes will take effect after you restart the computer EC2ABCD-EXAMPLE.
Domain join succeeded, restarting
Computer is part of example.local, exiting
```
If the command fails, the system returns information similar to the following.
```
Failed to join domain with error:
Computer 'EC2ABCD-EXAMPLE' failed to join domain 'example.local'
from its current workgroup 'WORKGROUP' with following error message:
The specified domain either does not exist or could not be contacted.
```
# Auditing and logging Parameter Store activity
AWS CloudTrail captures API calls made in the AWS Systems Manager console, the AWS Command Line Interface (AWS CLI), and the Systems Manager SDK. You can view the information in the CloudTrail console or in an Amazon Simple Storage Service (Amazon S3) bucket. All CloudTrail logs for your account use one bucket. For more information about viewing and using CloudTrail logs of Systems Manager activity, see [Logging AWS Systems Manager API calls with AWS CloudTrail](monitoring-cloudtrail-logs.md). For more information about auditing and logging options for Systems Manager, see [Logging and monitoring in AWS Systems Manager](monitoring.md).
# Troubleshooting Parameter Store
Use the following information to help you troubleshoot problems with Parameter Store, a tool in AWS Systems Manager.
## Troubleshooting `aws:ec2:image` parameter creation
Use the following information to help troubleshoot problems with creating `aws:ec2:image` data type parameters.
### No permission to create an instance
**Problem**: You try to create an instance using an `aws:ec2:image` parameter but receive an error message such as "You are not authorized to perform this operation."
+ **Solution**: You do not have all the permissions needed to create an EC2 instance using a parameter value, such as permissions for `ec2:RunInstances`, `ec2:DescribeImages`, and `ssm:GetParameter`, among others. Contact a user with administrator permissions in your organzation to request the necessary permissions.
### EventBridge reports the failure message "Unable to Describe Resource"
**Problem**: You ran a command to create an `aws:ec2:image` parameter, but parameter creation failed. You receive a notification from Amazon EventBridge that reports the exception "Unable to Describe Resource".
**Solution**: This message can indicate the following:
+ You do not have all the permissions needed for the `ec2:DescribeImages` API operation, or you lack permission to access the specific image referenced in the parameter. Contact a user with administrator permissions in your organization to request the necessary permissions.
+ The Amazon Machine Image (AMI) ID you entered as a parameter value isn't valid. Make sure you're entering the ID of an AMI that is available in the current AWS Region and account you're working in.
### New `aws:ec2:image` parameter isn't available
**Problem**: You just ran a command to create an `aws:ec2:image` parameter and a version number was reported, but the parameter isn't available.
+ **Solution**: When you run the command to create a parameter that uses the `aws:ec2:image` data type, a version number is generated for the parameter right away, but the parameter format must be validated before the parameter is available. This process can take up to a few minutes. To monitor the parameter creation and validation process, you can do the following:
+ Use EventBridge to send you notifications about your `create` and `update` parameter operations. These notifications report whether a parameter operation was successful or not. For information about subscribing to Parameter Store events in EventBridge, see [Setting up notifications or triggering actions based on Parameter Store events](sysman-paramstore-cwe.md).
+ In the Parameter Store section of the Systems Manager console, refresh the list of parameters periodically to search for the new or updated parameter details.
+ Use the **GetParameter** command to check for the new or updated parameter. For example, using the AWS Command Line Interface (AWS CLI):
```
aws ssm get-parameter name MyParameter
```
For a new parameter, a `ParameterNotFound` message is returned until the parameter is validated. For an existing parameter that you're updating, information about the new version isn't included until the parameter is validated.
If you attempt to create or update the parameter again before the validation process is complete, the system reports that validation is still in process. If the parameter isn't created or updated, you can try again after 5 minutes have passed from the original attempt.