Deployment & Fault Tolerance

Deploying a Knative service powered by Vert.x

This how-to shows you how to deploy a Vert.x-based 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 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 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:

import org.jetbrains.kotlin.gradle.tasks.KotlinCompile

plugins {
  id("org.jetbrains.kotlin.jvm").version("2.0.21")
  id("com.google.cloud.tools.jib") version "3.4.4"
  application
}

repositories {
  jcenter()
}

dependencies {  (1)
  implementation("org.jetbrains.kotlin:kotlin-stdlib")
  implementation("io.vertx:vertx-web:5.0.0.CR2")
  implementation("org.asciidoctor:asciidoctorj:2.5.13")
}

application {  (2)
  mainClass = "io.vertx.howtos.knative.serving.AppKt"
}

tasks.withType<KotlinCompile> {
  kotlinOptions.jvmTarget = "11"
}

jib {  (3)
  to {
    image = "dev.local/jponge/knative-vertx-asciidoctor"
    tags = setOf("v1")
  }
  container {
    mainClass = "io.vertx.howtos.knative.serving.AppKt"
    ports = listOf("8080")
  }
}

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:

<?xml version="1.0" encoding="UTF-8"?>
<project
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"
  xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

  <modelVersion>4.0.0</modelVersion>

  <groupId>io.vertx.howtos</groupId>
  <artifactId>knative-serving-howto</artifactId>
  <version>1.0-SNAPSHOT</version>

  <properties>
    <kotlin.version>2.0.21</kotlin.version>
    <kotlin.compiler.jvmTarget>11</kotlin.compiler.jvmTarget>
    <main.class>io.vertx.howtos.knative.serving.AppKt</main.class>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  </properties>

  <dependencies>  (1)
    <dependency>
      <groupId>org.jetbrains.kotlin</groupId>
      <artifactId>kotlin-stdlib</artifactId>
      <version>${kotlin.version}</version>
    </dependency>
    <dependency>
      <groupId>io.vertx</groupId>
      <artifactId>vertx-web</artifactId>
      <version>5.0.0.CR2</version>
    </dependency>
    <dependency>
      <groupId>org.asciidoctor</groupId>
      <artifactId>asciidoctorj</artifactId>
      <version>2.5.13</version>
    </dependency>
  </dependencies>

  <build>
    <sourceDirectory>${project.basedir}/src/main/kotlin</sourceDirectory>
    <plugins>
      <plugin>
        <artifactId>kotlin-maven-plugin</artifactId>
        <groupId>org.jetbrains.kotlin</groupId>
        <version>${kotlin.version}</version>
        <executions>
          <execution>
            <id>compile</id>
            <phase>compile</phase>
            <goals>
              <goal>compile</goal>
            </goals>
          </execution>
          <execution>
            <id>test-compile</id>
            <phase>test-compile</phase>
            <goals>
              <goal>test-compile</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
      <plugin>
        <groupId>org.codehaus.mojo</groupId>  (2)
        <artifactId>exec-maven-plugin</artifactId>
        <version>3.5.0</version>
        <executions>
          <execution>
            <goals>
              <goal>java</goal>
            </goals>
          </execution>
        </executions>
        <configuration>
          <mainClass>${main.class}</mainClass>
        </configuration>
      </plugin>
      <plugin>
        <groupId>com.google.cloud.tools</groupId> (3)
        <artifactId>jib-maven-plugin</artifactId>
        <version>3.4.4</version>
        <configuration>
          <to>
            <image>dev.local/jponge/knative-vertx-asciidoctor</image>
            <tags>
              <tag>v1</tag>
            </tags>
          </to>
          <container>
            <mainClass>${main.class}</mainClass>
            <ports>
              <port>8080</port>
            </ports>
          </container>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>

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:

package io.vertx.howtos.knative.serving

import io.vertx.core.Vertx
import io.vertx.ext.web.Router
import io.vertx.ext.web.handler.BodyHandler
import org.asciidoctor.Asciidoctor
import org.asciidoctor.Options
import org.asciidoctor.SafeMode

fun main() {
  val vertx = Vertx.vertx() (1)

  val asciidoctor = Asciidoctor.Factory.create()  (2)
  val options = Options.builder()
    .safe(SafeMode.SAFE)
    .backend("html5")
    .standalone(true)
    .build()

  val router = Router.router(vertx)
  router.route().handler(BodyHandler.create())  (3)

  router.post().handler { ctx ->  (4)
    ctx.response()
      .putHeader("Content-Type", "text/html")
      .end(asciidoctor.convert(ctx.body().asString(), options))
  }

  vertx.createHttpServer()
    .requestHandler(router)
    .listen(8080)
    .await()
}

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 HTTPie, you would run a command similar to:

http POST :8080/ @README.adoc

Preparing your cluster

You should go to the Knative documentation for installation instructions.

The commands in this how-to assume that you have installed 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:

eval $(minikube docker-env -p knative)
./gradlew jibDockerBuild    # or mvn package jib:dockerBuild

Docker should then list the image:

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:

apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: knative-vertx-asciidoctor
  namespace: default
spec:
  template:
    spec:
      containers:
        - image: dev.local/jponge/knative-vertx-asciidoctor:v1

We can then apply the configuration and check that the service is available:

kubectl apply -f service.yaml

You should see something like:

service.serving.knative.dev/knative-vertx-asciidoctor created

Then:

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:

http POST knative-vertx-asciidoctor.default.10.101.169.49.sslip.io @README.adoc

You should see HTML in the response.

If your system is not able to resolve sslip.io names, extract the IP from the URL and try something this:

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:

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:

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.