{"id":29374689,"url":"https://github.com/garyd203/ssmash","last_synced_at":"2026-05-17T01:49:38.663Z","repository":{"id":56366327,"uuid":"186609998","full_name":"garyd203/ssmash","owner":"garyd203","description":"ssmash - Simple application configuration management for AWS SSM Parameter Store","archived":false,"fork":false,"pushed_at":"2024-03-20T15:45:21.000Z","size":129,"stargazers_count":1,"open_issues_count":8,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-06-26T10:51:53.301Z","etag":null,"topics":["application-configuration","aws","hacktoberfest","infrastructure-as-code","ssm-parameter-store"],"latest_commit_sha":null,"homepage":"https://ssmash.readthedocs.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/garyd203.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELOG.rst","contributing":"CONTRIBUTING.rst","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null}},"created_at":"2019-05-14T11:40:05.000Z","updated_at":"2020-11-12T01:53:03.000Z","dependencies_parsed_at":"2022-08-15T17:20:51.954Z","dependency_job_id":null,"html_url":"https://github.com/garyd203/ssmash","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/garyd203/ssmash","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/garyd203%2Fssmash","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/garyd203%2Fssmash/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/garyd203%2Fssmash/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/garyd203%2Fssmash/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/garyd203","download_url":"https://codeload.github.com/garyd203/ssmash/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/garyd203%2Fssmash/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264502621,"owners_count":23618658,"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":["application-configuration","aws","hacktoberfest","infrastructure-as-code","ssm-parameter-store"],"created_at":"2025-07-09T20:11:23.373Z","updated_at":"2026-05-17T01:49:33.639Z","avatar_url":"https://github.com/garyd203.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"======\nssmash\n======\n\n\n.. image:: https://img.shields.io/pypi/v/ssmash.svg\n        :target: https://pypi.python.org/pypi/ssmash\n\n.. image:: https://img.shields.io/pypi/pyversions/ssmash.svg\n        :target: https://pypi.python.org/pypi/ssmash\n        :alt: Python versions\n\n.. image:: https://readthedocs.org/projects/ssmash/badge/?version=latest\n        :target: https://ssmash.readthedocs.io/en/latest/?badge=latest\n        :alt: Documentation Status\n\n.. image:: https://img.shields.io/pypi/dm/ssmash.svg\n        :target: https://pypi.python.org/pypi/ssmash\n        :alt: Downloads\n\n.. image:: https://img.shields.io/badge/code%20style-black-000000.svg\n        :target: https://github.com/ambv/black\n        :alt: Code style: black\n\n`ssmash \u003chttps://ssmash.readthedocs.io\u003e`_, the SSM AppConfig Storage Helper,\nis an easy-to-use application configuration management tool for AWS\ndeployments. You specify hierarchical configuration values in a simple YAML\nfile, and ``ssmash`` will turn that into an AWS CloudFormation file that\nstores your configuration values in the SSM Parameter Store.\n\n``ssmash`` is mainly intended for application developers who are at least partly\ninvolved in the deployment and operations of their applications. If you want\nto externalise (some of) the runtime configuration of your application, this\nis a simple and cheap solution. If you also want to be able to automatically\nrestart your application when it's configuration changes, then this **is**\nthe tool for you\n\n\nInstallation\n------------\n\nInstall ``ssmash`` using ``pip``, the standard python package installer:\n\n.. code-block:: console\n\n   $ pip install ssmash\n\nYou will probably use ``ssmash`` with the AWS command line tools, so install\nand\n`configure \u003chttps://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html\u003e`_\nthat too, if you haven't already:\n\n.. code-block:: console\n\n   $ pip install awscli\n   $ aws configure\n\n\nExample\n-------\n\nSuppose you have an input file like this:\n\n.. code-block:: yaml\n\n    acme:\n        shipping-labels-service:\n            enable-fast-delivery: true\n            explosive-purchase-limit: 1000\n            greeting: hello world\n            whitelist-users:\n                - coyote\n                - roadrunner\n\nThen run ``ssmash``:\n\n.. code-block:: console\n\n    $ ssmash -i acme_prod_config.yaml -o cloud_formation_template.yaml\n    $ aws cloudformation deploy \\\n        --stack-name \"acme-prod-config\" --template-file cloud_formation_template.yaml \\\n        --no-fail-on-empty-changeset\n\nYou will now have the following parameters in AWS Systems Manager, that can\nbe loaded as a string inside your application:\n\n* ``/acme/shipping-labels-service/enable-fast-delivery`` = \"true\"\n* ``/acme/shipping-labels-service/explosive-purchase-limit`` = \"1000\"\n* ``/acme/shipping-labels-service/greeting`` = \"hello world\"\n* ``/acme/shipping-labels-service/whitelist-users`` = \"coyote,roadrunner\"\n\n\nAutomated Application Restarts\n------------------------------\n\nMost of the time, your application loads its configuration at startup.\nDepending on your application, the safest and easiest way to reload its\nconfiguration is to simply restart it.\n\nssmash has built-in support to restart some types of application as part of\nthe deployment process. We do this by telling it to \"invalidate\" the\nconfiguration used by the application.\n\nDocker with AWS ECS\n^^^^^^^^^^^^^^^^^^^\n\n``ssmash`` can generate CloudFormation that will safely restart the Tasks in\nan ECS Service once your configuration has changed, and make the successful\ndeployment of your new application configuration depend upon the successful\nrestart of that Service. Just specify the target ECS service using extra\ncommand line parameters, like so:\n\n.. code-block:: console\n\n    $ ssmash -i acme_prod_config.yaml -o cloud_formation_template.yaml \\\n        invalidate-ecs \\\n        --cluster-name acme-prod-cluster \\\n        --service-name shipping-labels-service \\\n        --role-name arn:aws:iam::123456789012:role/acme-ecs-admin\n    $ aws cloudformation deploy \\\n        --stack-name \"acme-prod-config\" --template-file cloud_formation_template.yaml \\\n        --no-fail-on-empty-changeset\n\nYou can also refer to the name of a `CloudFormation Export\n\u003chttps://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-stack-exports.html\u003e`_\ninstead of using the name directly (eg. if your service has a non-obvious\ngenerated name), using the interchangeable command line parameters for\n``--cluster-import`` and ``--service-import`` and ``--role-import``.\n\nServerless with AWS Lambda\n^^^^^^^^^^^^^^^^^^^^^^^^^^\n\n``ssmash`` can generate CloudFormation that will safely cause your\nserverless functions to discard their virtual machine (aka \"`Execution Context\n\u003chttps://docs.aws.amazon.com/lambda/latest/dg/running-lambda-code.html\u003e`_\"),\nmeaning they effectively reload their configuration. To\naccess this secret sauce, just add a couple more command line parameters:\n\n.. code-block:: console\n\n    $ ssmash -i acme_prod_config.yaml -o cloud_formation_template.yaml \\\n        invalidate-lambda \\\n        --function-name shipping-label-printer-function \\\n        --role-name arn:aws:iam::123456789012:role/acme-serverless-admin\n    $ aws cloudformation deploy \\\n        --stack-name \"acme-prod-config\" --template-file cloud_formation_template.yaml \\\n        --no-fail-on-empty-changeset\n\nYou can also refer to the name of a `CloudFormation Export\n\u003chttps://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-stack-exports.html\u003e`_\ninstead of using the name directly, using the interchangeable command line\nparameters for ``--function-import`` and ``--role-import``.\n\n\nAdvanced: Automated Restarts For Only Some Parameters\n-----------------------------------------------------\n\nAutomated application restarts are great, but they don't scale when you have\na single configuration file that is used by multiple applications - you don't\nwant to restartevery application every time one of the config values changes.\nHappily, ``ssmash`` can handle that too - you just need to invoke the magic\n(madness!) of YAML tags, which allow us to add metadata to any part of the\nconfiguration hierarchy (either leaf configuration values, or tree nodes).\n\nFirst, let's extend the above example to include configuration for another\napplication:\n\n.. code-block:: yaml\n\n    acme:\n        common:\n            enable-slapstick: true\n            region: us-west-2\n        shipping-labels-service:\n            enable-fast-delivery: true\n            explosive-purchase-limit: 1000\n            greeting: hello world\n            whitelist-users:\n                - coyote\n                - roadrunner\n        warehouse-service:\n            item-substitutes:\n                birdseed: \"iron pellets\"\n                parachute: \"backpack\"\n\nNow we add a special ``.ssmash-config`` key to tell ``ssmash`` how to restart\nour applications. Then we annotate the configuration hierarchy using custom\nYAML tags to tell ``ssmash`` which applications are invalidated by which parts\nof the configuration hierarchy:\n\n.. code-block:: yaml\n\n    ---\n    .ssmash-config:\n        invalidations:\n            # The dictionary key here (\"shipping-labels\") is used in the\n            # configuration hierarchy to refer to this application\n            shipping-labels: !ecs-invalidation\n                # The `!ecs-invalidation` tag tells ssmash that this application\n                # uses ECS, and the configuration fields correspond to those used\n                # on the command line\n                cluster_name: acme-prod-cluster\n                service_name: shipping-label-service\n                role_name: arn:aws:iam::123456789012:role/acme-ecs-admin\n            warehousing: !ecs-invalidation\n                cluster_name: acme-prod-cluster\n                service_name: warehouse-service\n                role_name: arn:aws:iam::123456789012:role/acme-ecs-admin\n    acme:\n        common:\n            # This is a single leaf configuration value called \"enable-slapstick\",\n            # which will cause both applications to restart when it is changed\n            ? !item { invalidates: [ shipping-labels, warehousing ], key: enable-slapstick }\n            : true\n            region: us-west-2\n        # This is a tree node called \"shipping-labels-service\", which will cause\n        # the \"shipping-labels\" application defined above to restart when any of\n        # it's configuration values are changed\n        ? !item { invalidates: [ shipping-labels ], key: shipping-labels-service }\n        :\n            enable-fast-delivery: true\n            explosive-purchase-limit: 1000\n            greeting: hello world\n            whitelist-users:\n                - coyote\n                - roadrunner\n        # This is a tree node called \"warehouse-service\", which will cause\n        # the \"warehousing\" application defined above to restart when any of\n        # it's configuration values are changed\n        ? !item { invalidates: [ warehousing ], key: warehouse-service }\n        :\n            item-substitutes:\n                birdseed: \"iron pellets\"\n                parachute: \"backpack\"\n\n\nThen run ``ssmash`` normally:\n\n.. code-block:: console\n\n    $ ssmash -i acme_prod_config.yaml -o cloud_formation_template.yaml\n    $ aws cloudformation deploy \\\n        --stack-name \"acme-prod-config\" --template-file cloud_formation_template.yaml \\\n        --no-fail-on-empty-changeset\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgaryd203%2Fssmash","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgaryd203%2Fssmash","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgaryd203%2Fssmash/lists"}