Skip to main content

A tool to manage contents of AWS SSM Parameter Store

Project description

ssm-diff

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:

Dev:
  DBServer:
    MySQL:
      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.

Installation

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.

Finally

$ 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.

Examples

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:

qa:
  ci:
    api:
      db_schema: foo_ci
      db_user: bar_ci
      db_password: !secure 'baz_ci'
  uat:
    api:
      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:

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

Running

$ 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

Finally

$ 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.

Filename, size & hash SHA256 hash help File type Python version Upload date
ssm_diff-0.5-py3-none-any.whl (6.6 kB) Copy SHA256 hash SHA256 Wheel py3

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page