| Name | aws-parameters JSON |
| Version |
0.1.7
JSON |
| download |
| home_page | |
| Summary | Streamlined, efficient access to configuration values in AWS SSM Parameter Store and SecretsManager. |
| upload_time | 2023-08-06 00:45:12 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.8 |
| license | MIT License Copyright (c) 2023 Gregory Lindsey Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
aws
systems manager
configuration
secretsmanager
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# aws-parameters ⚙️
<!-- [](https://github.com/abk7777/aws-json-dataset/actions/workflows/run_tests.yml) [](https://codecov.io/github/abk7777/aws-json-dataset) -->
[](https://www.python.org/downloads/release/python-3100/) [](https://opensource.org/licenses/MIT)
Streamlined, efficient access to configuration values in AWS SSM Parameter Store and SecretsManager.
## Description
When building applications in AWS, it is common to use SSM Parameter Store and SecretsManager to store configuration values. The `aws-parameters` library 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 Works
There are 3 basics steps involved in using `aws-parameters`:
1. Create a JSON object with service-to-parameter mappings
2. Pass this JSON object to the `AppConfig` class
3. Access parameters and secrets through the `params` and `secrets` attributes of the `AppConfig` instance
#### Service-to-Parameter Mappings
A 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:
```json
// param-mappings.json
{
"ssm": [
"/dev/myapp/MyParam1",
"/dev/myapp/MyParam2"
],
"secretsmanager": [
"/dev/myapp/MySecret1",
"/dev/myapp/MySecret2"
]
}
```
Be aware that `aws-parameters` is opinionated about the naming convention for parameters and secrets in that it expects it to describe a path. See [Considerations](#considerations) for more details.
#### Instantiating the `AppConfig` class
Next, you can pass this object to the `AppConfig` class using several methods to create an instance. See [Configuration Methods](#configuration-methods) for more details.
```python
from awsparameters import AppConfig
# load the above JSON object from a file
with open("service-to-parameter-mappings.json", "r") as f:
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 the `AppConfig` class. Instead, it will only make API calls when you access a parameter or secret through the `AppConfig.params` or `AppConfig.secrets` attributes.
#### Accessing Parameters and Secrets
Finally you can access parameters and secrets like this:
```python
# access a parameter
MyParam1 = app.params.MyParam1
# access a secret
MySecret1 = app.secrets.MySecret1
```
This 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.
### Advantages
- Fast, simple interface to configuration values that can reduce development overhead when working with SSM Parameter Store and SecretsManager
- Immediate access to available parameters and secrets through intellisense, `map` or `list` methods
- Maintain least-privileged permissions to parameters and secrets using path-based access control
- Lazy 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.
### Considerations
* You must use the path convention for naming parameters, but you can choose any separator you want by setting the `path_separator` parameter when creating an instance of `AppConfig`. The default is `/`.
* Only the latest parameter versions can be fetched.
## Quickstart
Install the library using pip.
```bash
pip install -i https://test.pypi.org/simple/ aws-parameters
```
## Environment Configuration
### Parameter Mappings
The `AppConfig` class requires a JSON object with service to parameter mappings in order to know which values it needs to access:
```json
// Parameter Mappings JSON Schema
{
"ssm": [
"parameter_path_and_identifier",
...
],
"secretsmanager": [
"secret_path_and_identifier",
...
]
}
```
For example:
```json
{
"ssm": [
"/dev/myapp/MyParam1",
"/dev/myapp/MyParam2"
],
"secretsmanager": [
"/dev/myapp/MySecret1",
"/dev/myapp/MySecret2"
]
}
```
In this example, the path is `/dev/myapp` and the identifiers or names are `MyParam1`, `MyParam2`, `MySecret1`, and `MySecret2`.
You can store this in a JSON file or as its own SSM Parameter.
### Configuration Methods
<!-- TODO
There are 3 methods of creating or providing this JSON object to `aws-parameters`:
1. From a local JSON file (fastest)
2. From a parameter path such as `/dev/myapp/*` (second fastest)
3. From deployed SSM Parameter mapping (third fastest) -->
The current method of providing this JSON object to `aws-parameters` is from deployed SSM Parameter mapping (third fastest)
See [Methods of Access](#methods-of-access) for more details.
<!-- #### JSON File or Object
This is the fastest method but it requires that the JSON file is up to date with the latest parameters and secrets.
### Parameter Path
Choose and utilize a path naming convention in your cloud resource definitions for SSM Parameters or SecretsManager Secrets.
For example you can use the template `/{stage}/{app name}/{parameter or secret name}` when creating SSM Parameters or Secrets. You could then just pass the path `/{stage}/{app name}/*` to `aws-parameters` and it will use AWS SDK methods for Systems Manager and SecretsManager to listor describe and retrieve all available parameters or secrets under that path. -->
#### From SSM Parameter
For 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:
```yaml
AWSTemplateFormatVersion: "2010-09-09"
Parameters:
AppName:
Type: String
Description: Name of the application
Stage:
Type: String
Description: Stage of the application
Resources:
ParamMappingsParameter:
Type: AWS::SSM::Parameter
Properties:
Type: String
Name: !Sub '/${Stage}/${AppName}/MyParamMappings'
Description: "Parameter mappings for aws-parameters"
Tier: Standard
Value: !Sub |
{
"ssm": [
"/${Stage}/${AppName}/MyParam1",
"/${Stage}/${AppName}/MyParam2"
],
"secretsmanager": [
"/${Stage}/${AppName}/MySecret1",
"/${Stage}/${AppName}/MySecret2"
]
}
```
## Usage
See [Configuration Methods](#configuration-methods) for the different ways to setup the environment and access SSM Parameters and SecretsManager Secrets values.
```python
from awsparameters import AppConfig
# (optional) Create a boto3 session outside the class
session = boto3.Session(region_name=AWS_REGION)
# Retrieve the Parameter Mappings from SSM Parameter Store
mappings_path = "/dev/myapp/MyParamMappings"
# Create the AppConfig object from the mappings path
app = AppConfig(
mappings_path=mappings_path,
boto3_session=session)
```
To see all the available parameters and secrets by namespace, you can access the `map` attribute:
```python
# print all available parameters
app.map
# output
{
"ssm": [
"/dev/myapp/MyParam1",
"/dev/myapp/MyParam2"
],
"secretsmanager": [
"/dev/myapp/MySecret1",
"/dev/myapp/MySecret2"
]
}
```
## Local Development
Follow the steps to set up the deployment environment.
### Prerequisites
* Python 3.10
* AWS credentials
### Creating a Python Virtual Environment
When developing locally, create a Python virtual environment to manage dependencies:
```bash
python3.10 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install .[dev,test]
```
## Unit Tests
Follow the steps above to create a Python virtual environment. Run tests with the following command.
```bash
make test
```
## Authors
**Primary Contact:** [@chrisammon3000](https://github.com/chrisammon3000)
## License
This library is licensed under the MIT-0 License. See the LICENSE file.
Raw data
{
"_id": null,
"home_page": "",
"name": "aws-parameters",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "aws,systems manager,configuration,secretsmanager",
"author": "",
"author_email": "\"@chrisammon3000\" <gclindsey@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/64/e3/bcf1a3b806945c6214872eb5225c54a29110db4dcaff92bef9cc367bb004/aws-parameters-0.1.7.tar.gz",
"platform": null,
"description": "# aws-parameters \u2699\ufe0f\n<!-- [](https://github.com/abk7777/aws-json-dataset/actions/workflows/run_tests.yml) [](https://codecov.io/github/abk7777/aws-json-dataset) -->\n[](https://www.python.org/downloads/release/python-3100/) [](https://opensource.org/licenses/MIT)\n\nStreamlined, efficient access to configuration values in AWS SSM Parameter Store and SecretsManager.\n\n## Description\nWhen building applications in AWS, it is common to use SSM Parameter Store and SecretsManager to store configuration values. The `aws-parameters` library 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.\n\nThe 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.\n\n### How it Works\nThere are 3 basics steps involved in using `aws-parameters`:\n1. Create a JSON object with service-to-parameter mappings\n2. Pass this JSON object to the `AppConfig` class\n3. Access parameters and secrets through the `params` and `secrets` attributes of the `AppConfig` instance\n\n#### Service-to-Parameter Mappings\nA service-to-parameter mapping says which service, SSM Parameter Store (`ssm`) or SecretsManager (`secretsmanager`), is storing a given parameter.\n\nFirst, you will need to create a Parameter Mappings object looking something like this:\n```json\n// param-mappings.json\n{\n \"ssm\": [\n \"/dev/myapp/MyParam1\",\n \"/dev/myapp/MyParam2\"\n ],\n \"secretsmanager\": [\n \"/dev/myapp/MySecret1\",\n \"/dev/myapp/MySecret2\"\n ]\n}\n```\nBe aware that `aws-parameters` is opinionated about the naming convention for parameters and secrets in that it expects it to describe a path. See [Considerations](#considerations) for more details.\n\n#### Instantiating the `AppConfig` class\nNext, you can pass this object to the `AppConfig` class using several methods to create an instance. See [Configuration Methods](#configuration-methods) for more details.\n```python\nfrom awsparameters import AppConfig\n\n# load the above JSON object from a file\nwith open(\"service-to-parameter-mappings.json\", \"r\") as f:\n param_config = json.load(f)\n\napp = AppConfig(mappings_path=param_config)\n```\n\nOne of the big advantages of the library is that no API calls are made when you instantiate the `AppConfig` class. Instead, it will only make API calls when you access a parameter or secret through the `AppConfig.params` or `AppConfig.secrets` attributes.\n\n#### Accessing Parameters and Secrets\nFinally you can access parameters and secrets like this:\n```python\n# access a parameter\nMyParam1 = app.params.MyParam1\n\n# access a secret\nMySecret1 = app.secrets.MySecret1\n```\nThis 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.\n\n### Advantages\n- Fast, simple interface to configuration values that can reduce development overhead when working with SSM Parameter Store and SecretsManager\n- Immediate access to available parameters and secrets through intellisense, `map` or `list` methods\n- Maintain least-privileged permissions to parameters and secrets using path-based access control\n- Lazy loading for all available parameters or secrets, meaning it will only make API calls when a value is requested:\n - 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.\n - 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.\n\n### Considerations\n* You must use the path convention for naming parameters, but you can choose any separator you want by setting the `path_separator` parameter when creating an instance of `AppConfig`. The default is `/`.\n* Only the latest parameter versions can be fetched.\n\n## Quickstart\nInstall the library using pip.\n```bash\npip install -i https://test.pypi.org/simple/ aws-parameters\n```\n\n## Environment Configuration\n\n### Parameter Mappings\nThe `AppConfig` class requires a JSON object with service to parameter mappings in order to know which values it needs to access:\n```json\n// Parameter Mappings JSON Schema\n{\n \"ssm\": [\n \"parameter_path_and_identifier\",\n ...\n ],\n \"secretsmanager\": [\n \"secret_path_and_identifier\",\n ...\n ]\n}\n```\n\nFor example:\n```json\n{\n \"ssm\": [\n \"/dev/myapp/MyParam1\",\n \"/dev/myapp/MyParam2\"\n ],\n \"secretsmanager\": [\n \"/dev/myapp/MySecret1\",\n \"/dev/myapp/MySecret2\"\n ]\n}\n```\nIn this example, the path is `/dev/myapp` and the identifiers or names are `MyParam1`, `MyParam2`, `MySecret1`, and `MySecret2`.\n\nYou can store this in a JSON file or as its own SSM Parameter.\n\n### Configuration Methods\n\n<!-- TODO\nThere are 3 methods of creating or providing this JSON object to `aws-parameters`:\n1. From a local JSON file (fastest)\n2. From a parameter path such as `/dev/myapp/*` (second fastest)\n3. From deployed SSM Parameter mapping (third fastest) -->\n\nThe current method of providing this JSON object to `aws-parameters` is from deployed SSM Parameter mapping (third fastest)\n\nSee [Methods of Access](#methods-of-access) for more details.\n\n\n<!-- #### JSON File or Object\nThis is the fastest method but it requires that the JSON file is up to date with the latest parameters and secrets.\n\n### Parameter Path\nChoose and utilize a path naming convention in your cloud resource definitions for SSM Parameters or SecretsManager Secrets. \n\nFor example you can use the template `/{stage}/{app name}/{parameter or secret name}` when creating SSM Parameters or Secrets. You could then just pass the path `/{stage}/{app name}/*` to `aws-parameters` and it will use AWS SDK methods for Systems Manager and SecretsManager to listor describe and retrieve all available parameters or secrets under that path. -->\n\n\n#### From SSM Parameter\nFor 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:\n```yaml\nAWSTemplateFormatVersion: \"2010-09-09\"\nParameters:\n AppName:\n Type: String\n Description: Name of the application\n Stage:\n Type: String\n Description: Stage of the application\nResources:\n ParamMappingsParameter:\n Type: AWS::SSM::Parameter\n Properties:\n Type: String\n Name: !Sub '/${Stage}/${AppName}/MyParamMappings'\n Description: \"Parameter mappings for aws-parameters\"\n Tier: Standard\n Value: !Sub |\n {\n \"ssm\": [\n \"/${Stage}/${AppName}/MyParam1\",\n \"/${Stage}/${AppName}/MyParam2\"\n ],\n \"secretsmanager\": [\n \"/${Stage}/${AppName}/MySecret1\",\n \"/${Stage}/${AppName}/MySecret2\"\n ]\n }\n```\n\n## Usage\nSee [Configuration Methods](#configuration-methods) for the different ways to setup the environment and access SSM Parameters and SecretsManager Secrets values.\n\n```python\nfrom awsparameters import AppConfig\n\n# (optional) Create a boto3 session outside the class \nsession = boto3.Session(region_name=AWS_REGION)\n\n# Retrieve the Parameter Mappings from SSM Parameter Store\nmappings_path = \"/dev/myapp/MyParamMappings\"\n\n# Create the AppConfig object from the mappings path\napp = AppConfig(\n mappings_path=mappings_path, \n boto3_session=session)\n```\n\n\nTo see all the available parameters and secrets by namespace, you can access the `map` attribute:\n```python\n# print all available parameters\napp.map\n\n# output\n{\n \"ssm\": [\n \"/dev/myapp/MyParam1\",\n \"/dev/myapp/MyParam2\"\n ],\n \"secretsmanager\": [\n \"/dev/myapp/MySecret1\",\n \"/dev/myapp/MySecret2\"\n ]\n}\n```\n\n## Local Development\nFollow the steps to set up the deployment environment.\n\n### Prerequisites\n* Python 3.10\n* AWS credentials\n\n### Creating a Python Virtual Environment\nWhen developing locally, create a Python virtual environment to manage dependencies:\n```bash\npython3.10 -m venv .venv\nsource .venv/bin/activate\npip install -U pip\npip install .[dev,test]\n```\n\n## Unit Tests\nFollow the steps above to create a Python virtual environment. Run tests with the following command.\n```bash\nmake test\n```\n\n## Authors\n**Primary Contact:** [@chrisammon3000](https://github.com/chrisammon3000)\n\n## License\nThis library is licensed under the MIT-0 License. See the LICENSE file.\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2023 Gregory Lindsey Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ",
"summary": "Streamlined, efficient access to configuration values in AWS SSM Parameter Store and SecretsManager.",
"version": "0.1.7",
"project_urls": null,
"split_keywords": [
"aws",
"systems manager",
"configuration",
"secretsmanager"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5c2c401bc7c8aa6f62116f0b3db65f903c7d3f7c6cc739e5a4af61def0eaea91",
"md5": "d76b82fe73a07309e935677f2e31fa5d",
"sha256": "cb8e04454a9d2e21b16bd91bb1ac1162a01780e07da9cd19975f892d2566fbcd"
},
"downloads": -1,
"filename": "aws_parameters-0.1.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d76b82fe73a07309e935677f2e31fa5d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 8933,
"upload_time": "2023-08-06T00:45:10",
"upload_time_iso_8601": "2023-08-06T00:45:10.533703Z",
"url": "https://files.pythonhosted.org/packages/5c/2c/401bc7c8aa6f62116f0b3db65f903c7d3f7c6cc739e5a4af61def0eaea91/aws_parameters-0.1.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "64e3bcf1a3b806945c6214872eb5225c54a29110db4dcaff92bef9cc367bb004",
"md5": "4fc67cd96c59466b23a0d6b9c05dc7bc",
"sha256": "7e4818565d6551980521e03a86f4c23b57e58572cb1c8c66ba90d995cdb05ec9"
},
"downloads": -1,
"filename": "aws-parameters-0.1.7.tar.gz",
"has_sig": false,
"md5_digest": "4fc67cd96c59466b23a0d6b9c05dc7bc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 12757,
"upload_time": "2023-08-06T00:45:12",
"upload_time_iso_8601": "2023-08-06T00:45:12.348171Z",
"url": "https://files.pythonhosted.org/packages/64/e3/bcf1a3b806945c6214872eb5225c54a29110db4dcaff92bef9cc367bb004/aws-parameters-0.1.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-06 00:45:12",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "aws-parameters"
}
