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 GCN 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 and Amazon Web Services (AWS).

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 and/or Amazon Web Services cloud platforms.

Set up

Your Desktop

You have set up your desktop development environment with required (and optional) tools.

Set up

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

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 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
Click Generate Project. 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 Oracle Cloud Infrastructure

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 or using the Oracle Cloud Infrastructure CLI.

Update the Oracle Cloud Infrastructure configuration file (oci/src/main/resources/application-oraclecloud.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.

3. Configure the Project for Amazon Web Services

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

4. Run the Application

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

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

./gradlew :oci:run

./gradlew :aws:run

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

4.2. Download the Picture

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

4.3. Delete the Picture

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

5. Use VSCode Test Explorer to Test Your Code

Running tests for your GCN application is easy with VSCode Test Explorer.

VS Code Tests

6. 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, run the following command to build a native executable:

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

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

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

8. 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 and Amazon Web Services.

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 -pl aws

./gradlew aws:dockerPush

This will push an Amazon Web Services container image to a 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

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.

9. 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 multi-service application like MuShop for Micronaut. For more information, view:

Introduction to Micronaut MuShop