Parameters
The parameters utilities provide a way to retrieve parameter values from
AWS Systems Manager Parameter Store,
AWS Secrets Manager, Amazon DynamoDB,
or AWS AppConfig.
Key features
- Retrieve one or multiple parameters from an underlying provider in a standard way
- Cache parameter values for a given amount of time (defaults to 5 seconds)
- Transform parameter values from JSON or base 64 encoded strings
Install
In order to provide lightweight dependencies, each parameters module is available as its own
package:
- Secrets Manager -
powertools-parameters-secrets
- SSM Parameter Store -
powertools-parameters-ssm
- Amazon DynamoDB -
powertools-parameters-dynamodb
- AWS AppConfig -
powertools-parameters-appconfig
You can easily mix and match parameter providers within the same project for different needs.
Note that you must provide the concrete parameters module you want to use below - see the TODOs!
IAM Permissions
This utility requires additional permissions to work as expected. See the table below:
Provider |
Function/Method |
IAM Permission |
SSM |
SSMProvider.get(String) SSMProvider.get(String, Class) |
ssm:GetParameter |
SSM |
SSMProvider.getMultiple(String) |
ssm:GetParametersByPath |
SSM |
If using withDecryption(true) |
You must add an additional permission kms:Decrypt |
Secrets |
SecretsProvider.get(String) SecretsProvider.get(String, Class) |
secretsmanager:GetSecretValue |
DynamoDB |
DynamoDBProvider.get(String) DynamoDBProvider.getMultiple(string) |
dynamodb:GetItem dynamoDB:Query |
AppConfig |
AppConfigProvider.get(String) AppConfigProvider.getMultiple(string) |
appconfig:StartConfigurationSession , appConfig:GetLatestConfiguration |
Retrieving Parameters
You can retrieve parameters either using annotations or by using the xParamProvider
class for each parameter
provider directly. The latter is useful if you need to configure the underlying SDK client, for example to use
a different region or credentials, the former is simpler to use.
Built-in provider classes
This section describes the built-in provider classes for each parameter store, providing
examples showing how to inject parameters using annotations, and how to use the provider
interface. In cases where a provider supports extra features, these will also be described.
Secrets Manager
SSM Parameter Store
The AWS Systems Manager Parameter Store provider supports two additional arguments for the get()
and getMultiple()
methods:
Option |
Default |
Description |
withDecryption() |
False |
Will automatically decrypt the parameter. |
recursive() |
False |
For getMultiple() only, will fetch all parameter values recursively based on a path prefix. |
DynamoDB
AppConfig
Advanced configuration
Caching
Each provider uses the CacheManager
to cache parameter values. When a value is retrieved using from the provider, a
custom cache duration can be provided using withMaxAge(duration, unit)
.
If this is not specified, the default value set on the CacheManager
itself will be used. This default can be customized
by calling setDefaultExpirationTime(duration, unit)
on the CacheManager
.
Parameter values can be transformed using withTransformation(transformerClass)
.
Base64 and JSON transformations are provided. For more complex transformation, you need to specify how to deserialize.
getMultiple()
does not support transformation and will return simple Strings.
You can write your own transformer, by implementing the Transformer
interface and the applyTransformation()
method.
For example, if you wish to deserialize XML into an object.
Fluent API
To simplify the use of the library, you can chain all method calls before a get.
Create your own Provider
You can create your own custom parameter store provider by implementing a handful of classes: