com.coveo:spring-boot-parameter-store-integration

An integration of Amazon Web Services' Systems Manager Parameter Store for Spring Boot's properties injection.


License
MIT

Documentation

Build Status MIT license Maven Central

Spring Boot Parameter Store Integration

The Spring Boot Parameter Store Integration is a tiny library used to integrate AWS Parameter Store in Spring Boot's powerful property injection. For example, it allows you to fetch a property directly using the @Value annotation. In fact, it simply adds a PropertySource with highest precedence to the existing ones (see Spring Boot's External Configuration).

Requirements

The library uses:

Those can be overriden in your pom.xml.

The library was tested and worked properly with:

Unleashing the Magic

For your pom.xml:

<dependency>
    <groupId>com.coveo</groupId>
    <artifactId>spring-boot-parameter-store-integration</artifactId>
    <version>1.1.0</version>
</dependency>

There are 3 ways to enable this lib after importing it in your pom.xml, pick yours:

  • Set awsParameterStorePropertySource.enabled to true (yml, properties, or anything here)
  • Add the profile awsParameterStorePropertySourceEnabled to your active profiles
  • Set awsParameterStorePropertySource.enabledProfiles with some custom profiles that should integrate the AWS Parameter Store using a comma-separated list such as MyProductionProfile,MyTestProfile
    Important: using other list injecting methods like a yaml list won't work because this property gets loaded too early in the boot process.

Using the lib:

Use a property that is prefixed with / somewhere such as

@Value("${/my/parameter/store/property}")
String value;

You might be wondering why use slashes (/)?

The AWS Parameter Store already uses this naming pattern to classify your properties as you would do with folders. Using this prefix to limit the number of calls to AWS at boot seemed natural. This means that properties not prefixed with / can't yet be fetched in the AWS Parameter Store using this lib.

AWS Client

The lib uses the DefaultAWSCredentialProviderChain and the DefaultAWSRegionProviderChain. This means that if your code is running on an EC2 instance that has access to a Parameter Store property and its associated KMS key, the library should be able to fetch it without any configuration.

If you need to use a custom endpoint for the AWS Simple Systems Management client, you can set the property awsParameterStoreSource.ssmClient.endpointConfiguration.endpoint. For more details, see the AWSClientBuilder.EndpointConfiguration class, which is used to configure the client. By default, the associated signing region is fetched from DefaultAWSRegionProviderChain, but if you need to specify a different one, you can use the property awsParameterStoreSource.ssmClient.endpointConfiguration.signingRegion. Note that this only sets the signingRegion for the endpoint and not the aws client region. Region configuration should be done using the providers available from the DefaultAWSRegionProviderChain.

Using Spring Boot's Placeholder Properties

Since naming properties with some / everywhere seems a bit awkward and not coherent with actual property keys, we suggest using placeholder properties. This way you can use AWS Parameter Store without modifying your current property naming scheme. Using nested properties makes things easier for multiple environments and simplifies property name changes in the Parameter Store without editing the code (using an environment variable).

So your yml could look like this:

my.super.duper.secret: defaultValue

And you would inject the Parameter Store key through an environment variable using a placeholder like this:

my.super.duper.secret: ${/my/parameter/store/secret}

When Spring Boot encounters your environment variable, it doesn't inject ${/my/parameter/store/secret} in your property my.super.duper.secret, but instead tries to load the property /my/parameter/store/secret from its property sources, and then hits the Parameter Store source because of the prefix /.

Halting the Boot to Prevent Production Incidents

The default behaviour of a PropertySource when it can't find a property is to return null, and then the PropertyResolver iterates on every other PropertySource to find a matching value. This is the default behaviour for this lib.

If you want to halt the boot when a property prefixed with / isn't found in the Parameter Store, just set awsParameterStorePropertySource.haltBoot to true in your properties. We personally use this to prevent injecting default properties in a production environment.

Spring Cloud

TL;DR: Define the enabling properties in the bootstrap properties (bootstrap.yml, bootstrap.properties, etc.)(see Unleashing the Magic).

Spring Cloud has a second application context named bootstrap that gets initialized before Spring Boot's normal application context. Since this lib uses an EnvironmentPostPrecessor to add the Parameter Store PropertySource, it gets triggered twice. Since you probably want it to be added on the bootstrap context, we highly recommend using the bootstrap properties to enable this lib. More details on this Stack Overflow Thread.

Contributing

Open an issue to report bugs or to request additional features. Pull requests are always welcome.

Enjoy 🍻

UPDATE: I wrote a blog post about this library on our technical blog.