This project provides various extensions to Micronaut for Amazon Web Services (AWS).

A base AWSClientConfiguration is provided which can be used as a base configuration class for any configuration that needs to configure an AWS SDK client.

For this project, you can find a list of releases (with release notes) here:

https://github.com/micronaut-projects/micronaut-aws/releases

Micronaut AWS 2.0.0 contains improvements to ease the creation of Alexa Skills with Micronaut:

Check the Alexa section to learn more.

See the section Breaking Changes to ease into the migration to Micronaut AWS 2.x

Micronaut is verified to run on Amazon Corretto.

To use the AWS SDK v1, add the following dependency:

When working with AWS SDK, you may need to provide a com.amazonaws.auth.AWSCredentialsProvider. To ease that this module provides a utility class: EnvironmentAWSCredentialsProvider

For example the following snippet show how you may configure a S3 Client if you set two environment variables:

Read about externalized Configuration with property sources in Micronaut.

To use the AWS SDK v2, add the following dependency:

By default, the AWS SDK v2 will pull transitively both the Netty (async) and Apache HTTP (sync) clients. If you wish to use a client based on the JVM’s lightweight URLConnection, you should configure it as explained below.

To use the URLConnection-based client, you should exclude the other clients from the classpath:

Then, you can configure it with the following configuration properties:

If you don’t exclude the other clients from the classpath, you still can configure which one is used by setting the following JVM system properties:

The Apache HTTP client can be configured with the following options:

The Netty client can be configured with the following options:

By default, AWS SDK v2 will attempt to find AWS credentials from the following places:

For more information, check the AWS documentation.

If you still want to specify the credentials via configuration, you can do so in the application configuration file:

By default, AWS SDK v2 will attempt to determine the AWS region in the following ways:

For more information, check the AWS documentation.

If you still want to specify the region via configuration, you can do so in the application configuration file:

You can override the endpoint of an AWS Service by setting aws.services.*.endpoint-override, for example, during testing.

For example, for AWS SQS, you can set aws.services.sqs.endpoint-override=https://localhost:1234.

To use an API Gateway Management Api client, add the following dependency:

Then, the following beans will be created:

And:

The HTTP client, credentials and region will be configured as per described in the SDK v2 documentation.

Micronaut provides a high-level, uniform object storage API that works across the major cloud providers: Micronaut Object Storage.

To get started, select the object-storage-aws feature in Micronaut Launch, or add the following dependency:

For more information, check the Micronaut Object Storage AWS support documentation.

If you still need the low-level AWS S3 client, add the following dependency:

Then, the following beans will be created:

And:

The HTTP client, credentials and region will be configured as per described in the SDK v2 documentation.

Additionally, this service accepts the following configuration properties:

To use a DynamoDb client, add the following dependency:

Then, the following beans will be created:

And:

The HTTP client, credentials and region will be configured as per described in the SDK v2 documentation.

To use a SES client, add the following dependency:

Then, the following beans will be created:

And:

The HTTP client, credentials and region will be configured as per described in the SDK v2 documentation.

To use a SNS client, add the following dependency:

Then, the following beans will be created:

And:

The HTTP client, credentials and region will be configured as per described in the SDK v2 documentation.

To use a SQS client, add the following dependency:

Then, the following beans will be created:

And:

The HTTP client, credentials and region will be configured as per described in the SDK v2 documentation.

To use an SSM client, add the following dependency:

Then, the following beans will be created:

And:

The HTTP client, credentials and region will be configured as per described in the SDK v2 documentation.

To use a AWS Secrets Manager client, add the following dependency:

Then, the following beans will be created:

And:

The HTTP client, credentials and region will be configured as per described in the SDK v2 documentation.

To use Service discovery, the AWS Java SDK for Amazon Route 53 Auto Naming module, add the following dependency:

Then, the following beans will be created:

And:

The HTTP client, credentials and region will be configured as per described in the SDK v2 documentation.

To use the Cloudwatch Logs, add the following dependency to your project:

Then, the following beans will be created:

And:

The HTTP client, credentials and region will be configured as per described in the SDK v2 documentation.

By default, Micronaut application will try to create the group and stream for you using AWS client. To disable this behavior you have to set the createGroupAndStream flag to false inside your appender. Default value for group name is your application name and for stream name is your hostname. If you want you can change them by setting value groupName for group name and streamName for stream name.

Edit a src/main/resources/logback.xml file and make it look like this:

You can customize your JsonLayout with additional parameters the are available on official docs of Logback’s JsonLayout.

The CloudWatchLoggingAppender supports blacklisting the loggers by specifying the logger name. That might come handy if you want to use level=DEBUG or level=TRACE for the root logger level.

If you are using the OpenTelemetry for tracing you can include traceId and spanId fields into your logs. First you have to add next dependency into your project:

Inside your src/main/resources/logback.xml you should add a new appender io.opentelemetry.instrumentation.logback.v1_0.OpenTelemetryAppender.

Since this appender is queuing up log messages and then writing them remotely, there are a number of situations which might result in log messages not getting remoted correctly. To address such scenarios you can configure the emergency appender to preserve those messages.

Inside your src/main/resources/logback.xml you should add a new appender, in the example it is STDOUT. Inside the CloudWatchLoggingAppender add appender-ref that points to the new crated appender.

When you have completed a setup, you can browse your logs on the Cloudwatch home. In the Log groups menu and choose the group name and stream name of your application. In the "Log events" section you should be able to see your service logs.

For advanced configuration options that are not suitable to provide via application.yml, you can declare a BeanCreatedEventListener bean that listens for builder bean creations, and apply any further customisation there:

Since the list of services offered by AWS is huge, you can write your own client support and leverage the foundation classes that support the services supported by Micronaut.

To do so, you would create a @Factory class that would get injected some other beans to do its job.

For example, to create a client for AWS Rekognition:

Amazon API Gateway, unless you use a custom domain, uses the following format:

https://{restapi-id}.execute-api.{region}.amazonaws.com/{stageName}

You can use StageResolver and its implementations HttpRequestStageResolver or APIGatewayProxyRequestEventStageResolver to resolve the stage name.

Moreover, you can use AmazonApiGatewayUtils to check whether a resolved host matches the above format.

To use this API add the following dependency

There are several ways to create Micronaut AWS Lambda functions.

In Micronaut Launch, you can select the feature aws-lambda for applications of type Application or Serverless Function. Those application types have their CLI equivalents commands.

To deploy a AWS Lambda function you have to:

The above decisions influence the type of Micronaut application you choose.

To deploy a Micronaut function to AWS Lambda you have to choose a AWS Lambda Runtime. For Micronaut functions, you select a Java 17 runtime or custom runtime. To deploy your Micronaut function as a GraalVM Native Image you need to select a custom runtime.

Depending on your application type and runtime, you need different dependencies:

micronaut-function-aws-api-proxy has a transitive dependency to micronaut-function-aws.

The previous set of artifacts have a group id of io.micronaut.aws.

Micronaut CLI or Launch will include the necessary dependencies when you select the aws-lambda feature or both aws-lambda and graalvm features.

AWS Lambda integrates with other AWS services to invoke functions. The Micronaut application type you select depends on the triggers you want to support. To respond to incoming HTTP requests (e.g. AWS Lambda Proxy integrations in API Gateway) you can choose either Application or Serverless Function. For other triggers, such as consuming events from a queue, or run on a schedule you will choose Serverless Function.

On the one hand, if you need to support a single endpoint a Serverless Function gives you a function with less code (which translates to a faster cold startup).

On the other hand, functions written as an application of type Application allows you to code with a more familiar paradigm - Classes annotated with @Controller. That it is possible because, through the micronaut-function-aws-api-proxy dependency, Micronaut integrates with the AWS Lambda Java Events project.

To smooth the developer experience when you use the micronaut-function-aws-api-proxy dependency, Micronaut AWS offers the micronaut-function-aws-api-proxy-test dependency.

Add it as a developmentOnly dependency so that it is used when you run the app locally:

and to the test classpath:

This dependency starts a Jetty server, allowing you to have the same developer experience (run the app while developing or test it with @MicronautTest) as when you use a runtime such as Netty.

Lambda Context is registered as a singleton each time the handler gets invoked. You can inject it by using:

If present in the Lambda Context, the following singletons are registered, and you can inject them:

AWS Lambda Function Handler

The aws-lambda-java-core library defines two interfaces for handler methods. When coding your functions with Micronaut you don’t implement those interfaces directly. Instead you extend or use its Micronaut equivalents:

For functions of type Application, use the handler:

To resolve that class you need to add the micronaut-function-aws-api-proxy dependency to your build.

For Serverless Functions the decision to use one MicronautRequestHandler or MicronautRequestStreamHandler depends on how you want to handle the input and output types.

To resolve those classes you need to add the micronaut-function-aws dependency to your build.

With MicronautRequestHandler, it is expected that you supply generic types with the input and the output types. If you wish to work with raw streams then subclass MicronautRequestStreamHandler instead.

You need to add a dependency to Micronaut Jackson Databind:

or a dependency to Micronaut Serialization

If you want to use Micronaut Serialization with AWS Lambda Java Events add the following dependency:

micronaut-aws-lambda-events-serde provides an implementation of com.amazonaws.services.lambda.runtime.CustomPojoSerializer which is loaded via SPI. This CustomPojoSerialization avoids your Micronaut function paying a double hit on performance when using a serialization library inside the Lambda function.

AWS Lambda runtime will reuse the instances of your handler classes but the Java Virtual Machine will be suspended between the invocation. Every call on a single instance of your handler will reuse the same application context. If you need to perform actions before the JVM gets suspended then you can create synchronous handler for AfterExecutionEvent event which is published right before the execution of the method handleRequest in MicronautRequestHandler and MicronautRequestStreamHandler is finished.

To subscribe to AfterExecutionEvent create a @Singleton class which implements ApplicationEventListener<AfterExecutionEvent>. Learn more about Context Events.

Instances of Lambda functions are automatically added as request concurrency increases. When a new instance handles its first request it has to start the JVM and load your code, this one time process is called a cold start. The request is then processed, and the instance stays alive to be reused for subsequent requests. Lambda instances can be replaced over time and there is no way to determine how long a Lambda instance will live for.

Lambda function executions have different phases (Initialization, Invocation…​).

During the initialization phase:

The intialization phase has access to more CPU, because of that Micronaut starts the application context and eagerly inits singletons during the intialization of the handler class.

GraalVM is a universal virtual machine which allows to compile Java programs to native executables.

The introduction of AWS Lambda custom runtimes enables cold startup improvements for Java applications running in AWS Lambda.

Micronaut’s dependency micronaut-function-aws-custom-runtime eases the creation of AWS Lambda Custom runtime to execute a Micronaut function.

The main API you will interact with is AbstractMicronautLambdaRuntime. An abstract class which you can extend to create your custom runtime mainClass. That class includes the necessary code to perform the Processing Tasks described in the Custom Runtime documentation.

For Lambda responding to HTTP triggers, Micronaut AWS ships with several implementations of AbstractMicronautLambdaRuntime:

You can configure the mainClass used in your runtime via the Gradle plugin:

or via the Maven Plugin:

When you generate a project with Micronaut CLI or Micronaut Launch with aws-lambda and graalvm features, the output includes the necessary files to generate a ZIP file to distribute your functions as a GraalVM Native Image executed from a AWS Lambda custom runtime.

Micronaut Framework needs an HTTP client to poll the Lambda Runtime when you deploy as a native executable. Add the following dependency to satisfy this requirement.

micronaut-function-aws adds SLF4J Mapping Diagnostic Context Key/Value pairs for:

You can use those MDC Keys in a logging pattern:

Override MicronautRequestHandler populateMappingDiagnosticContextValues or populateMappingDiagnosticContextWithXrayTraceId methods to adjust the functionality to your needs.

Check the step-by-step tutorials to get you started:

To test Lambda handlers with JUnit 5, use the MicronautLambdaTest annotation which will configure a suitable ApplicationContext for use in a Lambda environment. The following dependency is needed:

Testing subclasses of MicronautRequestHandler or MicronautRequestStreamHandler with this annotation requires both a no-arg and a one-arg constructor, the latter being used to inject the test application context:

Example usage:

The annotation supports the same options as @MicronautTest. Please note that regardless of whether or not you provide a custom builder, some Lambda-specific configuration will be set (e.g. eager initialization and active environments).

Use MicronautRequestStreamHandler in combination of a class annotated with @FunctionBean which implements one of the interfaces from the java.util.function package.

For example, you can have a @FunctionBean which logs the input event.

A single project can define multiple functions, however only a single function should be configured for execution by the application.

By default, it is resolved via the property micronaut.function.name. If not present, the function name present in the Lambda Context, the name of the function on the AWS Console, is used.

Alternatively, you can write a custom Handler which extends MicronautRequestStreamHandler and overrides MicronautRequestStreamHandler::resolveFunctionName(Environment)

Micronaut AWS provides support for invoking AWS Lambda functions within a Micronaut application context.

To use the features described in this section, you will need to have the micronaut-function-client-aws dependency on your classpath.

You can define multiple named functions under the aws.lambda.functions configuration. Each is configured by AWSInvokeRequestDefinition that allows setting any property on the underlying com.amazonaws.services.lambda.model.InvokeRequest.

For example, you invoke a function named AwsLambdaFunctionName, in the AWS Lambda console, with the following configuration:

You create an interface annotated with @FunctionClient to invoke the Lambda Function:

Alternatively, you can remove the @Named annotation and match the method name to the function bean name.

To configure credentials for invoking the function you can either define a ~/.aws/credentials file or use the application configuration file. Micronaut registers a EnvironmentAWSCredentialsProvider that resolves AWS credentials from the Micronaut Environment.

Read the following guides to learn more abut AWS Lambda:

The Micronaut’s aws-alexa module simplifies development of Alexa Skills with Java, Kotlin or Groovy.

Typically, the next step will be to provide an instance of AlexaSkillConfiguration. The easiest way to do that is to configure the skill id via configuration:

You have to provide your an implementation of Micronaut’s SkillBuilderProvider.

Micronaut’s alexa module provides by default StandardSkillBuilderProvider which creates an SDK instance using the Skills.standard builder. However, to use it, you need add the dependency:

For each AlexaSkillConfiguration bean, Micronaut uses the builder provided by [SkillBuilderProvider to create for you a bean of type AlexaSkill for you and wires up the beans of the following types:

To create the sample skill described in Amazon Documentation - Develop your first skill with Micronaut’s Alexa you will write the same LaunchRequestHandler, HelloWorldIntent, HelpIntent, CancelandStopHandler, FallbackIntentHandler, SessionEndedRequestHandler handlers.

You will do just one change, you will annotate those handlers with jakarta.inject.Singleton.

The micronaut-function-aws-alexa module includes support for building deploying an Alexa Skill as a Lambda Function.

As handler specify io.micronaut.function.aws.alexa.AlexaFunction. You don’t need to create a class which extends SkillStreamHandler, AlexaFunction takes care of adding request handlers interceptors etc.

Micronaut simplifies hosting a Custom Skill as a Web Service.

The micronaut-aws-webservice is a fork of Amazon Servlet module. It allow you to run your Alexa Skill backend logic in Micronaut applications deployed with a netty or servlet runtimes.

Just by including the dependency:

you get an POST endpoint at /alexa (the route is configurable via alexa.endpoint.path.

You can configure your Skill’s endpoint under Build/Endpoint in the Alexa developer console.

Micronaut Alexa ships with a Speech Systhesys Markup Language builder.

Micronaut’s eases the creation of Flash Briefing Skills.

Your application must expose an endpoint which returns a JSON Array of FlashBriefingItem

To resolve the Request Locale inject a bean of type HandlerInputLocaleResolver.

You can force a fixed locale or a custom default locale via configuration:

If the built-in methods do not meet your use case, create a bean of type HandlerInputLocaleResolver and set its order (through the getOrder method) relative to the existing resolvers.

Micronaut AWS supports distributed configuration via services such as AWS Secrets Manager and AWS System Manager Parameter Store.

You can create environment-specific configurations as well by including the environment name after an underscore _. For example if micronaut.application.name is set to helloworld, specifying configuration values under helloworld_test will be applied only to the test environment.

Note the trailing slash in the configuration names.

For example, if the configuration name /config/application_test/server.url is configured in AWS Parameter Store, any application connecting to that parameter store can retrieve the value using server.url. If the application has micronaut.application.name configured to be myapp, a value with the name /config/myapp_test/server.url overrides the value just for that application.

Read the following guides to learn more abut AWS distributed configuration with the Micronaut Framework:

To use AWS Secrets Manager as distributed configuration include the following dependency:

To enable distributed configuration, create a src/main/resources/bootstrap.yml file and enable the configuration client:

Example:

If you add micronaut.application.name: myapp to bootstrap.yml and you start your app in the dev Micronaut environment the secret shown in the following image is read and two properties micronaut.security.oauth2.clients.companyauthserver.client-id and micronaut.security.oauth2.clients.companyauthserver.client-secret are exposed to your application:

To avoid secret keys naming collision in the Micronaut application context, which is caused by the strict naming convention specified by some AWS services, add a configuration section to src/main/resources/bootstrap.yml. For example, if you would like to use multiple RDS instances, you can do it in the following way:

Note that secret-name is a name suffix of the secret configured in AWS Secret Manager. For example, to add rds_backup configuration for a production environment, add the rds_backup configuration entry to the src/main/resources/bootstrap.yml as shown in the example above. Also, create RDS secret in AWS Secret Manager with name /config/application_prod/rds_backup or /config/[APPLICATION_NAME]_prod/rds_backup. Note that prefix is a unique key prefix that is prepended to all keys that belong to a given secret.

To learn more about the Micronaut environments, go to Environments

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

If you set:

The following prefixes are searched:

If you set:

The following prefixes are searched:

By setting both:

If you set:

Only the following prefix is searched:

Micronaut supports configuration sharing via AWS System Manager Parameter Store. You need the following dependencies configured:

To enable distributed configuration a src/main/resources/bootstrap.yml configuration file must be created and configured to use Parameter Store:

See the configuration reference for all configuration options.

You can configure shared properties from the AWS Console → System Manager → Parameter Store.

Micronaut uses a hierarchy to read configuration values, and supports String, StringList, and SecureString types.

Each level of the tree can be composed of key=value pairs. For multiple key/value pairs, set the type to StringList.

For special secure information, such as keys or passwords, use the type SecureString. KMS will be automatically invoked when you add and retrieve values, and will decrypt them with the default key store for your account. If you set the configuration to not use secure strings, they will be returned to you encrypted and you must manually decrypt them.

You can find the source code of this project in this repository:

https://github.com/micronaut-projects/micronaut-aws

If you are looking for a higher-level API, check out Agorapulse’s AWS SDK for Micronaut.