Parameters
The parameters utility provides high-level functions to retrieve one or multiple parameter values from AWS Systems Manager Parameter Store, AWS Secrets Manager, AWS AppConfig, Amazon DynamoDB, or bring your own.
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
- Bring Your Own Parameter Store Provider
Getting started¶
By default, we fetch parameters from System Manager Parameter Store, secrets from Secrets Manager, and application configuration from AppConfig.
IAM Permissions¶
This utility requires additional permissions to work as expected.
Different parameter providers require different permissions
Provider | Function/Method | IAM Permission |
---|---|---|
SSM Parameter Store | get_parameter , SSMProvider.get |
ssm:GetParameter |
SSM Parameter Store | get_parameters , SSMProvider.get_multiple |
ssm:GetParametersByPath |
Secrets Manager | get_secret , SecretsManager.get |
secretsmanager:GetSecretValue |
DynamoDB | DynamoDBProvider.get |
dynamodb:GetItem |
DynamoDB | DynamoDBProvider.get_multiple |
dynamodb:Query |
App Config | AppConfigProvider.get_app_config , get_app_config |
appconfig:GetConfiguration |
Fetching parameters¶
You can retrieve a single parameter using get_parameter
high-level function.
For multiple parameters, you can use get_parameters
and pass a path to retrieve them recursively.
1 2 3 4 5 6 7 8 9 10 11 |
|
Fetching secrets¶
You can fetch secrets stored in Secrets Manager using get_secrets
.
1 2 3 4 5 |
|
Fetching app configurations¶
New in 1.10.0
You can fetch application configurations in AWS AppConfig using get_app_config
.
The following will retrieve the latest version and store it in the cache.
1 2 3 4 5 |
|
Advanced¶
Adjusting cache TTL¶
By default, we cache parameters retrieved in-memory for 5 seconds.
You can adjust how long we should keep values in cache by using the param max_age
, when using get()
or get_multiple()
methods across all providers.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
|
Always fetching the latest¶
If you'd like to always ensure you fetch the latest parameter from the store regardless if already available in cache, use force_fetch
param.
1 2 3 4 5 |
|
Built-in provider class¶
For greater flexibility such as configuring the underlying SDK client used by built-in providers, you can use their respective Provider Classes directly.
This can be used to retrieve values from other regions, change the retry behavior, etc.
SSMProvider¶
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
|
The AWS Systems Manager Parameter Store provider supports two additional arguments for the get()
and get_multiple()
methods:
Parameter | Default | Description |
---|---|---|
decrypt | False |
Will automatically decrypt the parameter. |
recursive | True |
For get_multiple() only, will fetch all parameter values recursively based on a path prefix. |
Example
1 2 3 4 5 6 7 8 |
|
SecretsProvider¶
1 2 3 4 5 6 7 8 9 |
|
DynamoDBProvider¶
The DynamoDB Provider does not have any high-level functions, as it needs to know the name of the DynamoDB table containing the parameters.
Local testing with DynamoDB Local
You can initialize the DynamoDB provider pointing to DynamoDB Local using endpoint_url
parameter:
1 2 3 |
|
DynamoDB table structure for single parameters
For single parameters, you must use id
as the partition key for that table.
id | value |
---|---|
my-parameter | my-value |
Example
With this table, the return value of dynamodb_provider.get("my-param")
call will be my-value
.
1 2 3 4 5 6 7 |
|
DynamoDB table structure for multiple values parameters
If you want to be able to retrieve multiple parameters at once sharing the same id
, your table needs to contain a sort key name sk
.
For example, if you want to retrieve multiple parameters having my-hash-key
as ID:
id | sk | value |
---|---|---|
my-hash-key | param-a | my-value-a |
my-hash-key | param-b | my-value-b |
my-hash-key | param-c | my-value-c |
With this table, the return of dynamodb_provider.get_multiple("my-hash-key")
call will be a dictionary like:
1 2 3 4 5 |
|
Example
1 2 3 4 5 6 7 8 9 10 |
|
Additional arguments
The DynamoDB provider supports four additional arguments at initialization. These can be used if you require a custom table structure:
Parameter | Mandatory | Default | Description |
---|---|---|---|
table_name | Yes | (N/A) | Name of the DynamoDB table containing the parameter values. |
key_attr | No | id |
Hash key for the DynamoDB table. |
sort_attr | No | sk |
Range key for the DynamoDB table. You don't need to set this if you don't use the get_multiple() method. |
value_attr | No | value |
Name of the attribute containing the parameter value. |
Example
1 2 3 4 5 6 7 8 9 10 11 |
|
AppConfigProvider¶
1 2 3 4 5 6 7 8 9 |
|
Create your own provider¶
You can create your own custom parameter store provider by inheriting the BaseProvider
class, and implementing both _get()
and _get_multiple()
methods to retrieve a single, or multiple parameters from your custom store.
All transformation and caching logic is handled by the get()
and get_multiple()
methods from the base provider class.
Here is an example implementation using S3 as a custom parameter store:
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 |
|
Deserializing values with transform parameter¶
For parameters stored in JSON or Base64 format, you can use the transform
argument for deserialization.
The transform
argument is available across all providers, including the high level functions
1 2 3 4 |
|
1 2 3 4 5 6 7 8 9 10 |
|
Partial transform failures with get_multiple()
¶
If you use transform
with get_multiple()
, you can have a single malformed parameter value. To prevent failing the entire request, the method will return a None
value for the parameters that failed to transform.
You can override this by setting the raise_on_transform_error
argument to True
. If you do so, a single transform error will raise a TransformParameterError
exception.
For example, if you have three parameters, /param/a, /param/b and /param/c, but /param/c is malformed:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
|
Passing additional SDK arguments¶
You can use arbitrary keyword arguments to pass it directly to the underlying SDK method.
1 2 3 4 5 6 7 |
|
Here is the mapping between this utility's functions and methods and the underlying SDK:
Provider | Function/Method | Client name | Function name |
---|---|---|---|
SSM Parameter Store | get_parameter |
ssm |
get_parameter |
SSM Parameter Store | get_parameters |
ssm |
get_parameters_by_path |
SSM Parameter Store | SSMProvider.get |
ssm |
get_parameter |
SSM Parameter Store | SSMProvider.get_multiple |
ssm |
get_parameters_by_path |
Secrets Manager | get_secret |
secretsmanager |
get_secret_value |
Secrets Manager | SecretsManager.get |
secretsmanager |
get_secret_value |
DynamoDB | DynamoDBProvider.get |
dynamodb |
(Table resource) |
DynamoDB | DynamoDBProvider.get_multiple |
dynamodb |
(Table resource) |
App Config | get_app_config |
appconfig |
get_configuration |