https://github.com/vertx-howtos/knative-serving-howto
Deploying a Knative service powered by Vert.x
https://github.com/vertx-howtos/knative-serving-howto
howto knative knative-serving vertx
Last synced: about 1 year ago
JSON representation
Deploying a Knative service powered by Vert.x
- Host: GitHub
- URL: https://github.com/vertx-howtos/knative-serving-howto
- Owner: vertx-howtos
- License: apache-2.0
- Created: 2019-03-05T15:18:16.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2024-12-04T16:59:39.000Z (over 1 year ago)
- Last Synced: 2025-05-06T09:19:36.259Z (about 1 year ago)
- Topics: howto, knative, knative-serving, vertx
- Language: Kotlin
- Homepage:
- Size: 377 KB
- Stars: 3
- Watchers: 2
- Forks: 6
- Open Issues: 4
-
Metadata Files:
- Readme: README.adoc
- License: LICENSE
Awesome Lists containing this project
README
= Deploying a Knative service powered by Vert.x
:author: Julien Ponge
:page-permalink: /
:page-github: vertx-howtos/knative-serving-howto
This how-to shows you how to deploy a Vert.x-based https://cloud.google.com/knative/[Knative] service.
== What you will build
- You will write a service that accepts Asciidoc text, and produces an HTML rendering with Asciidoctor.
- This service will be written in Kotlin.
- A container image with the function will be created with https://github.com/GoogleContainerTools/jib[Jib].
- This service will be deployed with Knative/serving.
== What you need
- A text editor or IDE
- Java 11 higher
- Maven or Gradle
- Docker
- A working Kubernetes cluster with https://github.com/knative/serving[Knative/serving].
== What is a Knative service and why is Vert.x a good match?
Knative starts container images (3 by default) to respond to requests, and scales down to 0 after some delay without traffic.
A "function" served by Knative/serving is simply an HTTP service written in any language, and packaged as a container image.
Vert.x is ideal for writing Knative services on the JVM, because:
. Vert.x applications start very fast since there is no magic happening at run time,
. GraalVM can be used compilation to further reduce the startup and memory footprint (out of the scope of this how-to),
. Vert.x applications are resource-efficient and remain responsive even under heavy load,
. Vert.x offers a large ecosystem of reactive clients to other middlewares (databases, messaging, etc.),
. a _main_ method / function suffices to bootstrap a Vert.x application!
== Create a project
The code of this project contains Maven and Gradle build files that are functionally equivalent.
=== With Gradle
Here is the content of the `build.gradle.kts` file that you should be using:
[source,kotlin,role="collapsed"]
----
include::build.gradle.kts[]
----
<1> We need Kotlin, `vertx-web` and `asciidoctorj`.
<2> The Gradle application plugin allows us to run the application locally with the `run` command.
<3> Jib configuration to produce an image.
=== With Maven
Here is the content of the `pom.xml` file that you should be using:
[source,xml,role="collapsed"]
----
include::pom.xml[]
----
<1> We need Kotlin, `vertx-web` and `asciidoctorj`.
<2> Allows running with `mvn exec:java`.
<3> Jib configuration to produce an image.
== Writing the service
The service exposes an HTTP server.
Asciidoc is passed to the function through HTTP POST requests.
For each request, Asciidoctor is used to perform the conversion to HTML:
[source,kotlin]
----
include::src/main/kotlin/io/vertx/howtos/knative/serving/App.kt[]
----
<1> We create a Vert.x context.
<2> We configure a Asciidoctor render.
<3> We install an HTTP request body handler, so we can just process the whole body rather than manually assemble buffers.
<4> For each request, we render the HTML from the Asciidoc.
We could have written the Vert.x code as a verticle, but doing so in the `main` function reduces the boilerplate code since we would only be deploying a single verticle here anyway.
== Running the function locally
We can easily test that the service works:
. from your IDE, run the `main` function, or
. with Gradle: `./gradlew run` (Linux, macOS) or `gradle run` (Windows).
. with Maven: `mvn compile exec:java`.
You can then upload the content of an Asciidoc file, like the `README.adoc` file at the root of this repository.
With https://httpie.org/[HTTPie], you would run a command similar to:
[source,shell]
----
http POST :8080/ @README.adoc
----
== Preparing your cluster
You should go to the https://knative.dev/docs/install/[Knative documentation for installation instructions].
The commands in this how-to assume that you have installed https://knative.dev/docs/install/quickstart-install/[Knative using quickstart] and Minikube.
== Building your container image
The Jib plugin in your Gradle or Maven build will automatically assemble a container image with the correct entry point to run the application, and port 8080 being exposed.
The container image then has to be pushed to your favorite repository.
If you are using Minikube, you can directly build and tag the container image:
[source,shell]
----
eval $(minikube docker-env -p knative)
./gradlew jibDockerBuild # or mvn package jib:dockerBuild
----
Docker should then list the image:
[source,shell]
----
docker image ls
----
You should see something like:
----
REPOSITORY TAG IMAGE ID
(...)
dev.local/jponge/knative-vertx-asciidoctor latest 4ca7aafd590c
dev.local/jponge/knative-vertx-asciidoctor v1 4ca7aafd590c
(...)
----
== Describing a service for Knative
Here is the descriptor in file `service.yaml` for exposing our service with Knative/serving:
[source,yaml]
----
include::service.yaml[]
----
We can then apply the configuration and check that the service is available:
[source,shell]
----
kubectl apply -f service.yaml
----
You should see something like:
----
service.serving.knative.dev/knative-vertx-asciidoctor created
----
Then:
[source,shell]
----
kubectl get ksvc
----
You should see something like:
----
NAME URL LATESTCREATED LATESTREADY READY REASON
knative-vertx-asciidoctor http://knative-vertx-asciidoctor.default.10.101.169.49.sslip.io knative-vertx-asciidoctor-00001 knative-vertx-asciidoctor-00001 True
----
== Testing the service exposed by Knative
With Minikube, making a request to the function is similar to:
[source,shell]
----
http POST knative-vertx-asciidoctor.default.10.101.169.49.sslip.io @README.adoc
----
You should see HTML in the response.
[NOTE]
====
If your system is not able to resolve `sslip.io` names, extract the IP from the URL and try something this:
[source,shell]
----
http POST 10.101.169.49 'Host:knative-vertx-asciidoctor.default.10.101.169.49.sslip.io' @README.adoc
----
====
You should also see pods for your service:
[source,shell]
----
kubectl get pods
----
You should see something like:
----
NAME READY STATUS RESTARTS AGE
knative-vertx-asciidoctor-mlhwq-deployment-5cc999bdb7-jx2ff 3/3 Running 0 2m5s
----
After a while, you can check that the Knative auto-scaler has removed all pods:
[source,shell]
----
kubectl get pods
----
You should see something like:
----
No resources found.
----
Issue a new request, and see that new pods have been created again.
== Summary
- We wrote a Knative service with Vert.x and Kotlin that renders Asciidoc text to HTML.
- We built a container image.
- We deployed this service with Knative/serving.
== See also
- https://vertx.io/docs/vertx-web/java/[Vert.x web APIs]
- https://kubernetes.io/docs/setup/minikube/[Minikube]
- https://knative.dev/docs/[Knative documentation]
- https://knative.dev/docs/serving/[Knative serving]