# 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, Amazon 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/Images/ApprovedAMI`. The value of the parameter is an approved AMI ID for a test environment. After you finish testing the image, you want the parameter to use the approved AMI ID for a production environment. You change the value of `/MyApp/Images/ApprovedAMI`. Systems Manager automatically creates version two with the new AMI ID. 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/Images/ApprovedAMI` parameter with a new approved AMI ID, 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 Amazon 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.amazonaws.cn/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 (\_). + 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 Amazon 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 Amazon Systems Manager console at [https://console.amazonaws.cn/systems-manager/](https://console.amazonaws.cn/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 Amazon Systems Manager console at [https://console.amazonaws.cn/systems-manager/](https://console.amazonaws.cn/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 Amazon Systems Manager console at [https://console.amazonaws.cn/systems-manager/](https://console.amazonaws.cn/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 Amazon Systems Manager console at [https://console.amazonaws.cn/systems-manager/](https://console.amazonaws.cn/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 Amazon CLI This section describes how to perform the following tasks by using the Amazon Command Line Interface (Amazon CLI). + [Creating a new parameter label using the Amazon CLI](#sysman-paramstore-labels-cli-create) + [Viewing labels for a parameter using the Amazon CLI](#sysman-paramstore-labels-cli-view) + [Viewing a list of parameters that are assigned a label using the Amazon CLI](#sysman-paramstore-labels-cli-view-param) + [Moving a parameter label using the Amazon CLI](#sysman-paramstore-labels-cli-move) + [Deleting parameter labels using the Amazon CLI](#systems-manager-parameter-store-labels-cli-delete) ### Creating a new parameter label using the Amazon CLI The following procedure describes how to attach a label to a specific version of an *existing* parameter by using the Amazon CLI. You can't attach a label when you create a parameter. **To create a parameter label** 1. Install and configure the Amazon Command Line Interface (Amazon CLI), if you haven't already. For information, see [Installing or updating the latest version of the Amazon CLI](https://docs.amazonaws.cn/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 Amazon Web Services 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}}" ``` The following example shows the command. ``` aws ssm get-parameters --names "/Production/ApprovedAMI: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}} ``` The following examples show the commands. ``` aws ssm label-parameter-version --name /config/approved-ami --labels production east-region finance ``` ``` aws ssm label-parameter-version --name /config/approved-ami --parameter-version 3 --labels image-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 Amazon CLI You can use the [GetParameterHistory](https://docs.amazonaws.cn/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.amazonaws.cn/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 Amazon CLI You can use the [GetParametersByPath](https://docs.amazonaws.cn/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 Amazon 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 Amazon CLI The following procedure describes how to delete parameter labels by using the Amazon 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"] } ```