AWS Cloud Operations Blog
Use parameter labels for easy configuration update across environments
By Sahithya Jagadish, Software Development Engineer at Amazon Web Services
Parameter Store, part of AWS Systems Manager, provides a centralized, encrypted store to manage your configuration data, whether it’s plaintext data (public URLs) or secrets (such as passwords or API keys). Parameter Store is available through the AWS CLI, APIs, and SDKs. You can easily reference parameters across AWS services such as AWS Lambda and Amazon Elastic Container Service (Amazon ECS).
You can use Parameter Store labels to manage multiple parameter versions by adding human-readable names to a set of configuration parameters. Labeling helps protect against unintended overwrites of a parameter value due to user parameter updates. If any issue arises during an intended update of configuration, labels can be used to roll back to the previous version easily. In this blog post, I show you how parameter labels can be used as an alias to parameter versions. You can group parameter versions across hierarchies using labels, and you can deploy new updates to parameters across environments using hierarchies and labels.
Different ways to group parameters – hierarchies, tags, and labels
Parameter Hierarchies: Parameter Store allows you to organize parameters in a hierarchical manner to represent common groups, such as environments (e.g., dev/test/prod), or applications (e.g., /Config/Prod/Fleet/MinHealthyHosts, /Config/Beta/Fleet/MinHealthyHosts). Each parameter will still have its own line of history versions, and you can control access to individual parameters. For more details on parameter hierarchies, read Organize Parameters by Hierarchy, Tags or Amazon CloudWatch Events with AWS Systems Manager Parameter Store.
Tags: You can also tag parameters just like you tag any other AWS resource, and set up tag-based permissions on parameters.
Labels: Labels let you maintain a single parameter for different values of a configuration or deployment. For example, if you have different API keys for your beta and production environment, you can simply create a single API key parameter, and have different parameter versions for beta and production with labels attached to them. This creates a single history trail of parameter versions, and you can also control access for who can attach labels across versions on which parameters.
Parameter labels
Whenever a parameter is updated a new version is created and is assigned a unique version number. You can attach a human-readable alias to specific parameter versions and retrieve the value of a history version using labels. A unique label can be associated to only one version of a parameter, that is, no two parameter versions can have the same label. After a label is attached, it can’t be deleted but can only be moved from one version of the parameter to another. Each parameter version can have up to 10 labels.
In the following example there are 5 versions of parameter P1. You can attach labels to the previous versions of the parameter and retrieve the parameter value using the syntax
Using parameter labels for easy configuration updates
Consider a scenario where you have a set of application configuration parameters, such as database connection strings, and API keys across beta and production environments. You have frequent updates to these configuration parameters and want to retrieve specific versions of parameters in your application without having to delete or update the parameter. For your production environment you require version 4 of the database connection string, and version 6 of the API key. For your beta environment you require version 1 of the database connection string, and version 3 of the API key. Using labels, you can create a snapshot over a set of parameter versions across hierarchies.
Step 1: Create the parameters
Create the configuration parameters using the AWS CLI or AWS Management Console. For example, the CLI command to create the API key parameter is:
Use an overwrite flag to update the parameter
Assume you have updated your configuration parameters multiple times and you have 5 versions of database connection string, and 6 versions of API key in your production environment. You have 2 versions of database connection string, and 3 versions of API key in your beta environment.
Step 2: Attach parameter labels
Attach “Current” label to the appropriate parameter versions. The API key parameter requires the latest version, so you don’t need to provide a parameter version.
You can attach a “Current” label to the appropriate parameter version using the console as well. In the AWS Systems Manager console, go to the Parameter Store, and in the parameter history view, choose the version and attach labels.
Similarly attach the “Current” label to the appropriate parameter versions of beta environment configuration parameters.
Step 3: Retrieve your application configuration parameters using the Current label
Use the GetParametersByPath command to retrieve all the parameters that are in the “/Config/” path and have the label “Current” attached. If you don’t provide a label filter in this command, then the API will return the latest value of the parameter.
You can also use GetParameters by specifying the parameter name along with the label.
Step 4: Update the parameter
Now that your application is using the Get API actions to retrieve parameters by using the “Current” label as described in Step 3, any update to your parameters will not immediately take effect. Hence any accidental overwrite won’t affect your application.
Step 5: Move “Current” label to new updated value
After the value is determined to be ready to be picked by the application, the administrator can then move the label “Current” to another version. Attach a label “Fallback” to the previous valid value.
If your application polls Parameter Store for configuration values, then it picks up the updated value after the “Current” label is moved. You don’t need to make code changes to refer to a specific version of the parameter.
Pseudo code in an application
Step 6: View all labels associated with each parameter version
In the console, you can go to the parameter history view to retrieve all the versions of a parameter and the attached labels.
You can also retrieve all the versions of a parameter and the attached labels using the CLI:
Access control for attaching a label
Label promotion controls what parameter versions are being used in your application, so you can ensure access control on label promotion by denying access to the LabelParameterVersion API action. For example, the following IAM policy restricts access to LabelParameterVersion for all production configuration parameters only and allows access to beta.
Setting up notifications and events for label updates
You can use Amazon CloudWatch and Amazon Simple Notification Service (Amazon SNS) to notify you if a label is attached or moved from one version to another. In this example we demonstrate how we can set up email notifications for label and parameter updates.
The event pattern can be modified to represent which parameter updates should trigger an event. In the following example any parameter update and label update to the production database connection string and the API key will trigger an event and send you a notification.
Conclusion
This blog post demonstrates the Parameter Store labeling feature. This feature was built on top of parameter versioning and provides a simpler way to manage parameter versions. Labels are user-defined aliases to parameter versions and can be used to group parameter versions across hierarchies. Labels provide an additional layer of protection during parameter updates, allowing you to quickly fall back to the previous version. You can restrict control on promoting labels by using IAM policies. In addition, you can use CloudWatch to be notified when a label is created or moved from one version to another.
About the Author
Sahithya Jagadish is a Software Development Engineer in the AWS Systems Manager team. She has worked on projects relating to Systems Manager console and AWS Parameter Store. Outside work, she enjoys cooking and is a travel enthusiast.