These tutorials target Micronaut Framework 3. Read, Guides for Micronaut Framework 4.

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: 3.9.2

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:

  • Some time on your hands

  • A decent text editor or IDE

  • JDK 1.8 or greater installed with JAVA_HOME configured appropriately

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=maven --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.

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.MediaType;
import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Get;
import io.micronaut.http.annotation.Produces;

import java.math.BigDecimal;

@Controller (1)
public class VatController {

    private final Vat vat;

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

    @Produces(MediaType.TEXT_PLAIN) (3)
    @Get("/vat")  (4)
    public BigDecimal index() {
        return 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 By default, a Micronaut response uses application/json as Content-Type. We are returning a String, not a JSON object, so we set it to text/plain.
4 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 javax.validation.constraints.NotBlank;
import javax.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 jakarta.inject.Inject;
import java.math.BigDecimal;

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)
public class VatControllerTest {

    @Inject
    @Client("/")
    public HttpClient httpClient;

    @Test
    void vatExposesTheValueAddedTaxRate() {
        assertEquals(httpClient.toBlocking().retrieve("/vat", BigDecimal.class), new BigDecimal("7.7"));
    }
}
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:

pom.xml
<dependency>
    <groupId>io.micronaut.aws</groupId>
    <artifactId>micronaut-aws-parameter-store</artifactId>
    <scope>compile</scope>
</dependency>

4.5. Enable Distributed Configuration

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

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

4.6. Clean up Application Configuration

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

src/main/resources/application.yml
- micronaut:
-  application:
-    name: micronautguide

4.7. Disable Distributed Configuration for Test

To disable distributed configuration for tests, create a bootstrap-test.yml file:

src/test/resources/bootstrap-test.yml
micronaut:
  config-client:
    enabled: false

4.8. Enable Distributed Configuration with AWS Parameter Store

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

src/main/resources/bootstrap.yml
aws:
  client:
    system-manager:
      parameterstore:
        enabled: true (1)
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.9. 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 ./mvnw mn: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.yml
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 ./mvnw mn: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.yml
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

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.