Here is our second tutorial about Quarkus. Today we will learn how to create native executable applications with amazingly fast start up time. Next we will create a Container image that will be eventually deployed on the top of Openshift
If you have already had a look at our first tutorial Getting started with Quarkus, you could see that Quarkus's maven plugin included a goal to build native images:
<build>
<plugins>
<plugin>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-maven-plugin</artifactId>
<version>${quarkus.version}</version>
<executions>
<execution>
<goals>
<goal>native-image</goal>
</goals>
<configuration>
<enableHttpUrlHandler>true</enableHttpUrlHandler>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
In order to build native images we need to install GraalVM, which is a high-performance, embeddable, polyglot virtual machine for running applications written in JavaScript, Python, Ruby, R, JVM-based languages like Java, Scala, Kotlin, and LLVM-based languages such as C and C++.
GraalVM is available at: https://github.com/oracle/graal/releases
Download the latest stable release of GraalVM and unzip it in a folder of your likes. Within the graalvm-ce-linux-amd64-19.2.1.tar.gz you will find:
- A JVM
- A JavaScript engine & node.js runtime
- A LLVM engine
Now export the GRAALVM_HOME with the path where GraalVM was installed:
export GRAALVM_HOME=/path/to/graal
Next, we need the native-image tool which allows you to ahead-of-time compile Java code to a standalone executable. You can install the native-image tool as follows:
${GRAALVM_HOME}/bin/gu install native-image
We will now build the HelloWorld Quarkus application discussed in the first tutorial Getting started with Quarkus. Move to the root folder and build the native executable use the 'mvn verify -Pnative' command:
$ mvn verify -Pnative [INFO] ------------------------------------------------------- [INFO] T E S T S [INFO] ------------------------------------------------------- [INFO] Running com.sample.QuarkusEndpointTest 2019-03-25 18:36:49,921 INFO [io.qua.dep.QuarkusAugmentor] (main) Beginning quarkus augmentation 2019-03-25 18:36:50,501 INFO [io.qua.dep.QuarkusAugmentor] (main) Quarkus augmentation completed in 580ms 2019-03-25 18:36:50,812 INFO [io.quarkus] (main) Quarkus 0.11.0 started in 0.299s. Listening on: http://127.0.0.1:8081 2019-03-25 18:36:50,813 INFO [io.quarkus] (main) Installed features: [cdi, resteasy] [INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 2.077 s - in com.sample.QuarkusEndpointTest
Note: if you are getting this error "Basic header file missing ()" then it means that headers are not available on your system. You can install them using:
sudo apt-get install libz-dev
If you are using a Fedora/RHEL system, use instead:
sudo dnf install zlib-devel
Once that the native generation has been completed, check the target folder:
$ ls -al target drwxrwxr-x. 15 francesco francesco 4096 Mar 25 18:37 . drwxrwxr-x. 4 francesco francesco 4096 Mar 25 18:29 .. drwxrwxr-x. 4 francesco francesco 4096 Mar 24 20:13 classes drwxrwxr-x. 2 francesco francesco 4096 Mar 24 20:20 failsafe-reports drwxrwxr-x. 3 francesco francesco 4096 Mar 18 09:47 generated-sources drwxrwxr-x. 3 francesco francesco 4096 Mar 24 20:13 generated-test-sources -rw-rw-r--. 1 francesco francesco 5209 Mar 25 18:36 hello-quarkus-1.0-SNAPSHOT.jar -rwxrwxr-x. 1 francesco francesco 19740232 Mar 25 18:37 hello-quarkus-1.0-SNAPSHOT-runner -rw-r--r--. 1 francesco francesco 36337 Mar 25 18:36 hello-quarkus-1.0-SNAPSHOT-runner.jar
The native executable hello-quarkus-1.0-SNAPSHOT-runner, which is a minimal REST Service, is just 19MB in size. Let's run it:
./hello-quarkus-1.0-SNAPSHOT-runner 2019-03-25 18:39:51,473 INFO [io.quarkus] (main) Quarkus 0.11.0 started in 0.007s. Listening on: http://127.0.0.1:8080 2019-03-25 18:39:51,474 INFO [io.quarkus] (main) Installed features: [cdi, resteasy]
As you can see, in a few milliseconds the application will boot. Test it with:
$ curl http://localhost:8080/hello
Building Docker images from native executables
It is amazing how simple is to build a Docker image out of your native executable application. Quarkus's Maven plugin already arranged for you a Dockerfile in the project folder src/main/docker.
Here is the content of it:
FROM fabric8/java-alpine-openjdk8-jre ENV JAVA_OPTIONS="-Dquarkus.http.host=0.0.0.0 -Djava.util.logging.manager=org.jboss.logmanager.LogManager" ENV AB_ENABLED=jmx_exporter COPY target/lib/* /deployments/lib/ COPY target/*-runner.jar /deployments/app.jar ENTRYPOINT [ "/deployments/run-java.sh" ]
You can build the docker image "quarkus/hello-quarkus" as follows:
docker build -f src/main/docker/Dockerfile -t quarkus/hello-quarkus .
Now check that the image is available:
$ docker images REPOSITORY TAG IMAGE ID CREATED SIZE quarkus/hello-quarkus latest 761947bb9d9d 25 seconds ago 125 MB
It's time to run it, with:
$ docker run -i --rm -p 8080:8080 quarkus/hello-quarkus 2019-03-25 18:54:21,070 INFO [io.quarkus] (main) Quarkus 0.11.0 started in 0.002s. Listening on: http://[::]:8080 2019-03-25 18:54:21,070 INFO [io.quarkus] (main) Installed features: [cdi, resteasy]
You can test it with:
$ curl http://localhost:8080/hello
Deploying Quarkus applications on Openshift
Once that you have the Container image of your application, it's very simple to deploy it on Openshift or Kubernetes. To keep it as simple as possible, we will use Minishift as Openshift cluster. Start Minishift with:
$ ./minishift start
Create a sample project named "quarkus":
$ oc new-project quarkus Now using project "quarkus" on server "https://192.168.42.204:8443".
Next, create a new Binary build named "quarkus-quickstart":
$ oc new-build --binary --name=quarkus-quickstart -l app=quarkus-quickstart
* A Docker build using binary input will be created
* The resulting image will be pushed to image stream tag "quarkus-quickstart:latest"
* A binary build was created, use 'start-build --from-dir' to trigger a new build
--> Creating resources with label app=quarkus-quickstart ...
imagestream.image.openshift.io "quarkus-quickstart" created
buildconfig.build.openshift.io "quarkus-quickstart" created
--> Success
We need to set the dockerfilePath parameter in our build, with the location where the Dockerfile is:
$ oc patch bc/quarkus-quickstart -p '{"spec":{"strategy":{"dockerStrategy":{"dockerfilePath":"src/main/docker/Dockerfile"}}}}'
buildconfig.build.openshift.io/quarkus-quickstart patched
Now we can start the build operation, that will push the Quarkus application on Openshift:
$ oc start-build quarkus-quickstart --from-dir=. --follow Uploading directory "." as binary input for the build ... >build.build.openshift.io/quarkus-quickstart-1 started Receiving source from STDIN as archive ... Pulling image registry.fedoraproject.org/fedora-minimal ... Pulled 0/1 layers, 20% complete Pulled 1/1 layers, 100% complete Extracting Step 1/8 : FROM registry.fedoraproject.org/fedora-minimal ---> f0c38118c459 Step 2/8 : WORKDIR /work/ ---> 69b5e60840bc Removing intermediate container 86df47c2a9c2 Step 3/8 : COPY target/*-runner /work/application ---> 75695835b4fe Removing intermediate container 7cbd0029ae38 Step 4/8 : RUN chmod 775 /work ---> Running in edd7a212de68 ---> 0856df0e56c8 Removing intermediate container edd7a212de68 Step 5/8 : EXPOSE 8080 ---> Running in fde34fea6934 ---> eb6112ea782c Removing intermediate container fde34fea6934 Step 6/8 : CMD ./application -Dquarkus.http.host=0.0.0.0 ---> Running in a7c2b6d751f3 ---> 8140539071be Removing intermediate container a7c2b6d751f3 Step 7/8 : ENV "OPENSHIFT_BUILD_NAME" "quarkus-quickstart-1" "OPENSHIFT_BUILD_NAMESPACE" "quarkus" ---> Running in 06a6f92a98e5 ---> 1daf960db23d Removing intermediate container 06a6f92a98e5 Step 8/8 : LABEL "io.openshift.build.name" "quarkus-quickstart-1" "io.openshift.build.namespace" "quarkus" ---> Running in 1a4f712b5df5 ---> 07bd2b01cc12 Removing intermediate container 1a4f712b5df5 Successfully built 07bd2b01cc12 Pushing image 172.30.1.1:5000/quarkus/quarkus-quickstart:latest ... Pushed 2/4 layers, 52% complete Pushed 3/4 layers, 81% complete Pushed 4/4 layers, 100% complete Push successful
Now that the image "quarkus-quickstart:latest" is available in our local registry, you can add it as application with:
$ oc new-app --image-stream=quarkus-quickstart:latest
--> Found image 07bd2b0 (26 seconds old) in image stream "quarkus/quarkus-quickstart" under tag "latest" for "quarkus-quickstart:latest"
* This image will be deployed in deployment config "quarkus-quickstart"
* Port 8080/tcp will be load balanced by service "quarkus-quickstart"
* Other containers can access this service through the hostname "quarkus-quickstart"
* WARNING: Image "quarkus/quarkus-quickstart:latest" runs as the 'root' user which may not be permitted by your cluster administrator
--> Creating resources ...
deploymentconfig.apps.openshift.io "quarkus-quickstart" created
service "quarkus-quickstart" created
--> Success
Application is not exposed. You can expose services to the outside world by executing one or more of the commands below:
'oc expose svc/quarkus-quickstart'
Run 'oc status' to view your app.
Great! the application has been created. Finish the work, by exposing the Service through a Route:
$ oc expose service quarkus-quickstart route.route.openshift.io/quarkus-quickstart exposed
Testing the Openshift application
Last effort will be testing our application which now should be visible in the Web console:
Let's copy the route address from the shell:
$ oc get route NAME HOST/PORT PATH SERVICES PORT TERMINATION WILDCARD quarkus-quickstart quarkus-quickstart-quarkus.192.168.42.204.nip.io quarkus-quickstart 8080-tcp None
Now test it with:
$ curl http://quarkus-quickstart-quarkus.192.168.42.204.nip.io/hello
Conclusion
At the end of this brief journey through Quarkus applications, we have discovered how to build a simple application which can be compiled easily into native code. One major feature of Quarkus is the ability to create instantly Container images of your applications which can be deployed on Openshift or Kubernates.