Parameters
The parameters utility provides a way to retrieve parameter values from AWS Systems Manager Parameter Store or AWS Secrets Manager. It also provides a base class to create your parameter provider implementation.
Key features
- Retrieve one or multiple parameters from the underlying provider
- Cache parameter values for a given amount of time (defaults to 5 seconds)
- Transform parameter values from JSON or base 64 encoded strings
Install¶
To install this utility, add the following dependency to your project.
1 2 3 4 5 |
|
1 2 3 4 |
|
IAM Permissions
This utility requires additional permissions to work as expected. See the table below:
Provider | Function/Method | IAM Permission |
---|---|---|
SSM Parameter Store | SSMProvider.get(String) SSMProvider.get(String, Class) |
ssm:GetParameter |
SSM Parameter Store | SSMProvider.getMultiple(String) |
ssm:GetParametersByPath |
Secrets Manager | SecretsProvider.get(String) SecretsProvider.get(String, Class) |
secretsmanager:GetSecretValue |
SSM Parameter Store¶
You can retrieve a single parameter using SSMProvider.get() and pass the key of the parameter. For multiple parameters, you can use SSMProvider.getMultiple() and pass the path to retrieve them all.
Alternatively, you can retrieve an instance of a provider and configure its underlying SDK client, in order to get data from other regions or use specific credentials.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
|
Additional arguments¶
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. |
Example:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
|
Secrets Manager¶
For secrets stored in Secrets Manager, use getSecretsProvider
.
Alternatively, you can retrieve an instance of a provider and configure its underlying SDK client, in order to get data from other regions or use specific credentials.
1 2 3 4 5 6 7 8 9 10 11 |
|
1 2 3 4 5 6 7 8 9 10 11 12 |
|
Advanced configuration¶
Caching¶
By default, all parameters and their corresponding values are cached for 5 seconds.
You can customize this default value using defaultMaxAge
. You can also customize this value for each parameter using
withMaxAge
.
1 2 3 4 5 6 7 8 9 10 11 |
|
1 2 3 4 5 6 7 8 9 10 11 |
|
Transform values¶
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-
SSMProvider.getMultiple()
does not support transformation and will return simple Strings.
1 2 3 |
|
1 2 3 |
|
Write your own Transformer¶
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.
1 2 3 4 5 6 7 8 9 10 11 12 13 |
|
1 2 3 |
|
Fluent API¶
To simplify the use of the library, you can chain all method calls before a get.
1 2 3 4 5 6 |
|
Create your own provider¶
You can create your own custom parameter store provider by inheriting the BaseProvider
class and implementing the
String getValue(String key)
method to retrieve data from your underlying store. All transformation and caching logic is handled by the get() methods in the base class.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 |
|
1 2 3 4 5 |
|
Annotation¶
You can make use of the annotation @Param
to inject a parameter value in a variable.
By default, it will use SSMProvider
to retrieve the value from AWS System Manager Parameter Store.
You could specify a different provider as long as it extends BaseProvider
and/or a Transformer
.
1 2 3 4 5 6 |
|
1 2 3 4 5 6 |
|
In this case SecretsProvider
will be used to retrieve a raw value that is then trasformed into the target Object by using JsonTransformer
.
To show the convenience of the annotation compare the following two code snippets.
Install¶
If you want to use the @Param
annotation in your project add configuration to compile-time weave (CTW) the powertools-parameters aspects into your project.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
|