Package: aws-parameters
aws-parameters ⚙️Streamlined, efficient access to configuration values in AWS SSM Parameter Store and SecretsManager.DescriptionWhen building applications in AWS, it is common to use SSM Parameter Store and SecretsManager to store configuration values. Theaws-parameterslibrary provides a simple, easy interface to access these values in a way that is fast, efficient, and secure. It is quick to setup and will perform lazy loading for all available parameters or secrets, meaning it will only call the API the first time the value is requested.The library abstracts the required boilerplate for retrieving SSM Parameters and SecretsManager secrets and provides a simple, fast way to access their values based on a one-time configuration of service-to-parameter mappings.How it WorksThere are 3 basics steps involved in usingaws-parameters:Create a JSON object with service-to-parameter mappingsPass this JSON object to theAppConfigclassAccess parameters and secrets through theparamsandsecretsattributes of theAppConfiginstanceService-to-Parameter MappingsA service-to-parameter mapping says which service, SSM Parameter Store (ssm) or SecretsManager (secretsmanager), is storing a given parameter.First, you will need to create a Parameter Mappings object looking something like this:// param-mappings.json{"ssm":["/dev/myapp/MyParam1","/dev/myapp/MyParam2"],"secretsmanager":["/dev/myapp/MySecret1","/dev/myapp/MySecret2"]}Be aware thataws-parametersis opinionated about the naming convention for parameters and secrets in that it expects it to describe a path. SeeConsiderationsfor more details.Instantiating theAppConfigclassNext, you can pass this object to theAppConfigclass using several methods to create an instance. SeeConfiguration Methodsfor more details.fromawsparametersimportAppConfig# load the above JSON object from a filewithopen("service-to-parameter-mappings.json","r")asf:param_config=json.load(f)app=AppConfig(mappings_path=param_config)One of the big advantages of the library is that no API calls are made when you instantiate theAppConfigclass. Instead, it will only make API calls when you access a parameter or secret through theAppConfig.paramsorAppConfig.secretsattributes.Accessing Parameters and SecretsFinally you can access parameters and secrets like this:# access a parameterMyParam1=app.params.MyParam1# access a secretMySecret1=app.secrets.MySecret1This will initiate API calls to AWS to retrieve the values of the parameters and secrets. The values will be cached so that subsequent calls will not require additional API calls.AdvantagesFast, simple interface to configuration values that can reduce development overhead when working with SSM Parameter Store and SecretsManagerImmediate access to available parameters and secrets through intellisense,maporlistmethodsMaintain least-privileged permissions to parameters and secrets using path-based access controlLazy loading for all available parameters or secrets, meaning it will only make API calls when a value is requested:When parameter or secret property is accessed, it first checks if the value has been computed before (cached). If it has, it immediately returns that cached value.If the value hasn't been computed before, it fetches the value and then returns it. This means that your Python app is only calling the AWS API when it needs to.ConsiderationsYou must use the path convention for naming parameters, but you can choose any separator you want by setting thepath_separatorparameter when creating an instance ofAppConfig. The default is/.Only the latest parameter versions can be fetched.QuickstartInstall the library using pip.pipinstall-ihttps://test.pypi.org/simple/aws-parametersEnvironment ConfigurationParameter MappingsTheAppConfigclass requires a JSON object with service to parameter mappings in order to know which values it needs to access:// Parameter Mappings JSON Schema{"ssm":["parameter_path_and_identifier",...],"secretsmanager":["secret_path_and_identifier",...]}For example:{"ssm":["/dev/myapp/MyParam1","/dev/myapp/MyParam2"],"secretsmanager":["/dev/myapp/MySecret1","/dev/myapp/MySecret2"]}In this example, the path is/dev/myappand the identifiers or names areMyParam1,MyParam2,MySecret1, andMySecret2.You can store this in a JSON file or as its own SSM Parameter.Configuration MethodsThe current method of providing this JSON object toaws-parametersis from deployed SSM Parameter mapping (third fastest)SeeMethods of Accessfor more details.From SSM ParameterFor this method of configuration you would store the parameter mappings as a JSON string using an SSM Parameter in your AWS account. Here is an example using a CloudFormation template:AWSTemplateFormatVersion:"2010-09-09"Parameters:AppName:Type:StringDescription:Name of the applicationStage:Type:StringDescription:Stage of the applicationResources:ParamMappingsParameter:Type:AWS::SSM::ParameterProperties:Type:StringName:!Sub'/${Stage}/${AppName}/MyParamMappings'Description:"Parametermappingsforaws-parameters"Tier:StandardValue:!Sub|{"ssm": ["/${Stage}/${AppName}/MyParam1","/${Stage}/${AppName}/MyParam2"],"secretsmanager": ["/${Stage}/${AppName}/MySecret1","/${Stage}/${AppName}/MySecret2"]}UsageSeeConfiguration Methodsfor the different ways to setup the environment and access SSM Parameters and SecretsManager Secrets values.fromawsparametersimportAppConfig# (optional) Create a boto3 session outside the classsession=boto3.Session(region_name=AWS_REGION)# Retrieve the Parameter Mappings from SSM Parameter Storemappings_path="/dev/myapp/MyParamMappings"# Create the AppConfig object from the mappings pathapp=AppConfig(mappings_path=mappings_path,boto3_session=session)To see all the available parameters and secrets by namespace, you can access themapattribute:# print all available parametersapp.map# output{"ssm":["/dev/myapp/MyParam1","/dev/myapp/MyParam2"],"secretsmanager":["/dev/myapp/MySecret1","/dev/myapp/MySecret2"]}Local DevelopmentFollow the steps to set up the deployment environment.PrerequisitesPython 3.10AWS credentialsCreating a Python Virtual EnvironmentWhen developing locally, create a Python virtual environment to manage dependencies:python3.10-mvenv.venvsource.venv/bin/activate
pipinstall-Upip
pipinstall.[dev,test]Unit TestsFollow the steps above to create a Python virtual environment. Run tests with the following command.maketestAuthorsPrimary Contact:@chrisammon3000LicenseThis library is licensed under the MIT-0 License. See the LICENSE file.