python-aws-ssm

Python package that interfaces with AWS System Manager.

Why to use python-aws-ssm and not the boto3 SSM client?

This package is wrapping boto3 SSM client and hides the complexity dealing with the not so Python friendly AWS SDK. Perfect use case for this package is when secure parameters for an application are stored to AWS Parameter Store using a path hierarchy. During application startup you can use this package to fetch them and use them in your application.

Warning

The SSM service is rate-limited by default. We strongly suggest using retrieving SSM keys by path, e.g. via ParameterStore.get_parameters_by_path(). This requires grouping keys by a useful path but reduces the chance of your own services being rate-limited in turn.

Install

pip install python-aws-ssm

Examples

Basic Usage

from python_aws_ssm.parameters import ParameterStore

# Assuming you have the parameters in the following format:
# my-service/dev/param-1  -> with value `a`
# my-service/dev/param-2  -> with value `b`
parameter_store = ParameterStore()
# Requesting the base path
parameters = parameter_store.get_parameters_by_path("/my-service/dev/")
# And getting a specific value
value = parameters.get("param-1")
# value should be `a`

Required parameters on path

Requesting parameters by path is efficient but comes with an additional burden of validation: clients typically expect a number of keys to be present, e.g. the path /service/foo/db/ might be used to retrieve the database credentials including the host name at /service/foo/db/hostname. The onus of verifying that this key is present is by default on the client.

To assert the presence of these keys automatically, pass a set of required parameters via the parameters keyword argument:

from python_aws_ssm.parameters import ParameterStore, MissingParameterError

# Assuming you have the following keys:
#  * /service/foo/db/hostname
#  * /service/foo/db/username
#  * /service/foo/db/password
#  * /service/foo/db/port
#  * /service/foo/db/description
parameter_store = ParameterStore()
# Requesting the base path but asserting presence of required parameters
try:
    parameters = parameter_store.get_parameters_by_path(
            "/service/foo/db/",
            required_parameters={"hostname", "username", "password", "port"}
        )
except MissingParameterError as e:
    # Report on the missing parameters.
    print(e.msg)
else:
    # Use the parameters, knowing that they exist.
    print(parameters['hostname'])  # guaranteed to exist.

Recursive and nested options

from python_aws_ssm.parameters import ParameterStore

# Assuming you have the parameters in the following format:
# my-service/dev/param-1  -> with value `a`
# my-service/dev/param-2  -> with value `b`
parameter_store = ParameterStore()
# Requesting the base path
parameters = parameter_store.get_parameters_by_path(
    "/my-service/", recursive=True, nested=True
)
# And getting a specific value
dev_parameters = parameters.get("dev")
# value should be {"param-1": "a", "param-2": "b"}

Get parameters by name

from python_aws_ssm.parameters import ParameterStore

# Assuming you have the parameters in the following format:
# my-service/dev/param-1  -> with value `a`
# common/dev/param-2  -> with value `b`
parameter_store = ParameterStore()
# Requesting the base path
parameters = parameter_store.get_parameters(
    ["/my-service/dev/param-1", "/common/dev/param-2"]
)
# And getting a specific value
dev_parameters = parameters.get("/common/dev/param-2")
# value should be `b`

With custom client

from python_aws_ssm.parameters import ParameterStore
import boto3

# Initialise an SSM client to specify the source of the credentials.
# e.g. locally a profile would be more likely; an AWS Lambda would most
# likely not override the credentials source.
ssm_client = boto3.Session(profile_name='dev').client('ssm')
parameter_store = ParameterStore(ssm_client)

parameters = parameter_store.get_parameters(["/service/path/"])

Development

If you are missing any features or have found a bug, please open a PR or a new Github issue.

Setup

This project uses Poetry to manage the dependencies and the virtual environment. Follow the instructions from Poetry website (https://poetry.eustace.io/docs/#installation) to configure your local environment.

After completing the Poetry setup, the virtual environment can be created running:

make setup

Tests

Tests are run by Pytest

make test

Code style

• Mypy is used for type annotations (https://github.com/python/mypy)
• Black formatter (https://github.com/psf/black) is used to keep the coding style consistent.
• Isort (https://github.com/timothycrosley/isort) is used to sort the imports. To format the codebase just run:

make format

and to check it before pushing:

make lint