docs(parameters): snippets split, improved, and lint (#1564)

* chore(parameters): refactoring examples

* chore(parameters): adding cache examples

* chore(parameters): adding builtin examples and fix mypy errors

* chore(parameters): adding all providers with custom config

* chore(parameters): adding custom provider

* chore(parameters): adding custom provider

* chore(parameters): adding custom provider

* chore(parameters): adding DynamoDB provider

* chore(parameters): adding tests - mock

* chore(parameters): adding more tests

* chore(parameters): adding appconfig builtin provider

* chore(parameters): adding final examples

* chore(parameters): adding final examples

* chore(parameters): highlights - small changes

* fix(docs): broken link in boto3_session

* fix(docs): improve constrast ratio

* fix(docs): typing and correctness on null endpoint

* (chore): addressing Ruben's feedbacks

* (chore): import errors

---------

Signed-off-by: Leandro Damascena <[email protected]>
Co-authored-by: heitorlessa <[email protected]>

Author: leandrodamascena

docs/utilities/parameters.md

@@ -0,0 +1,22 @@
+AWSTemplateFormatVersion: '2010-09-09'
+Transform: AWS::Serverless-2016-10-31
+Description: 'DynamoDB Table example'
+Resources:
+  ParameterTable:
+    Type: AWS::DynamoDB::Table
+    Properties:
+      TableName: ParameterTable
+      AttributeDefinitions:
+        -   AttributeName: IdKeyAttr
+            AttributeType: S
+        -   AttributeName: SkKeyAttr
+            AttributeType: S
+      KeySchema:
+        -   AttributeName: IdKeyAttr
+            KeyType: HASH
+        -   AttributeName: SkKeyAttr
+            KeyType: RANGE
+      TimeToLiveSpecification:
+        AttributeName: expiration
+        Enabled: true
+      BillingMode: PAY_PER_REQUEST

examples/parameters/sam/sam_dynamodb_custom_fields.yaml

@@ -0,0 +1,22 @@
+AWSTemplateFormatVersion: '2010-09-09'
+Transform: AWS::Serverless-2016-10-31
+Description: 'DynamoDB Table example'
+Resources:
+  ParameterTable:
+    Type: AWS::DynamoDB::Table
+    Properties:
+      TableName: ParameterTable
+      AttributeDefinitions:
+        -   AttributeName: id
+            AttributeType: S
+        -   AttributeName: sk
+            AttributeType: S
+      KeySchema:
+        -   AttributeName: id
+            KeyType: HASH
+        -   AttributeName: sk
+            KeyType: RANGE
+      TimeToLiveSpecification:
+        AttributeName: expiration
+        Enabled: true
+      BillingMode: PAY_PER_REQUEST

examples/parameters/sam/sam_dynamodb_table_recursive.yaml

@@ -0,0 +1,18 @@
+AWSTemplateFormatVersion: '2010-09-09'
+Transform: AWS::Serverless-2016-10-31
+Description: 'DynamoDB Table example'
+Resources:
+  ParameterTable:
+    Type: AWS::DynamoDB::Table
+    Properties:
+      TableName: ParameterTable
+      AttributeDefinitions:
+        -   AttributeName: id
+            AttributeType: S
+      KeySchema:
+        -   AttributeName: id
+            KeyType: HASH
+      TimeToLiveSpecification:
+        AttributeName: expiration
+        Enabled: true
+      BillingMode: PAY_PER_REQUEST

examples/parameters/sam/sam_dynamodb_table_single.yaml

@@ -0,0 +1,21 @@
+from typing import Any
+
+import requests
+
+from aws_lambda_powertools.utilities import parameters
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+
+def lambda_handler(event: dict, context: LambdaContext):
+    try:
+        # Retrieve a single parameter
+        endpoint_comments: Any = parameters.get_app_config(
+            name="config", environment="dev", application="comments", force_fetch=True
+        )
+
+        # the value of this parameter is https://jsonplaceholder.typicode.com/comments/
+        comments: requests.Response = requests.get(endpoint_comments)
+
+        return {"comments": comments.json()[:10], "statusCode": 200}
+    except parameters.exceptions.GetParameterError as error:
+        return {"comments": None, "message": str(error), "statusCode": 400}

examples/parameters/src/appconfig_force_fetch.py

@@ -0,0 +1,21 @@
+from typing import Any
+
+import requests
+
+from aws_lambda_powertools.utilities import parameters
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+
+def lambda_handler(event: dict, context: LambdaContext):
+    try:
+        # Retrieve a single parameter
+        endpoint_comments: Any = parameters.get_app_config(
+            name="config", environment="dev", application="comments", max_age=20
+        )
+
+        # the value of this parameter is https://jsonplaceholder.typicode.com/comments/
+        comments: requests.Response = requests.get(endpoint_comments)
+
+        return {"comments": comments.json()[:10], "statusCode": 200}
+    except parameters.exceptions.GetParameterError as error:
+        return {"comments": None, "message": str(error), "statusCode": 400}

examples/parameters/src/appconfig_with_cache.py

@@ -0,0 +1,23 @@
+from typing import Any
+
+import requests
+from botocore.config import Config
+
+from aws_lambda_powertools.utilities import parameters
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+config = Config(region_name="sa-east-1")
+appconf_provider = parameters.AppConfigProvider(environment="dev", application="comments", config=config)
+
+
+def lambda_handler(event: dict, context: LambdaContext):
+    try:
+        # Retrieve a single parameter
+        endpoint_comments: Any = appconf_provider.get("config")
+
+        # the value of this parameter is https://jsonplaceholder.typicode.com/comments/
+        comments: requests.Response = requests.get(endpoint_comments)
+
+        return {"comments": comments.json()[:10], "statusCode": 200}
+    except parameters.exceptions.GetParameterError as error:
+        return {"comments": None, "message": str(error), "statusCode": 400}

examples/parameters/src/builtin_provider_appconfig.py

@@ -0,0 +1,22 @@
+from typing import Any
+
+import requests
+
+from aws_lambda_powertools.utilities import parameters
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+dynamodb_provider = parameters.DynamoDBProvider(table_name="ParameterTable", endpoint_url="http://localhost:8000")
+
+
+def lambda_handler(event: dict, context: LambdaContext):
+
+    try:
+        # Usually an endpoint is not sensitive data, so we store it in DynamoDB Table
+        endpoint_comments: Any = dynamodb_provider.get("comments_endpoint")
+
+        comments: requests.Response = requests.get(endpoint_comments)
+
+        return {"comments": comments.json()[:10], "statusCode": 200}
+    # general exception
+    except Exception as error:
+        return {"comments": None, "message": str(error), "statusCode": 400}

examples/parameters/src/builtin_provider_dynamodb_custom_endpoint.py

@@ -0,0 +1,24 @@
+from typing import Any
+
+import requests
+
+from aws_lambda_powertools.utilities import parameters
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+dynamodb_provider = parameters.DynamoDBProvider(
+    table_name="ParameterTable", key_attr="IdKeyAttr", sort_attr="SkKeyAttr", value_attr="ValueAttr"
+)
+
+
+def lambda_handler(event: dict, context: LambdaContext):
+
+    try:
+        # Usually an endpoint is not sensitive data, so we store it in DynamoDB Table
+        endpoint_comments: Any = dynamodb_provider.get("comments_endpoint")
+
+        comments: requests.Response = requests.get(endpoint_comments)
+
+        return {"comments": comments.json()[:10], "statusCode": 200}
+    # general exception
+    except Exception as error:
+        return {"comments": None, "message": str(error), "statusCode": 400}

examples/parameters/src/builtin_provider_dynamodb_custom_fields.py

@@ -0,0 +1,33 @@
+from typing import Any
+
+import requests
+
+from aws_lambda_powertools.utilities import parameters
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+dynamodb_provider = parameters.DynamoDBProvider(table_name="ParameterTable")
+
+
+def lambda_handler(event: dict, context: LambdaContext):
+
+    try:
+        # Retrieve multiple parameters using HASH KEY
+        all_parameters: Any = dynamodb_provider.get_multiple("config")
+        endpoint_comments = "https://jsonplaceholder.typicode.com/noexists/"
+        limit = 2
+
+        for parameter, value in all_parameters.items():
+
+            if parameter == "endpoint_comments":
+                endpoint_comments = value
+
+            if parameter == "limit":
+                limit = int(value)
+
+        # the value of parameter is https://jsonplaceholder.typicode.com/comments/
+        comments: requests.Response = requests.get(endpoint_comments)
+
+        return {"comments": comments.json()[limit]}
+    # general exception
+    except Exception as error:
+        return {"comments": None, "message": str(error), "statusCode": 400}

examples/parameters/src/builtin_provider_dynamodb_recursive_parameter.py

@@ -0,0 +1,22 @@
+from typing import Any
+
+import requests
+
+from aws_lambda_powertools.utilities import parameters
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+dynamodb_provider = parameters.DynamoDBProvider(table_name="ParameterTable")
+
+
+def lambda_handler(event: dict, context: LambdaContext):
+
+    try:
+        # Usually an endpoint is not sensitive data, so we store it in DynamoDB Table
+        endpoint_comments: Any = dynamodb_provider.get("comments_endpoint")
+
+        comments: requests.Response = requests.get(endpoint_comments)
+
+        return {"comments": comments.json()[:10], "statusCode": 200}
+    # general exception
+    except Exception as error:
+        return {"comments": None, "message": str(error), "statusCode": 400}

examples/parameters/src/builtin_provider_dynamodb_single_parameter.py

@@ -0,0 +1,27 @@
+from typing import Any
+
+import requests
+from botocore.config import Config
+
+from aws_lambda_powertools.utilities import parameters
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+config = Config(region_name="sa-east-1", connect_timeout=1, retries={"total_max_attempts": 2, "max_attempts": 5})
+ssm_provider = parameters.SecretsProvider(config=config)
+
+
+def lambda_handler(event: dict, context: LambdaContext):
+
+    try:
+        # Usually an endpoint is not sensitive data, so we store it in SSM Parameters
+        endpoint_comments: Any = parameters.get_parameter("/lambda-powertools/endpoint_comments")
+        # An API-KEY is a sensitive data and should be stored in SecretsManager
+        api_key: Any = ssm_provider.get("/lambda-powertools/api-key")
+
+        headers: dict = {"X-API-Key": api_key}
+
+        comments: requests.Response = requests.get(endpoint_comments, headers=headers)
+
+        return {"comments": comments.json()[:10], "statusCode": 200}
+    except parameters.exceptions.GetParameterError as error:
+        return {"comments": None, "message": str(error), "statusCode": 400}

examples/parameters/src/builtin_provider_secret.py

@@ -0,0 +1,44 @@
+from typing import Any
+
+import boto3
+import requests
+
+from aws_lambda_powertools.utilities import parameters
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+# assuming role from another account to get parameter there
+# see: https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html
+sts_client = boto3.client("sts")
+assumed_role_object = sts_client.assume_role(
+    RoleArn="arn:aws:iam::account-of-role-to-assume:role/name-of-role", RoleSessionName="RoleAssume1"
+)
+credentials = assumed_role_object["Credentials"]
+
+# using temporary credentials in your SSMProvider provider
+# see: https://boto3.amazonaws.com/v1/documentation/api/latest/reference/core/session.html#module-boto3.session
+boto3_session = boto3.session.Session(
+    region_name="us-east-1",
+    aws_access_key_id=credentials["AccessKeyId"],
+    aws_secret_access_key=credentials["SecretAccessKey"],
+    aws_session_token=credentials["SessionToken"],
+)
+ssm_provider = parameters.SSMProvider(boto3_session=boto3_session)
+
+
+def lambda_handler(event: dict, context: LambdaContext):
+    try:
+        # Retrieve multiple parameters from a path prefix
+        all_parameters: Any = ssm_provider.get_multiple("/lambda-powertools/")
+        endpoint_comments = "https://jsonplaceholder.typicode.com/noexists/"
+
+        for parameter, value in all_parameters.items():
+
+            if parameter == "endpoint_comments":
+                endpoint_comments = value
+
+        # the value of parameter is https://jsonplaceholder.typicode.com/comments/
+        comments: requests.Response = requests.get(endpoint_comments)
+
+        return {"comments": comments.json()[:10]}
+    except parameters.exceptions.GetParameterError as error:
+        return {"comments": None, "message": str(error), "statusCode": 400}

examples/parameters/src/builtin_provider_ssm_recursive_parameter.py

@@ -0,0 +1,25 @@
+from typing import Any
+
+import requests
+from botocore.config import Config
+
+from aws_lambda_powertools.utilities import parameters
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+# changing region_name, connect_timeout and retrie configurations
+# see: https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html
+config = Config(region_name="sa-east-1", connect_timeout=1, retries={"total_max_attempts": 2, "max_attempts": 5})
+ssm_provider = parameters.SSMProvider(config=config)
+
+
+def lambda_handler(event: dict, context: LambdaContext):
+    try:
+        # Retrieve a single parameter
+        endpoint_comments: Any = ssm_provider.get("/lambda-powertools/endpoint_comments")
+
+        # the value of this parameter is https://jsonplaceholder.typicode.com/comments/
+        comments: requests.Response = requests.get(endpoint_comments)
+
+        return {"comments": comments.json()[:10], "statusCode": 200}
+    except parameters.exceptions.GetParameterError as error:
+        return {"comments": None, "message": str(error), "statusCode": 400}

examples/parameters/src/builtin_provider_ssm_single_parameter.py

@@ -0,0 +1,28 @@
+from typing import Any
+from uuid import uuid4
+
+import boto3
+
+from aws_lambda_powertools.utilities import parameters
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+ec2 = boto3.resource("ec2")
+ssm_provider = parameters.SSMProvider()
+
+
+def lambda_handler(event: dict, context: LambdaContext):
+    try:
+        # Retrieve the key pair from secure string parameter
+        ec2_pem: Any = ssm_provider.get("/lambda-powertools/ec2_pem", decrypt=True)
+
+        name_key_pair = f"kp_{uuid4()}"
+
+        ec2.import_key_pair(KeyName=name_key_pair, PublicKeyMaterial=ec2_pem)
+
+        ec2.create_instances(
+            ImageId="ami-026b57f3c383c2eec", InstanceType="t2.micro", MinCount=1, MaxCount=1, KeyName=name_key_pair
+        )
+
+        return {"message": "EC2 created", "success": True}
+    except parameters.exceptions.GetParameterError as error:
+        return {"message": f"Error creating EC2 => {str(error)}", "success": False}