Table of Contents

Micronaut AWS Parameter Store

Learn how to use AWS Parameter for Configuration Discovery in a Micronaut application.

Authors: Pavol Gressa, Sergio del Amo

Micronaut Version: 4.4.0

1. Getting Started

In this guide, you will use AWS Parameter Store in a Micronaut Application to drive configuration.

2. What you will need

To complete this guide, you will need the following:

3. Solution

We recommend that you follow the instructions in the next sections and create the application step by step. However, you can go right to the completed example.

4. Writing the Application

Create an application using the Micronaut Command Line Interface or with Micronaut Launch.

mn create-app example.micronaut.micronautguide --build=gradle --lang=java
If you don’t specify the --build argument, Gradle is used as the build tool.
If you don’t specify the --lang argument, Java is used as the language.
If you don’t specify the --test argument, JUnit is used for Java and Kotlin, and Spock is used for Groovy.

The previous command creates a Micronaut application with the default package example.micronaut in a directory named micronautguide.

Setup IntelliJ IDEA to develop Micronaut Applications.

4.1. Controller

First, create an interface to encapsulate the Value-added Tax rate of a country.

src/main/java/example/micronaut/Vat.java
package example.micronaut;

import io.micronaut.core.annotation.NonNull;

import java.math.BigDecimal;

public interface Vat {

    @NonNull
    String getCountry();

    @NonNull
    BigDecimal getRate();
}

Create a GET endpoint /vat. It returns the Value-added Tax rate configured in our application.

src/main/java/example/micronaut/VatController.java
package example.micronaut;

import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Get;

import java.math.BigDecimal;
import java.util.Collections;
import java.util.Map;

@Controller (1)
public class VatController {

    private final Vat vat;

    public VatController(Vat vat) {  (2)
        this.vat = vat;
    }

    @Get("/vat")  (3)
    public Map<String, BigDecimal> index() {
        return Collections.singletonMap("rate", vat.getRate());
    }
}
1 The class is defined as a controller with the @Controller annotation mapped to the path /.
2 Use constructor injection to inject a bean of type Vat.
3 The @Get annotation maps the index method to an HTTP GET request on /vat.

4.2. Configuration

src/main/java/example/micronaut/VatConfiguration.java
package example.micronaut;

import io.micronaut.context.annotation.ConfigurationProperties;
import io.micronaut.core.annotation.NonNull;

import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.NotNull;
import java.math.BigDecimal;

@ConfigurationProperties("vat") (1)
public class VatConfiguration implements Vat { (2)

    @NonNull
    @NotNull
    private BigDecimal rate;

    @NotBlank
    @NotNull
    private String country;

    @Override
    @NonNull
    public BigDecimal getRate() {
        return rate;
    }

    public void setRate(@NonNull BigDecimal rate) {
        this.rate = rate;
    }

    @Override
    public String getCountry() {
        return country;
    }

    public void setCountry(String country) {
        this.country = country;
    }
}
1 The @ConfigurationProperties annotation takes the configuration prefix.
2 By implementing the interface, we can inject a bean of type Vat in the previous Controller’s constructor.

4.3. Test

Write a test which verifies a GET /vat endpoint returns the value set via configuration.

src/test/java/example/micronaut/VatControllerTest.java
package example.micronaut;

import io.micronaut.http.client.HttpClient;
import io.micronaut.http.client.annotation.Client;
import io.micronaut.test.extensions.junit5.annotation.MicronautTest;
import org.junit.jupiter.api.Test;
import io.micronaut.context.annotation.Property;

import static org.junit.jupiter.api.Assertions.assertEquals;

@MicronautTest (1)
@Property(name = "vat.country", value = "Switzerland") (2)
@Property(name = "vat.rate", value = "7.7") (2)
class VatControllerTest {

    @Test
    void vatExposesTheValueAddedTaxRate(@Client("/") HttpClient httpClient) {
        assertEquals("{\"rate\":7.7}", httpClient.toBlocking().retrieve("/vat"));
    }
}
1 Annotate the class with @MicronautTest so the Micronaut framework will initialize the application context and the embedded server. More info.
2 Annotate the class with @Property to supply configuration to the test.

4.4. Dependency

To use AWS Parameter Store to drive configuration add the following dependency:

build.gradle
implementation("io.micronaut.aws:micronaut-aws-parameter-store")

4.5. Enable Distributed Configuration

Create a bootstrap.properties file in the resources directory to enable distributed configuration. Add the following:

src/main/resources/bootstrap.properties
(1)
micronaut.application.name=micronautguide
(2)
micronaut.config-client.enabled=true
1 Set the application name in bootstrap.properties instead of application.properties so that it is available when reading configuration from distributed sources. properties
2 Set micronaut.config-client.enabled=true which is used to read and resolve configuration from distributed sources.

4.6. Clean up Application Configuration

If application.properties sets micronaut.application.name, remove it. You moved it to bootstrap.properties.

src/main/resources/application.properties
micronaut.application.name=micronautguide

4.7. Disable Distributed Configuration for Test

You can disable distributed configuration in a test by annotating a test with:

@Property(name = "micronaut.config-client.enabled", value = StringUtils.FALSE)
@MicronautTest

4.8. Tune Distributed Configuration Startup

Add the following configuration to bootstrap.properties:

src/main/resources/bootstrap.properties
aws.distributed-configuration.search-active-environments=false
aws.distributed-configuration.search-common-application=false

If your application has the following active environments ec2, cloud, and lambda. The following configuration prefixes are searched:

  • /config/micronautguide_ec2/

  • /config/micronautguide_cloud/

  • /config/micronautguide_lambda/

  • /config/micronautguide/

  • /config/application_ec2/

  • /config/application_cloud/

  • /config/application_lambda/

  • /config/application/

If you set:

aws.distributed-configuration.search-active-environments=false

The following prefixes are searched:

  • /config/micronautguide/

  • /config/application/

If you set:

aws.distributed-configuration.search-common-application=false

The following prefixes are searched:

  • /config/micronautguide_ec2/

  • /config/micronautguide_cloud/

  • /config/micronautguide_lambda/

  • /config/micronautguide/

By setting both:

aws.distributed-configuration.search-active-environments=false
aws.distributed-configuration.search-common-application=false

Only the following prefix is searched:

  • /config/micronautguide/

Reducing the number of prefixes reduces the application’s startup.

4.9. Enable Distributed Configuration with AWS Parameter Store

Add the following configuration to enable distributed configuration with AWS Parameter Store:

src/main/resources/bootstrap.properties
(1)
aws.client.system-manager.parameterstore.enabled=true
1 With aws.client.system-manager.parameterstore.enabled enable distributed configuration with AWS Parameter Store.
micronaut.application.name name will be part of the parameter name in AWS Parameter Store.

4.10. Logging

Add loggers to get a more verbose output:

...
    <logger name="io.micronaut.discovery" level="TRACE"/>
    <logger name="io.micronaut.aws" level="TRACE"/>
</configuration>

5. Populate Configuration at AWS Parameter Store

You can use the AWS CLI or the AWS Console to populate your configuration.

5.1. Set Parameters via AWS Console

Visit AWS Parameter Store service.

Create two parameters:

Create Country Parameter

Create Rate Parameter

Set the environment to use ec2, the programmatic access and region:

export MICRONAUT_ENVIRONMENTS=ec2
export AWS_ACCESS_KEY_ID=xxx
export AWS_SECRET_ACCESS_KEY=xxx
export AWS_REGION=us-east-1

To run the application, use the ./gradlew run command, which starts the application on port 8080.

You will get an output such as:

06:41:44.364 [main] INFO  i.m.context.env.DefaultEnvironment - Established active environments: [ec2]
06:41:44.377 [main] INFO  i.m.context.env.DefaultEnvironment - Established active environments: [ec2]
06:41:44.489 [main] INFO  i.m.context.DefaultBeanContext - Reading Startup environment from bootstrap-test.properties
06:41:46.425 [main] DEBUG i.m.d.c.c.DistributedPropertySourceLocator - Resolving configuration sources from client: compositeConfigurationClient(AWS Parameter Store)
06:41:47.811 [main] TRACE i.m.d.a.p.AWSParameterStoreConfigClient - parameterBasePath=/config/application no parameters found
06:41:47.813 [main] TRACE i.m.d.a.p.AWSParameterStoreConfigClient - Retrieving parameters by path /config/application, pagination requested: false
06:41:47.961 [main] TRACE i.m.d.a.p.AWSParameterStoreConfigClient - parameterBasePath=/config/application no parameters found
06:41:47.961 [main] TRACE i.m.d.a.p.AWSParameterStoreConfigClient - parameterBasePath=/config/application no parameters found
06:41:48.084 [main] TRACE i.m.d.a.p.AWSParameterStoreConfigClient - parameterBasePath=/config/micronautguide no parameters found
06:41:48.085 [main] TRACE i.m.d.a.p.AWSParameterStoreConfigClient - Retrieving parameters by path /config/micronautguide, pagination requested: false
06:41:48.222 [main] TRACE i.m.d.a.p.AWSParameterStoreConfigClient - parameterBasePath=/config/micronautguide no parameters found
06:41:48.224 [main] TRACE i.m.d.a.p.AWSParameterStoreConfigClient - Converted {vat.rate=21, vat.country=Spain}
06:41:48.224 [main] TRACE i.m.d.a.p.AWSParameterStoreConfigClient - param found: parameterBasePath=/config/micronautguide parameter=vat.rate
06:41:48.224 [main] TRACE i.m.d.a.p.AWSParameterStoreConfigClient - param found: parameterBasePath=/config/micronautguide parameter=vat.country
06:41:48.359 [main] TRACE i.m.d.a.p.AWSParameterStoreConfigClient - parameterBasePath=/config/application_ec2 no parameters found
06:41:48.360 [main] TRACE i.m.d.a.p.AWSParameterStoreConfigClient - Retrieving parameters by path /config/application_ec2, pagination requested: false
06:41:48.485 [main] TRACE i.m.d.a.p.AWSParameterStoreConfigClient - parameterBasePath=/config/application_ec2 no parameters found
06:41:48.485 [main] TRACE i.m.d.a.p.AWSParameterStoreConfigClient - parameterBasePath=/config/application_ec2 no parameters found
06:41:48.607 [main] TRACE i.m.d.a.p.AWSParameterStoreConfigClient - parameterBasePath=/config/micronautguide_ec2 no parameters found
06:41:48.607 [main] TRACE i.m.d.a.p.AWSParameterStoreConfigClient - Retrieving parameters by path /config/micronautguide_ec2, pagination requested: false
06:41:48.732 [main] TRACE i.m.d.a.p.AWSParameterStoreConfigClient - parameterBasePath=/config/micronautguide_ec2 no parameters found
06:41:48.733 [main] TRACE i.m.d.a.p.AWSParameterStoreConfigClient - parameterBasePath=/config/micronautguide_ec2 no parameters found
06:41:48.733 [main] TRACE i.m.d.a.p.AWSParameterStoreConfigClient - source=micronautguide got priority=-98
06:41:48.734 [main] INFO  i.m.d.c.c.DistributedPropertySourceLocator - Resolved 1 configuration sources from client: compositeConfigurationClient(AWS Parameter Store)
06:41:49.083 [main] INFO  io.micronaut.runtime.Micronaut - Startup completed in 4874ms. Server Running: http://localhost:8080

You should be able to execute this curl request and see 21 as the output:

curl -i localhost:8080/vat

5.2. Set Parameters via AWS CLI

Install AWS CLI.

Once you configure the CLI a region and user AWS access ID and secret key is configured.

Run the following commands to

aws ssm put-parameter --name /config/micronautguide/vat/country --value=Spain --type String
aws ssm put-parameter --name /config/micronautguide/vat/rate --value=21.0 --type String

Set the environment to use ec2.

export MICRONAUT_ENVIRONMENTS=ec2

The AWS region and programmatic access set via the CLI will be used.

To run the application, use the ./gradlew run command, which starts the application on port 8080.

You will get an output such as:

06:41:44.364 [main] INFO  i.m.context.env.DefaultEnvironment - Established active environments: [ec2]
06:41:44.377 [main] INFO  i.m.context.env.DefaultEnvironment - Established active environments: [ec2]
06:41:44.489 [main] INFO  i.m.context.DefaultBeanContext - Reading Startup environment from bootstrap-test.properties
06:41:46.425 [main] DEBUG i.m.d.c.c.DistributedPropertySourceLocator - Resolving configuration sources from client: compositeConfigurationClient(AWS Parameter Store)
06:41:47.811 [main] TRACE i.m.d.a.p.AWSParameterStoreConfigClient - parameterBasePath=/config/application no parameters found
06:41:47.813 [main] TRACE i.m.d.a.p.AWSParameterStoreConfigClient - Retrieving parameters by path /config/application, pagination requested: false
06:41:47.961 [main] TRACE i.m.d.a.p.AWSParameterStoreConfigClient - parameterBasePath=/config/application no parameters found
06:41:47.961 [main] TRACE i.m.d.a.p.AWSParameterStoreConfigClient - parameterBasePath=/config/application no parameters found
06:41:48.084 [main] TRACE i.m.d.a.p.AWSParameterStoreConfigClient - parameterBasePath=/config/micronautguide no parameters found
06:41:48.085 [main] TRACE i.m.d.a.p.AWSParameterStoreConfigClient - Retrieving parameters by path /config/micronautguide, pagination requested: false
06:41:48.222 [main] TRACE i.m.d.a.p.AWSParameterStoreConfigClient - parameterBasePath=/config/micronautguide no parameters found
06:41:48.224 [main] TRACE i.m.d.a.p.AWSParameterStoreConfigClient - Converted {vat.rate=21, vat.country=Spain}
06:41:48.224 [main] TRACE i.m.d.a.p.AWSParameterStoreConfigClient - param found: parameterBasePath=/config/micronautguide parameter=vat.rate
06:41:48.224 [main] TRACE i.m.d.a.p.AWSParameterStoreConfigClient - param found: parameterBasePath=/config/micronautguide parameter=vat.country
06:41:48.359 [main] TRACE i.m.d.a.p.AWSParameterStoreConfigClient - parameterBasePath=/config/application_ec2 no parameters found
06:41:48.360 [main] TRACE i.m.d.a.p.AWSParameterStoreConfigClient - Retrieving parameters by path /config/application_ec2, pagination requested: false
06:41:48.485 [main] TRACE i.m.d.a.p.AWSParameterStoreConfigClient - parameterBasePath=/config/application_ec2 no parameters found
06:41:48.485 [main] TRACE i.m.d.a.p.AWSParameterStoreConfigClient - parameterBasePath=/config/application_ec2 no parameters found
06:41:48.607 [main] TRACE i.m.d.a.p.AWSParameterStoreConfigClient - parameterBasePath=/config/micronautguide_ec2 no parameters found
06:41:48.607 [main] TRACE i.m.d.a.p.AWSParameterStoreConfigClient - Retrieving parameters by path /config/micronautguide_ec2, pagination requested: false
06:41:48.732 [main] TRACE i.m.d.a.p.AWSParameterStoreConfigClient - parameterBasePath=/config/micronautguide_ec2 no parameters found
06:41:48.733 [main] TRACE i.m.d.a.p.AWSParameterStoreConfigClient - parameterBasePath=/config/micronautguide_ec2 no parameters found
06:41:48.733 [main] TRACE i.m.d.a.p.AWSParameterStoreConfigClient - source=micronautguide got priority=-98
06:41:48.734 [main] INFO  i.m.d.c.c.DistributedPropertySourceLocator - Resolved 1 configuration sources from client: compositeConfigurationClient(AWS Parameter Store)
06:41:49.083 [main] INFO  io.micronaut.runtime.Micronaut - Startup completed in 4874ms. Server Running: http://localhost:8080

You should be able to execute this curl request and see 21 as the output:

curl -i localhost:8080/vat

5.3. Leverage environments

AWS Parameter Store is specially powerful in combination with Micronaut environments. Imagine we deploy our application also for Switzerland. We can have an environment named ch and load different configuration based on the environment. Create two parameters:

aws ssm put-parameter --name /config/micronautguide_ch/vat/country --value=Switzerland --type String
aws ssm put-parameter --name /config/micronautguide_ch/vat/rate --value=7.7 --type String

Enable search for active environments:

aws.distributed-configuration.search-active-environments=true

Set the environment to use ec2 and ch.

export MICRONAUT_ENVIRONMENTS=ec2,ch

Run the application, and you should be able to execute this curl request and see 7.7 as the output:

curl -i localhost:8080/vat

6. Next steps

Read about Micronaut AWS Parameter Store integration.

Read about AWS System Manager Parameter Store

7. Help with the Micronaut Framework

The Micronaut Foundation sponsored the creation of this Guide. A variety of consulting and support services are available.

8. License

All guides are released with an Apache license 2.0 license for the code and a Creative Commons Attribution 4.0 license for the writing and media (images…​).