guardian / configraun

Simple configuration library built around AWS's Systems Manager Parameter Store

Version Matrix


Configraun is a thin wrapper around AWS's Systems Manager Parameter Store. Parameter store allows you to manage your configuration data in one place including plain data and secure data encrypted through AWS KMS.

Using Parameter Store to store your applications configuration has a number of benefits:

  1. You can control who and what resources access specific config through IAM credentials at a granular level.
  2. You can make use of AWS KMS to encrypt information and protect the security of your keys.
  3. Any changes to configuration in Parameter Store are versioned providing an audit trail of what has changed and by whom. In fact all calls to Parameter Store may be audited via Cloudtrail.
  4. Parameter store gives you some type safety around the type of the configuration item returned to you. I.e String | Secure String | String List.
  5. Config items can be tagged.


Add the following line to your SBT build definition, and set the version number to be the latest from the releases page:

libraryDependencies += "" %% "configraun" % "x.y"

You will then need to create a new instance of the client and set the key:

  implicit val client: AWSSimpleSystemsManagement = AWSSimpleSystemsManagementFactory(region, profile)

  val stack: String = "STACK"
  val stage: Stage = Stage.PROD
  val app: String = "APP"

  val config = Configraun.loadConfig(stack, app, stage)

Or, for an EC2 instance with appropriate IAM policies (see below):

  implicit val client: AWSSimpleSystemsManagement = AWSSimpleSystemsManagementFactory(region, profile)

  val config = Configraun.loadConfig()


Each of the get methods returns an Either[ConfigraunError, T], designed to be traversed within a for comprehension.




Key Format

Configraun expects that any parameters are keyed with a parameter hierarchy format. The hierarchy can have a maximum of 5 levels and must begin with /$stack/$app/$stage.






Key Value Creation

Keys can be created from the command line using the following:

aws --region $region --profile $profile ssm put-parameter --name '/mystack/myapp/PROD/mydomain/mykey' --value 'myvalue' --type String

IAM Policies

Instances will need to have Describe Tags permission in a policy in their instance role, or via some other form of credentials provider:

    "Effect": "Allow",
    "Action": "ec2:DescribeTags",
    "Resource": "*"