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

We showcase these capabilities by building a Java application which accesses OCI Object Storage as well as Amazon S3 Object Storage.

Prerequisites

Java Frameworks

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

Learn

Cloud accounts

You have created account(s) for the OCI and/or AWS 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 (OCI) and Amazon Web Services (AWS) without any source code changes. The application demonstrates how to store and retrieve user profile pictures in OCI and AWS 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

For this section, you will need an OCI account and an Object Storage bucket created already. See how to create an Object Storage bucket from the OCI Console or using the OCI CLI.

Update the OCI configuration file (oci/src/main/resources/application-oraclecloud.yml) with details of the bucket name and namespace:

micronaut:
      object-storage:
        oracle-cloud:
          default:
            bucket: '${OBJECT_STORAGE_BUCKET}'
            namespace: '${OBJECT_STORAGE_NAMESPACE}'

Replace '${OBJECT_STORAGE_BUCKET}' with your bucket and '${OBJECT_STORAGE_NAMESPACE}' with your namespace.

3. Configure the Project for Amazon Web Service

For this section, you will need an AWS account and a S3 bucket created already. See: Amazon S3 Object Storage Guide for assistance.

Update the AWS configuration file (aws/src/main/resources/application-ec2.yml) with details of the bucket name:

 micronaut:
      object-storage:
        aws:
          default:
            bucket: '${OBJECT_STORAGE_BUCKET}'

Replace '${OBJECT_STORAGE_BUCKET}' with 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 DevOps Service

Thanks to the GCN extension, you can leverage the OCI 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 OCI and AWS.

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 AWS container image to a correct AWS container registry. When you setup your Kubernetes deployment for AWS EKS, simply invoke the command:

kubectl apply -f deployment.yml

OCI

You can also install the GCN extension and use OCI DevOps Resources to leverage Oracle Cloud DevOps service and 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 OCI, make source code changes, push them into the OCI Git repository, and then trigger the build of a container image with your native executable or a container image with JVM using the predefined OCI Build Pipelines.

Learn more about this is in the Setting OCI 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