Get Started

Graal Cloud Native (GCN) 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. GCN also provides project creation utilities and VS Code extensions 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), and Google Cloud Platform (GCP).

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, and/or Google Cloud Platform.

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, and Google Cloud Platform without any source code changes. The application demonstrates how to store and retrieve user profile pictures in Oracle Cloud Infrastructure, Amazon Web Services and Google Cloud Platform Object Storage using the Micronaut Object Storage API.

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

1. Create the Application

Create an application using the GCN Launcher.

Open the GCN 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: AWS, GCP and OCI
- Language: Java (Default)
- Build Tool: Gradle (Groovy) or Maven
- Test Framework: JUnit (Default)
- Java Version: 17 (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 GCN 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 Visual Studio (VS) Code, and proceed to the next steps.

The GCN 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.

Update 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 a S3 bucket created already. See 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 a 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.

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

./gradlew :oci:run

./gradlew :aws:run

./gradlew :gcp: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 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/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/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/gcp

./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/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/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/gcp

5. Use VS Code and Oracle Cloud Infrastructure DevOps Service

Thanks to the GCN extension, you can leverage the Oracle Cloud Infrastructure DevOps Resources in VS Code to build a native executable of your application on the cloud instead of locally.

6. 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 and Google Cloud Platform.

6.1 Oracle Cloud Infrastructure

You can install the Visual Studio Code extensions for GCN, covered in Installing Graal Cloud Native Tools, and use OCI DevOps Resources to use the Oracle Cloud Infrastructure DevOps service to deploy your application to a pre-created Kubernetes cluster from within VS Code.

OCI Services in VS Code

Using the OCI DevOps Resources in VS Code, you can easily deploy a Java application to Oracle Cloud Infrastructure, make source code changes, push them into the Oracle Cloud Infrastructure Git repository, and then trigger the build of a container image with your native executable or a container image with JVM using the predefined Oracle Cloud Infrastructure Build Pipelines.

Learn more about this is in the Setting Oracle Cloud Infrastructure DevOps Build and Development Pipeline in VS Code guide.

6.2 AWS

A complete guide on how to deploy an application to a Kubernetes cluster in AWS EKS is available.

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

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

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

6.3 GCP

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

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

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

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

7. Developing the Application in VS Code

Develop Java applications in VS Code with Graal Cloud Native support. It offers help in the form of relevant code completion suggestions when editing GCN specific configuration files.

VS Code Hints

Java language support speeds up development of Java code with hints, etc.

VS Code Quick Fix

When developing database applications, the GCN tooling provides advanced database related code completion for find… () methods:

VS Code Completion

It offers the SQL code completion in @Query annotations among others, and so on.

VS SQL Code Completion

Next Steps

Explore

GCN 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 GCN site for list of modules and guides to learn more.

Modules

Guides

Create

Build a multiservice application like MuShop for Micronaut. For more information, view:

Introduction to Micronaut MuShop