Table of Contents

Distributed Configuration with AWS Secrets Manager and the Micronaut Framework

Learn how to load your secrets from AWS Secrets Manager in your Micronaut application

Authors: Sergio del Amo

Micronaut Version: 4.6.3

1. Getting Started

In this guide, we will create a Micronaut application written in Kotlin.

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=maven --lang=kotlin
If you don’t specify the --build argument, Gradle with the Kotlin DSL 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.

5. OAuth 2.0 Dependency

To use OAuth 2.0 integration, add the following dependency:

pom.xml
<dependency>
    <groupId>io.micronaut.security</groupId>
    <artifactId>micronaut-security-oauth2</artifactId>
    <scope>compile</scope>
</dependency>

6. Micronaut AWS Secrets Manager Dependency

Add the following dependencies:

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

7. Distributed Configuration

7.1. 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.

7.2. 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

7.3. 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

7.4. 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.

8. Create Secret

OAuth 2.0 clients have a client id and secret property. We will save both in AWS Secrets Manager.

Create a Secret in AWS Secrets Manager

aws secrets manager

9. Controller

Create a controller which exposes the value read from AWS Secrets Manager.

src/main/kotlin/example/micronaut/ClientIdController.kt
package example.micronaut

import io.micronaut.security.annotation.Secured
import io.micronaut.security.oauth2.configuration.OauthClientConfiguration
import io.micronaut.security.rules.SecurityRule
import jakarta.inject.Named
import io.micronaut.http.annotation.Get
import io.micronaut.http.MediaType
import io.micronaut.http.annotation.Produces
import io.micronaut.http.annotation.Controller

@Controller
class ClientIdController(
    @Named("companyauthserver") private val oauthClientConfiguration: OauthClientConfiguration
) {

    @Secured(SecurityRule.IS_ANONYMOUS)
    @Produces(MediaType.TEXT_PLAIN)
    @Get
    fun index(): String {
        return oauthClientConfiguration.clientId
    }
}

10. Logs

Add the following configuration to src/main/resources/logback.xml to get a more verbose output when the application starts up:

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

11. Running the Application

To run the application, use the ./mvnw mn:run command, which starts the application on port 8080.

You should see traces such as:

11:02:01.342 [main] INFO  i.m.context.DefaultBeanContext - Reading bootstrap environment configuration
11:02:01.668 [main] TRACE i.m.a.d.AwsDistributedConfigurationClient - application name: micronautguide
11:02:02.798 [main] TRACE i.m.a.d.AwsDistributedConfigurationClient - evaluating 2 keys
11:02:02.798 [main] TRACE i.m.a.d.AwsDistributedConfigurationClient - adding property micronaut.security.oauth2.clients.companyauthserver.client-id from prefix /config/micronautguide/
11:02:02.798 [main] TRACE i.m.a.d.AwsDistributedConfigurationClient - adding property micronaut.security.oauth2.clients.companyauthserver.client-secret from prefix /config/micronautguide/
11:02:02.798 [main] DEBUG i.m.a.d.AwsDistributedConfigurationClient - Property source awssecretsmanager with #2 items
11:02:02.798 [main] TRACE i.m.a.d.AwsDistributedConfigurationClient - property micronaut.security.oauth2.clients.companyauthserver.client-id resolved
11:02:02.798 [main] TRACE i.m.a.d.AwsDistributedConfigurationClient - property micronaut.security.oauth2.clients.companyauthserver.client-secret resolved
11:02:02.847 [main] INFO  i.m.d.c.c.DistributedPropertySourceLocator - Resolved 1 configuration sources from client: compositeConfigurationClient(AWS Secrets Manager)
curl localhost:8080
XXXX

12. Generate a Micronaut Application Native Executable with GraalVM

We will use GraalVM, an advanced JDK with ahead-of-time Native Image compilation, to generate a native executable of this Micronaut application.

Compiling Micronaut applications ahead of time with GraalVM significantly improves startup time and reduces the memory footprint of JVM-based applications.

Only Java and Kotlin projects support using GraalVM’s native-image tool. Groovy relies heavily on reflection, which is only partially supported by GraalVM.

12.1. GraalVM Installation

The easiest way to install GraalVM on Linux or Mac is to use SDKMan.io.

Java 21
sdk install java 21.0.5-graal

For installation on Windows, or for a manual installation on Linux or Mac, see the GraalVM Getting Started documentation.

The previous command installs Oracle GraalVM, which is free to use in production and free to redistribute, at no cost, under the GraalVM Free Terms and Conditions.

Alternatively, you can use the GraalVM Community Edition:

Java 21
sdk install java 21.0.2-graalce

12.2. Native Executable Generation

To generate a native executable using Maven, run:

./mvnw package -Dpackaging=native-image

The native executable is created in the target directory and can be run with target/micronautguide.

It is possible to customize the name of the native executable or pass additional build arguments using the Maven plugin for GraalVM Native Image building. Declare the plugin as following:

pom.xml
<plugin>
    <groupId>org.graalvm.buildtools</groupId>
    <artifactId>native-maven-plugin</artifactId>
    <version>0.10.3</version>
    <configuration>
        <!-- <1> -->
        <imageName>mn-graalvm-application</imageName> (1)
        <buildArgs>
              <!-- <2> -->
          <buildArg>-Ob</buildArg>
        </buildArgs>
    </configuration>
</plugin>
1 The native executable name will now be mn-graalvm-application.
2 It is possible to pass extra build arguments to native-image. For example, -Ob enables the quick build mode. 
curl localhost:8080
XXXX

13. Next Steps

Explore more features with Micronaut Guides.

Learn more about Micronaut AWS Secrets Manager integration.

Read about AWS Secrets Manager

14. Help with the Micronaut Framework

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

15. 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…​).