Skip to main content

A tool to manage contents of AWS SSM Parameter Store

Project description


AWS SSM Parameter Store is a really convenient, AWS-native, KMS-enabled storage for parameters and secrets.

Unfortunately, as of now, it doesn't seem to provide any human-friendly ways of batch-managing hierarchies of parameters.

The goal of the ssm-diff tool is to simplify that process by unwraping path-style (/Dev/DBServer/MySQL/db-string13 = value) parameters into a YAML structure:

      db-string13: value

Then, given that this local YAML representation of the SSM Parameter Store state was edited, calculating and applying diffs on the parameters.

ssm-diff supports complex data types as values and can operate within single or multiple prefixes.


pip install ssm-diff

Geting Started

The tool relies on native AWS SDK, thus, on a way SDK figures out an effective AWS configuration. You might want to configure it explicitly, setting AWS_DEFAULT_REGION, or AWS_PROFILE, before doing and manipulations on parameters

When AWS_PROFILE environment variable is set, local state file will have a name corresponding to the profile name.

Before we start editing the local representation of parameters state, we have to get it from SMM:

$ ssm-diff init

will create a local parameters.yml (or <AWS_PROFILE>.yml if AWS_PROFILE is in use) file that stores a YAML representation of the SSM Parameter Store state.

Once you accomplish editing this file, adding, modifying or deleting parameters, run:

$ ssm-diff plan

Which will show you the diff between this local representation and an SSM Parameter Store.


$ ssm-diff apply

will actually apply local changes to the Parameter Store.

Operations can also be limited to a particular prefix(es):

$ ssm-diff -p /dev -p /qa/ci {init,plan,apply}

NOTE: when remote state diverges for some reason, but you still want to preserve remote changes, there's a:

$ ssm-diff pull

command, doing just that.


Let's assume we have the following parameters set in SSM Parameter Store:

/qa/ci/api/db_schema    = foo_ci
/qa/ci/api/db_user      = bar_ci
/qa/ci/api/db_password  = baz_ci
/qa/uat/api/db_schema   = foo_uat
/qa/uat/api/db_user     = bar_uat
/qa/uat/api/db_password = baz_uat

$ ssm-diff init

will create a parameters.yml file with the following content:

      db_schema: foo_ci
      db_user: bar_ci
      db_password: !secure 'baz_ci'
      db_schema: foo_uat
      db_user: bar_uat
      db_password: !secure 'baz_uat'

KMS-encrypted (SecureString) and String type values are distunguished by !secure YAML tag.

Let's drop the ci-related stuff completely, and edit uat parameters a bit, ending up with the following parameters.yml file contents:

      db_schema: foo_uat
      db_charset: utf8mb4 
      db_user: bar_changed
      db_password: !secure 'baz_changed'


$ ssm-diff plan

will give the following output:

- /qa/ci/api/db_schema
- /qa/ci/api/db_user
- /qa/ci/api/db_password
+ /qa/uat/api/db_charset = utf8mb4
~ /qa/uat/api/db_user:
  < bar_uat
  > bar_changed
~ /qa/uat/api/db_password:
  < baz_uat
  > baz_changed


$ ssm-diff apply

will actually do all the necessary modifications of parameters in SSM Parameter Store itself, applying local changes

Known issues and limitations

  • There's currently no option to use different KMS keys for SecureString values encryption.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release. See tutorial on generating distribution archives.

Built Distribution

ssm_diff-0.5-py3-none-any.whl (6.6 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page