Skip to content

Commit dcf6620

Browse files
dreamorosidreamorosi
authored
feat(parameters): ability to set maxAge and decrypt via environment variables (#1384)
* feat: add env variables config for SSM/Parameters * tests: added unit tests * docs: updated docs with new env vars
1 parent 40a1a24 commit dcf6620

20 files changed

+308
-86
lines changed

‎docs/index.md

Lines changed: 16 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -293,20 +293,22 @@ Core utilities such as Tracing, Logging, and Metrics will be available across al
293293
???+ info
294294
Explicit parameters take precedence over environment variables
295295

296-
| Environment variable | Description | Utility | Default |
297-
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------- | ------------------- |
298-
| **POWERTOOLS_SERVICE_NAME** | Sets service name used for tracing namespace, metrics dimension and structured logging | All | `service_undefined` |
299-
| **POWERTOOLS_METRICS_NAMESPACE** | Sets namespace used for metrics | [Metrics](./core/metrics) | `default_namespace` |
300-
| **POWERTOOLS_TRACE_ENABLED** | Explicitly disables tracing | [Tracer](./core/tracer) | `true` |
301-
| **POWERTOOLS_TRACER_CAPTURE_RESPONSE** | Captures Lambda or method return as metadata. | [Tracer](./core/tracer) | `true` |
302-
| **POWERTOOLS_TRACER_CAPTURE_ERROR** | Captures Lambda or method exception as metadata. | [Tracer](./core/tracer) | `true` |
303-
| **POWERTOOLS_TRACER_CAPTURE_HTTPS_REQUESTS** | Captures HTTP(s) requests as segments. | [Tracer](./core/tracer) | `true` |
304-
| **POWERTOOLS_LOGGER_LOG_EVENT** | Logs incoming event | [Logger](./core/logger) | `false` |
305-
| **POWERTOOLS_LOGGER_SAMPLE_RATE** | Debug log sampling | [Logger](./core/logger) | `0` |
306-
| **POWERTOOLS_DEV** | Increase JSON indentation to ease debugging when running functions locally or in a non-production environment | [Logger](./core/logger) | `false` |
307-
| **LOG_LEVEL** | Sets logging level | [Logger](./core/logger) | `INFO` |
308-
309-
Each Utility page provides information on example values and allowed values
296+
| Environment variable | Description | Utility | Default |
297+
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------ | ------------------- |
298+
| **POWERTOOLS_SERVICE_NAME** | Sets service name used for tracing namespace, metrics dimension and structured logging | All | `service_undefined` |
299+
| **POWERTOOLS_METRICS_NAMESPACE** | Sets namespace used for metrics | [Metrics](./core/metrics) | `default_namespace` |
300+
| **POWERTOOLS_TRACE_ENABLED** | Explicitly disables tracing | [Tracer](./core/tracer) | `true` |
301+
| **POWERTOOLS_TRACER_CAPTURE_RESPONSE** | Captures Lambda or method return as metadata. | [Tracer](./core/tracer) | `true` |
302+
| **POWERTOOLS_TRACER_CAPTURE_ERROR** | Captures Lambda or method exception as metadata. | [Tracer](./core/tracer) | `true` |
303+
| **POWERTOOLS_TRACER_CAPTURE_HTTPS_REQUESTS** | Captures HTTP(s) requests as segments. | [Tracer](./core/tracer) | `true` |
304+
| **POWERTOOLS_LOGGER_LOG_EVENT** | Logs incoming event | [Logger](./core/logger) | `false` |
305+
| **POWERTOOLS_LOGGER_SAMPLE_RATE** | Debug log sampling | [Logger](./core/logger) | `0` |
306+
| **POWERTOOLS_DEV** | Increase JSON indentation to ease debugging when running functions locally or in a non-production environment | [Logger](./core/logger) | `false` |
307+
| **LOG_LEVEL** | Sets logging level | [Logger](./core/logger) | `INFO` |
308+
| **POWERTOOLS_PARAMETERS_MAX_AGE** | Adjust how long values are kept in cache (in seconds) | [Parameters](./utilities/parameters) | `5` |
309+
| **POWERTOOLS_PARAMETERS_SSM_DECRYPT** | Sets whether to decrypt or not values retrieved from AWS Systems Manager Parameters Store | [Parameters](./utilities/parameters) | `false` |
310+
311+
Each Utility page provides information on example values and allowed values.
310312

311313
## Tenets
312314

‎docs/snippets/parameters/adjustingCacheTTL.ts

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,12 @@ import { SSMProvider } from '@aws-lambda-powertools/parameters/ssm';
33
const parametersProvider = new SSMProvider();
44

55
export const handler = async (): Promise<void> => {
6-
// Retrieve a single parameter
7-
const parameter = await parametersProvider.get('/my/parameter', { maxAge: 60 }); // 1 minute
6+
// Retrieve a single parameter and cache it for 1 minute
7+
const parameter = await parametersProvider.get('/my/parameter', { maxAge: 60 }); // (1)
88
console.log(parameter);
99

10-
// Retrieve multiple parameters from a path prefix
11-
const parameters = await parametersProvider.getMultiple('/my/path/prefix', { maxAge: 120 }); // 2 minutes
10+
// Retrieve multiple parameters from a path prefix and cache them for 2 minutes
11+
const parameters = await parametersProvider.getMultiple('/my/path/prefix', { maxAge: 120 });
1212
for (const [ key, value ] of Object.entries(parameters || {})) {
1313
console.log(`${key}: ${value}`);
1414
}

‎docs/snippets/parameters/ssmProviderDecryptAndRecursive.ts

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ import { SSMProvider } from '@aws-lambda-powertools/parameters/ssm';
33
const parametersProvider = new SSMProvider();
44

55
export const handler = async (): Promise<void> => {
6-
const decryptedValue = await parametersProvider.get('/my/encrypted/parameter', { decrypt: true });
6+
const decryptedValue = await parametersProvider.get('/my/encrypted/parameter', { decrypt: true }); // (1)
77
console.log(decryptedValue);
88

99
const noRecursiveValues = await parametersProvider.getMultiple('/my/path/prefix', { recursive: false });

‎docs/utilities/parameters.md

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -127,17 +127,22 @@ The following will retrieve the latest version and store it in the cache.
127127

128128
### Adjusting cache TTL
129129

130-
???+ tip
131-
`maxAge` parameter is also available in high level functions like `getParameter`, `getSecret`, etc.
132-
133130
By default, the provider will cache parameters retrieved in-memory for 5 seconds.
134131

135132
You can adjust how long values should be kept in cache by using the param `maxAge`, when using `get()` or `getMultiple()` methods across all providers.
136133

134+
???+ tip
135+
If you want to set the same TTL for all parameters, you can set the `POWERTOOLS_PARAMETERS_MAX_AGE` environment variable. **This will override the default TTL of 5 seconds but can be overridden by the `maxAge` parameter**.
136+
137137
```typescript hl_lines="7 11" title="Caching parameters values in memory for longer than 5 seconds"
138138
--8<-- "docs/snippets/parameters/adjustingCacheTTL.ts"
139139
```
140140

141+
1. Options passed to `get()`, `getMultiple()`, and `getParametersByName()` will override the values set in `POWERTOOLS_PARAMETERS_MAX_AGE` environment variable.
142+
143+
???+ info
144+
The `maxAge` parameter is also available in high level functions like `getParameter`, `getSecret`, etc.
145+
141146
### Always fetching the latest
142147

143148
If you'd like to always ensure you fetch the latest parameter from the store regardless if already available in cache, use the `forceFetch` parameter.
@@ -166,10 +171,15 @@ The AWS Systems Manager Parameter Store provider supports two additional argumen
166171
| **decrypt** | `false` | Will automatically decrypt the parameter (see required [IAM Permissions](#iam-permissions)). |
167172
| **recursive** | `true` | For `getMultiple()` only, will fetch all parameter values recursively based on a path prefix. |
168173

174+
???+ tip
175+
If you want to always decrypt parameters, you can set the `POWERTOOLS_PARAMETERS_SSM_DECRYPT=true` environment variable. **This will override the default value of `false` but can be overridden by the `decrypt` parameter**.
176+
169177
```typescript hl_lines="6 9" title="Example with get() and getMultiple()"
170178
--8<-- "docs/snippets/parameters/ssmProviderDecryptAndRecursive.ts"
171179
```
172180

181+
1. Options passed to `get()`, `getMultiple()`, and `getParametersByName()` will override the values set in `POWERTOOLS_PARAMETERS_SSM_DECRYPT` environment variable.
182+
173183
#### SecretsProvider
174184

175185
```typescript hl_lines="4-5" title="Example with SecretsProvider for further extensibility"

‎package-lock.json

Lines changed: 2 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎packages/commons/src/config/ConfigService.ts

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,25 @@ abstract class ConfigService {
2424
*/
2525
public abstract getServiceName(): string;
2626

27+
/**
28+
* It returns the value of the _X_AMZN_TRACE_ID environment variable.
29+
*
30+
* The AWS X-Ray Trace data available in the environment variable has this format:
31+
* `Root=1-5759e988-bd862e3fe1be46a994272793;Parent=557abcec3ee5a047;Sampled=1`,
32+
*
33+
* The actual Trace ID is: `1-5759e988-bd862e3fe1be46a994272793`.
34+
*
35+
* @returns {string|undefined}
36+
*/
37+
public abstract getXrayTraceId(): string | undefined;
38+
39+
/**
40+
* It returns true if the string value represents a boolean true value.
41+
*
42+
* @param {string} value
43+
* @returns boolean
44+
*/
45+
public abstract isValueTrue(value: string): boolean;
2746
}
2847

2948
export {

‎packages/commons/src/config/EnvironmentVariablesService.ts

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,18 @@ class EnvironmentVariablesService extends ConfigService {
6060
return xRayTraceId.split(';')[0].replace('Root=', '');
6161
}
6262

63+
/**
64+
* It returns true if the string value represents a boolean true value.
65+
*
66+
* @param {string} value
67+
* @returns boolean
68+
*/
69+
public isValueTrue(value: string): boolean {
70+
const truthyValues: string[] = [ '1', 'y', 'yes', 't', 'true', 'on' ];
71+
72+
return truthyValues.includes(value.toLowerCase());
73+
}
74+
6375
}
6476

6577
export {

‎packages/commons/tests/unit/config/EnvironmentVariablesService.test.ts

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -110,4 +110,31 @@ describe('Class: EnvironmentVariablesService', () => {
110110

111111
});
112112

113+
describe('Method: isValueTrue', () => {
114+
115+
const valuesToTest: Array<Array<string | boolean>> = [
116+
[ '1', true ],
117+
[ 'y', true ],
118+
[ 'yes', true ],
119+
[ 't', true ],
120+
[ 'TRUE', true ],
121+
[ 'on', true ],
122+
[ '', false ],
123+
[ 'false', false ],
124+
[ 'fasle', false ],
125+
[ 'somethingsilly', false ],
126+
[ '0', false ]
127+
];
128+
129+
test.each(valuesToTest)('it takes string "%s" and returns %s', (input, output) => {
130+
// Prepare
131+
const service = new EnvironmentVariablesService();
132+
// Act
133+
const value = service.isValueTrue(input as string);
134+
// Assess
135+
expect(value).toBe(output);
136+
});
137+
138+
});
139+
113140
});

‎packages/logger/src/config/EnvironmentVariablesService.ts

Lines changed: 0 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -117,18 +117,6 @@ class EnvironmentVariablesService extends CommonEnvironmentVariablesService impl
117117
return this.isValueTrue(value);
118118
}
119119

120-
/**
121-
* It returns true if the string value represents a boolean true value.
122-
*
123-
* @param {string} value
124-
* @returns boolean
125-
*/
126-
public isValueTrue(value: string): boolean {
127-
const truthyValues: string[] = [ '1', 'y', 'yes', 't', 'true', 'on' ];
128-
129-
return truthyValues.includes(value.toLowerCase());
130-
}
131-
132120
}
133121

134122
export {

‎packages/logger/tests/unit/config/EnvironmentVariablesService.test.ts

Lines changed: 0 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -249,31 +249,4 @@ describe('Class: EnvironmentVariablesService', () => {
249249

250250
});
251251

252-
describe('Method: isValueTrue', () => {
253-
254-
const valuesToTest: Array<Array<string | boolean>> = [
255-
[ '1', true ],
256-
[ 'y', true ],
257-
[ 'yes', true ],
258-
[ 't', true ],
259-
[ 'TRUE', true ],
260-
[ 'on', true ],
261-
[ '', false ],
262-
[ 'false', false ],
263-
[ 'fasle', false ],
264-
[ 'somethingsilly', false ],
265-
[ '0', false ]
266-
];
267-
268-
test.each(valuesToTest)('it takes string "%s" and returns %s', (input, output) => {
269-
// Prepare
270-
const service = new EnvironmentVariablesService();
271-
// Act
272-
const value = service.isValueTrue(input as string);
273-
// Assess
274-
expect(value).toBe(output);
275-
});
276-
277-
});
278-
279252
});

0 commit comments

Comments
 (0)