SSM Naming Convention

Background

Historically BFD applications have been configured using a combination of environment variables and java system properties. In order for this to work in production the deployment automation had to place the necessary values into a startup script that sets up the environment variables and then runs the application. Because the configuration settings actually lived in SSM Parameter Store this added a layer of complexity to the deployment automation. The automation first copied the settings into SSM parameters, then downloaded them from SSM on the EC2 instance to insert them into a shell script template, and finally ran the script to launch the application.

The applications already have the ability to retrieve their configuration settings directly from SSM. This document describes the conventions and changes needed to use this feature in the future.

Naming Convention for SSM Hierarchies

SSM Parameters are essentially key/value pairs stored in the AWS SSM service. Parameters can be defined in a directory like structure by using / to separate folders. As with files and directories this allows parameters to be organized into hierarchies. For purposes of this document a hierarchy is simply one or more parameters contained under the same folder. The choice of folders to use is arbitrary but following a convention allows the parameters to be organized more easily. SSM allows programs to retrieve all parameters in a single folder or to retrieve all parameters in an entire hierarchy.

The naming convention used for SSM parameters is based on the RFC 0015-centralized-configuration-management and updated based on current practice. Refer to that RFC for background.

Hierarchies will follow either a 4 or 5 level convention.

• /${project}/${env}/${group}/${sensitivity}/
• /${project}/${env}/${group}/${subgroup}/${sensitivity}

In these examples project will generally be bfd, env will be one of prod, prod-sbx, or test. Group will be one of common, jenkins, migrator, server, or pipeline. Sub-groups are only used for the pipeline and will generally have the value rif or rda. Sensitivity will be either sensitive or nonsensitive. Anything following this will be mapped by the application using the logic previously described.

Mapping of SSM Parameter Hierarchies

At start-up the applications will retrieve all parameters from one or more hierarchies and combine them to create a map of parameter names to values.

Each hierarchy consists of one or more parameters under a base path. Parameters can be located at the root of the hierarchy or nested to arbitrary depth within the hierarchy. The name used by the application for any given parameter is formed by:

• removing the root path from the parameter name
• replacing any / in the remaining path with a .

For example if a hierarchy rooted at /x/y/z/ has the following structure:

/x/y/z/
  bfdServer/
    db_url = "..."
    flags/
      v2_enabled = true
      pac_enabled = true
    

The resulting parameters as viewed by the application would be:

• bfdServer.db_url
• bfdServer.flags.v2_enabled
• bfdServer.flags.pac_enabled

The application can be configured to pull parameters from a list containing multiple hierarchies. It applies a last-one-wins priority scheme to the parameters. Thus if the first and last hierarchies both contain a value for a parameter with a given name the one from the last hierarchy will be used and the one from the first hierarchy will be ignored. This only applies at the parameter level, not at the folder level. So for example given these hierarchies:

• /x/y/fruit/apple
• /x/y/fruit/pair
• /z/fruit/apple

The application, when configured with the hierarchies /x/y and /z, would use fruit.apple from /z and fruit.pair from /x/y. The value for fruit.apple under /x/y would be ignored.

Specifying Hierarchies for an Application

Applications look for an environment variable named CONFIG_SETTINGS_JSON. This should contain JSON that can define either or both of propertiesFile and ssmHierarchies. The latter is a JSON list of SSM hierarchy paths. They will be applied in increasing priority order (as described previously). Generally propertiesFile would only be used for local development or testing. For example:

{
  "propertiesFile":"pipeline.properties",
  "ssmHierarchies": [
    "/bfd/prod/common/sensitive",
    "/bfd/prod/common/nonsensitive",
    "/bfd/prod/pipeline/shared/sensitive",
    "/bfd/prod/pipeline/shared/nonsensitive",
    "/bfd/prod/pipeline/rda/sensitive",
    "/bfd/prod/pipeline/rda/nonsensitive"
  ]
 }

Grand Restructuring of Parameter Names

Currently the application's configuration settings follow no particular naming convention. Their capitalization is based on how they were historically defined (dotted camel case for properties, upper snake case for environment variables). Initially we can continue to use the current names but when we adopt this new convention they will all have to be renamed.

Here are some suggested changes:

• bfdServer.db.url -> db/url, the prefix is no longer necessary since the hierarchy will already determine the group.
• bfdServer.pac.enabled -> pac/enabled, the prefix is removed and the pac becomes a folder.
• BFD_KEYSTORE -> ssl/keystore, the two files can be placed into a common folder named ssl.
• DATABASE_URL -> db/url, all of the database settings could in a db folder.

Unchanged Environment Variables

A few of the current environment variables are used by the layered configuration so they must remain in place. These are:

• AWS_REGION
• AWS_ENDPOINT
• AWS_ACCESS_KEY
• AWS_SECRET_KEY
• CONFIG_SETTINGS_JSON