{"id":13501212,"url":"https://github.com/fictive-kin/dynaconf-aws-loader","last_synced_at":"2025-12-24T09:49:51.009Z","repository":{"id":173083043,"uuid":"648463315","full_name":"fictive-kin/dynaconf-aws-loader","owner":"fictive-kin","description":"A Dynaconf loader for AWS Systems Manager Parameter Store that can query slash-delimited hierarchical configuration data.","archived":false,"fork":false,"pushed_at":"2023-07-21T00:35:06.000Z","size":55,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-16T15:19:10.064Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fictive-kin.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2023-06-02T03:09:22.000Z","updated_at":"2024-08-19T10:04:03.000Z","dependencies_parsed_at":"2023-07-21T21:31:58.881Z","dependency_job_id":null,"html_url":"https://github.com/fictive-kin/dynaconf-aws-loader","commit_stats":null,"previous_names":["fictivekin/dynaconf-aws-loader","fictive-kin/dynaconf-aws-loader"],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fictive-kin%2Fdynaconf-aws-loader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fictive-kin%2Fdynaconf-aws-loader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fictive-kin%2Fdynaconf-aws-loader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fictive-kin%2Fdynaconf-aws-loader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fictive-kin","download_url":"https://codeload.github.com/fictive-kin/dynaconf-aws-loader/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246162092,"owners_count":20733351,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T22:01:29.337Z","updated_at":"2025-12-24T09:49:51.002Z","avatar_url":"https://github.com/fictive-kin.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"Dynaconf AWS Systems Manager Parameter Store Loader\n====================================================\n\nWhen configured, this loader will permit Dynaconf to query `AWS Systems Manager Parameter Store \u003chttps://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html\u003e`_ for slash-delimited hierarchical configuration data.\n\nLoader Configuration\n--------------------\n\nAn example:\n\n.. code-block:: python\n\n    from dynaconf import Dynaconf\n\n    settings = Dynaconf(\n        environments=True,\n        settings_file=\"settings.toml\",\n        LOADERS_FOR_DYNACONF=[\n            \"dynaconf_aws_loader.loader\",\n            \"dynaconf.loaders.env_loader\"\n        ],\n    )\n\n\nNote that for the basic functioning of this loader, the `environments \u003chttps://www.dynaconf.com/configuration/#environments\u003e`_ option for ``Dynaconf`` must be set, and an environment must be used.\n\nConfiguration Variables\n-----------------------\n\nBoth of the following configuration values should be set in the *environment* to avoid a chicken/egg scenario for initializing this custom loader:\n\n- ``SSM_PARAMETER_PROJECT_PREFIX_FOR_DYNACONF``: Required.\n  The ``project`` prefix in the parameter store path. For example, if the parameter hierarchy looks something like ``/baldur/development/database_uri``, then in this case ``SSM_PARAMETER_PROJECT_PREFIX_FOR_DYNACONF=baldur``.\n\n- ``SSM_PARAMETER_NAMESPACE_FOR_DYNACONF``: Optional.\n  This provides an additional level of grouping once the project and environment have been determined. For example, if the parameter hierarchy looks something like ``/baldur/pr-123/development/database_uri``, then ``SSM_PARAMETER_NAMESPACE_FOR_DYNACONF=pr-123``.\n\n.. note::\n   If a namespace is utilized, be aware that namespaced settings will be *merged* with non-namespaced settings. This merge is a naive one, where namespaced settings will completely overwrite non-namespaced settings with the same key.\n\nThe following optional variables should be set in your ``settings.toml`` (or equivalent format), if desired:\n\n- ``SSM_ENDPOINT_URL_FOR_DYNACONF``: If your AWS SSM uses a different endpoint than the AWS default. This can be useful for local development when you are running something like `LocalStack \u003chttps://localstack.cloud/\u003e`_.\n- ``SSM_SESSION_FOR_DYNACONF``: If you require custom `boto3.session.Session \u003chttps://boto3.amazonaws.com/v1/documentation/api/latest/reference/core/session.html\u003e`_ arguments, you can specify then as a dictionary here. Note that this will override the default ``boto3`` credential configuration.\n- ``SSM_LOAD_DEFAULT_ENV_FOR_DYNACONF``: Boolean, defaults to ``True``. If you want the SSM loader to load keys under the ``default`` environment name. The key name itself can be set via the Dynaconf setting of ``DEFAULT_ENV_FOR_DYNACONF`` if you want it to be something other than ``default``.\n\n\nParameter Store Details\n~~~~~~~~~~~~~~~~~~~~~~~\n\nThe structure that this loader expects from the path-based organization in SSM is:\n\n.. code-block::\n\n    /\u003cproject-name\u003e/\u003cenvironment\u003e/\u003cparameter-name\u003e\n\n\nAn optional ``namespace`` can be specified as a sub-project grouping for parameters:\n\n.. code-block::\n\n    /\u003cproject-name\u003e/\u003cenvironment\u003e/\u003cnamespace\u003e/\u003cparameter-name\u003e\n\n\nNote that if you choose to use a ``namespace`` identifier, it must not conflict with existing ``environment`` identifiers.\n\nIf ``SSM_LOAD_DEFAULT_ENV_FOR_DYNACONF`` is set to ``True`` (which is the default value), the loader will add whatever the value of ``DEFAULT_ENV_FOR_DYNACONF`` as an ``environment`` key to load from SSM. The typical use case here is to have a default value for all environments that can be overriden on a per-environment basis as necessary.\n\n\nSecurity Considerations\n~~~~~~~~~~~~~~~~~~~~~~~\n\nFor this loader to function correctly and securely, the use of IAM policies to restrict which parameters can be read/mutated is highly encouraged.\n\nPolicies can be enacted on a glob-path basis, which will ensure that the only parameters that can be fetched/hydrated into the local object instance are the ones that the current environment is permitted to load.\n\nThe following policy for a fictional account allows a user to call the ``DescribeParameters`` and ``GetParameters`` API operations for parameters that begin with the path ``/testapp/production``:\n\n.. code-block:: json\n\n    {\n        \"Version\": \"2012-10-17\",\n        \"Statement\": [\n            {\n                \"Effect\": \"Allow\",\n                \"Action\": [\n                    \"ssm:DescribeParameters\"\n                ],\n                \"Resource\": \"*\"\n            },\n            {\n                \"Effect\": \"Allow\",\n                \"Action\": [\n                    \"ssm:GetParameters\"\n                ],\n                \"Resource\": \"arn:aws:ssm:us-east-1:000000000000:parameter/testapp/production*\"\n            }\n        ]\n    }\n\n\n.. warning::\n\n    If a user has access to a path, then the user can access all levels of that path. For example, if a user has permission to access path ``/testapp``, then the user can also access ``testapp/production``. Even if a user has explicitly been denied access in IAM for parameter ``/testapp/production``, they can still call the ``GetParametersByPath`` API operation recursively for ``/testapp`` and view ``/testapp/production``.\n\n\nSetting Parameters via Boto3\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nParameters may be set via the AWS Web Console UI, or one of their many client libraries. The `boto3 \u003chttps://boto3.amazonaws.com/v1/documentation/api/latest/index.html\u003e`_ library is perhaps the most well-known, and the process is relatively straightforward:\n\n.. code-block:: python\n\n    import boto3\n    ssm_client = boto3.client(\"ssm\")\n\n    ssm_client.put_parameter(\n        Name=\"/testapp/development/database/host\",\n        Value=\"localhost\",\n        Type=\"String\",\n    )\n\n    ssm_client.put_parameter(\n        Name=\"/testapp/production/database/password\",\n        Value=\"sekrit\",\n        Type=\"SecureString\",\n    )\n\n    ssm_client.put_parameter(\n        Name=\"/testapp/production/database/host\",\n        Value=\"db.example.com\",\n        Type=\"String\",\n    )\n\n    ssm_client.put_parameter(\n        Name=\"/testapp/production/admin_email\",\n        Value=\"help@example.com\",\n        Type=\"String\",\n    )\n\n\nThis creates a parameter hierarchy with the following structure:\n\n.. code-block:: json\n\n    {\n        \"testapp\": {\n            \"development\": {\"database\": {\"host\": \"localhost\"}},\n            \"production\": {\n                \"database\": {\"host\": \"db.example.com\", \"password\": \"sekrit\"},\n                \"admin_email\": \"help@example.com\",\n            },\n        },\n    }\n\n\nParameter Name Limitations\n--------------------------\n\nAWS SSM has the following key (and thus path) limitations:\n\n- Parameter names are case sensitive\n- A parameter name must be unique within an Amazon Web Services Region\n- A parameter name can't be prefixed with \"aws\" or \"ssm\" (case-insensitive)\n- Parameter names can include only the following symbols and letters: a-zA-Z0-9\\_.-\n- The slash character ( ``/`` ) is used to delineate hierarchies in parameter names\n- A parameter name can't include spaces\n- Parameter hierarchies are limited to a maximum depth of fifteen levels\n\n\nTesting\n~~~~~~~\n\n0. Have Docker installed and running\n1. Clone this repository\n2. Ensure you have `poetry` available on your system\n3. `poetry run pytest`\n\nThe test suite will spin up an ephemeral Docker container; it may take a few seconds for it to load. The relevant test fixtures will handle setting parameters and their values in the Localstack SSM service.\n\n\nTODO\n~~~~\n\n- [ ] CI configuration for matrix-based python/dynaconf version testing\n- [ ] Handle `Parameter Store references to AWS Secrets Manager \u003chttps://docs.aws.amazon.com/systems-manager/latest/userguide/integration-ps-secretsmanager.html\u003e`_\n- [ ] Make ``tests/docker-compose.yml`` more configurable, e.g. ports, in case a different Localstack container is already running for the user\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffictive-kin%2Fdynaconf-aws-loader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffictive-kin%2Fdynaconf-aws-loader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffictive-kin%2Fdynaconf-aws-loader/lists"}