Get Started

The Graal Development Kit for Micronaut (GDK) is a build of a curated set of Micronaut^® framework modules and their required libraries for building portable cloud native microservices that take full advantage of powerful cloud platform services and that can be compiled ahead-of-time by GraalVM Native Image. The GDK also provides project creation utilities for application development and deployment.

The modules provide platform-independent support for a set of core cloud services including object storage, secret management, streaming, tracing, and more. This guide walks you through the steps to successfully create, build, test and deploy a cloud native application to Oracle Cloud Infrastructure, Amazon Web Services (AWS), Google Cloud Platform (GCP), and Microsoft Azure.

We showcase these capabilities by building a Java application which accesses cloud object storage in a vendor-independent way.

Prerequisites

Java Framework Experience

You have a basic understanding of Java microservice frameworks such as Micronaut, Helidon, Spring Boot, or Quarkus.

About Micronaut

Cloud Accounts

You have created account(s) for Oracle Cloud Infrastructure, Amazon Web Services, Google Cloud Platform, and/or Microsoft Azure.

Set up

Your Desktop

You have set up your desktop development environment with required tools.

Set up

This guide describes how to create a Micronaut application that runs natively on Oracle Cloud Infrastructure, Amazon Web Services, Google Cloud Platform, and Microsoft Azure without any source code changes. The application demonstrates how to store and retrieve user profile pictures in Oracle Cloud Infrastructure, Amazon Web Services, Google Cloud Platform, and Microsoft Azure using the Micronaut Object Storage API.

Windows platform: The GDK guides are compatible with Gradle only. Maven support is coming soon.

1. Create the Application

Create an application using the GDK Launcher.

Open the GDK Launcher.
Create a new project using the following selections. (Alternatively, use these shortcuts for Maven or Gradle.)
- Project Type: Application (Default)
- Project Name: GettingStarted
- Base Package: com.example (Default)
- Clouds: OCI, AWS, GCP, and Azure
- Language: Java (Default)
- Build Tool: Gradle (Groovy) or Maven
- Test Framework: JUnit (Default)
- Java Version: 25 (Default)
- Micronaut Version: (Default)
- Cloud Services: Object Storage
- Features: GraalVM Native Image (Default)
- Sample Code: Yes (Default)
Click Generate Project and then click Download Zip. The GDK Launcher creates an application with the default package com.example in a directory named GettingStarted. The application ZIP file will be downloaded to your default downloads directory. Unzip it, open it in your code editor, and proceed to the next steps.

The GDK Launcher creates the following sample source code files that use the Micronaut Object Storage API to create, read, and delete objects in the major cloud providers:

an interface describing the endpoints of the "profile pictures" microservice:
lib/src/main/java/com/example/ProfilePicturesApi.java
an implementation with the required dependencies:
lib/src/main/java/com/example/ProfilePicturesController.java

2. Configure the Project

For this section, you will need an Oracle Cloud Infrastructure account and an Object Storage bucket created already. See how to create an Object Storage bucket from the Oracle Cloud Console.

Add the Oracle Cloud Infrastructure configuration file (oci/src/main/resources/application.properties) with the name of the bucket and its namespace:

micronaut.object-storage.oracle-cloud.default.namespace=OBJECT_STORAGE_NAMESPACE
micronaut.object-storage.oracle-cloud.default.bucket=OBJECT_STORAGE_BUCKET

Replace OBJECT_STORAGE_BUCKET with the name of your bucket and OBJECT_STORAGE_NAMESPACE with your namespace.

For this section, you will need an Amazon Web Services account and an S3 bucket already created. See the Amazon S3 Object Storage Guide for assistance.

Update the Amazon Web Services configuration file (aws/src/main/resources/application.properties) with the name of the bucket:

micronaut.object-storage.aws.default.bucket=OBJECT_STORAGE_BUCKET

Replace OBJECT_STORAGE_BUCKET with the name of your bucket.

For this section, you will need a Google Cloud Platform account and an Object Storage bucket created already. See GCP Object Storage Guide for assistance.

Update the Google Cloud Platform configuration file (gcp/src/main/resources/application.properties) with the name of the bucket:

micronaut.object-storage.gcp.default.bucket=OBJECT_STORAGE_BUCKET

Replace OBJECT_STORAGE_BUCKET with the name of your bucket.

For this section, you will need a Microsoft Azure account and a Storage Container created already. See Azure Object Storage Guide for assistance.

Update the Azure configuration file (azure/src/main/resources/application.properties) with the name of the container and the storage endpoint:

micronaut.object-storage.azure.default.container=STORAGE_CONTAINER
micronaut.object-storage.azure.default.endpoint=STORAGE_ENDPOINT

Replace STORAGE_CONTAINER with the name of your container and STORAGE_ENDPOINT with your storage endpoint (it will look like https://gdkstorage.blob.core.windows.net/).

3. Run the Application

./mvnw install -pl lib -am && ./mvnw mn:run -pl oci

./mvnw install -pl lib -am && ./mvnw mn:run -pl aws

./mvnw install -pl lib -am && ./mvnw mn:run -pl gcp

./mvnw install -pl lib -am && ./mvnw mn:run -pl azure

./gradlew :oci:run

./gradlew :aws:run

./gradlew :gcp:run

./gradlew :azure:run

3.1. Upload the Picture

 curl -F "fileUpload=@my_picture.jpg" http://localhost:8080/pictures/avatar

The image type has to be of a JPEG format.

3.2. Download the Picture

curl http://localhost:8080/pictures/avatar -J -o profile.jpg

3.3. Delete the Picture

curl -X "DELETE" http://localhost:8080/pictures/avatar

4. Build a Native Executable of Your Application with GraalVM

To build a native executable of your application, you should install GraalVM with Native Image. Once your local environment is setup, use the command below to build a native executable. Then run it and test it as above.

./mvnw install -pl lib -am && ./mvnw clean package -pl oci -Dpackaging=native-image

The native executable is created in the oci/target/ directory and can be run with the following command:

oci/target/GettingStarted-oci

./mvnw install -pl lib -am && ./mvnw package -pl aws -Dpackaging=native-image

The native executable is created in the aws/target/ directory and can be run with the following command:

aws/target/GettingStarted-aws

./mvnw install -pl lib -am && ./mvnw package -pl gcp -Dpackaging=native-image

The native executable is created in the gcp/target/ directory and can be run with the following command:

gcp/target/GettingStarted-gcp

./mvnw install -pl lib -am && ./mvnw package -pl azure -Dpackaging=native-image

The native executable is created in the azure/target/ directory and can be run with the following command:

azure/target/GettingStarted-azure

./gradlew :oci:nativeCompile

The native executable is created in the oci/build/native/nativeCompile/ directory and can be run with the following command:

oci/build/native/nativeCompile/GettingStarted-oci

./gradlew :aws:nativeCompile

The native executable is created in the aws/build/native/nativeCompile/ directory and can be run with the following command:

aws/build/native/nativeCompile/GettingStarted-aws

./gradlew :gcp:nativeCompile

The native executable is created in the gcp/build/native/nativeCompile/ directory and can be run with the following command:

gcp/build/native/nativeCompile/GettingStarted-gcp

./gradlew :azure:nativeCompile

The native executable is created in the azure/build/native/nativeCompile/ directory and can be run with the following command:

azure/build/native/nativeCompile/GettingStarted-azure

5. Deploy the Application as a Container on the Cloud

Next you can create a container with Native Image version of the application and deploy it on a Kubernetes cluster on Oracle Cloud Infrastructure, Amazon Web Services, Google Cloud Platform, and Microsoft Azure.

5.1. Oracle Cloud Infrastructure

A complete lab on how to deploy an application to Oracle Cloud Infrastructure Container Engine for Kubernetes is available.

5.2. AWS

With your AWS account ready and access to EKS configured, simply invoke this command:

./mvnw deploy -Dpackaging=docker-native -pl aws

./mvnw deploy -Dpackaging=docker-native -pl aws

./mvnw deploy -Dpackaging=docker-native -pl aws

./mvnw deploy -Dpackaging=docker-native -pl aws

./gradlew aws:dockerPushNative

./gradlew aws:dockerPushNative

./gradlew aws:dockerPushNative

./gradlew aws:dockerPushNative

This will build a native executable, package it as a container image and push the container image to the correct Amazon Web Services container registry. When you setup your Kubernetes deployment for Amazon Web Services EKS, simply invoke the command:

kubectl apply -f deployment.yml

5.3. GCP

With your GCP account ready and access to GKE configured, simply invoke this command:

./mvnw deploy -Dpackaging=docker-native -pl gcp

./mvnw deploy -Dpackaging=docker-native -pl gcp

./mvnw deploy -Dpackaging=docker-native -pl gcp

./mvnw deploy -Dpackaging=docker-native -pl gcp

./gradlew gcp:dockerPushNative

./gradlew gcp:dockerPushNative

./gradlew gcp:dockerPushNative

./gradlew gcp:dockerPushNative

This will build a native executable, package it as a container image and push the container image to the correct Google container registry. When you setup your Kubernetes deployment for GKE, simply invoke the command:

kubectl apply -f deployment.yml

5.4. Azure

A complete guide on how to deploy an application to Azure Kubernetes Engine is available.

With your Azure account ready and access to AKS configured, simply invoke this command:

./mvnw deploy -Dpackaging=docker-native -pl azure

./mvnw deploy -Dpackaging=docker-native -pl azure

./mvnw deploy -Dpackaging=docker-native -pl azure

./mvnw deploy -Dpackaging=docker-native -pl azure

./gradlew azure:dockerPushNative

./gradlew azure:dockerPushNative

./gradlew azure:dockerPushNative

./gradlew azure:dockerPushNative

This will build a native executable, package it as a container image and push the container image to the correct Azure container registry. When you setup your Kubernetes deployment for AKS, simply invoke the command:

kubectl apply -f deployment.yml

Next Steps

Learn

The Micronaut Fundamentals course covers core concepts of the Micronaut framework, application creation, HTTP development, and OpenAPI integration. It also introduces data validation, error handling, GraalVM native images, and deployment with the Graal Development Kit (GDK).

Micronaut Fundamentals Course

Explore

The GDK provides easy step-by-step guides, and companion sample applications, for the developer to learn how to use a specific cloud service (such as Micronaut Data). Browse the GDK site for list of modules and guides to learn more.

Modules

Guides

Create

Build a multi-service application like MuShop for Micronaut. For more information, view:

Introduction to Micronaut MuShop