SSM Parameter Conventions

Autoload Convention Path

Jets will autoload SSM parameters under the path of /PROJECT/ENV/. This means SSM parameters like

/demo/dev/DATABASE_URL
/demo/dev/SECRET_KEY_BASE

All you have to do is create them in AWS SSM parameter store, and they are automatically loaded. So the config/jets/env/.env is entirely optional. This behavior can be configured with:

config/jets/project.rb

Jets.project.configure do
  config.dotenv.ssm.autoload = true # default: true
end

This spares you from updating your config/jets/env files with newly added SSM parameters. Here’s a useful CLI command to see what values are in SSM.

❯ aws ssm get-parameters-by-path --path "/demo/dev/" | jq -r '.Parameters[].Name' | sort
/demo/dev/DATABASE_URL
/demo/dev/SECRET_KEY_BASE

For those who prefer more control over the SSM env variables, you can turn off the behavior and use explicit jets/config/env files. If you using both, the explicit values always win.

Note: Jets uses the optimized get_parameters_by_path API call. It efficiently retrieves multiple parameters that share a path hierarchy. This minimizes API calls compared to fetching parameters individually and avoids rate limit issues. The implementation does not use the recursive option by design, so the parameters should be within the same hierarchy level.

Conventional SSM Names

Additionally, there is some conventional SSM name logic to help DRY up your dotenv files. Some examples probably best help explain:

DATABASE_URL=SSM        # => DATABASE_URL=/demo/dev/DATABASE_URL
DATABASE_URL=SSM:DB_URL # => DATABASE_URL=/demo/dev/DB_URL

If the value starts with a / right after SSM:, IE: SSM:/abs/path/DB_URL, then the conventional behavior is not performed.

DATABASE_URL=SSM:/shared/dev/DB_URL # => DATABASE_URL=/shared/dev/DB_URL

Custom Convention Resolver

The conventional SSM name works like this:

DATABASE_URL=SSM        # => DATABASE_URL=/demo/dev/DATABASE_URL
DATABASE_URL=SSM:DB_URL # => DATABASE_URL=/demo/dev/DB_URL

For advanced use cases where the that logic does not work for your needs, you can configure a custom convention_resolver.

config/jets/project.rb

Jets.project.configure do
  config.dotenv.ssm.convention_resolver = ->(ssm_leaf_name) do
    "/#{Jets.project.name}/#{ssm_env}/#{ssm_leaf_name}"
  end
end

It can be any object that responds to .call and is passed the ssm_leaf_name as an argument.

Reference

The table below covers each setting. Each option is configured with config.OPTION. The config. portion is not shown for conciseness. IE: logger.level vs config.logger.level.

See Full Config Reference