{"id":20796747,"url":"https://github.com/vertx-howtos/knative-serving-howto","last_synced_at":"2025-05-06T09:19:42.351Z","repository":{"id":37263300,"uuid":"173970366","full_name":"vertx-howtos/knative-serving-howto","owner":"vertx-howtos","description":"Deploying a Knative service powered by Vert.x","archived":false,"fork":false,"pushed_at":"2024-12-04T16:59:39.000Z","size":386,"stargazers_count":3,"open_issues_count":4,"forks_count":6,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-05-06T09:19:36.259Z","etag":null,"topics":["howto","knative","knative-serving","vertx"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vertx-howtos.png","metadata":{"files":{"readme":"README.adoc","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-03-05T15:18:16.000Z","updated_at":"2024-12-04T17:01:47.000Z","dependencies_parsed_at":"2022-08-24T15:51:31.507Z","dependency_job_id":null,"html_url":"https://github.com/vertx-howtos/knative-serving-howto","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vertx-howtos%2Fknative-serving-howto","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vertx-howtos%2Fknative-serving-howto/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vertx-howtos%2Fknative-serving-howto/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vertx-howtos%2Fknative-serving-howto/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vertx-howtos","download_url":"https://codeload.github.com/vertx-howtos/knative-serving-howto/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252655008,"owners_count":21783374,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["howto","knative","knative-serving","vertx"],"created_at":"2024-11-17T16:28:55.850Z","updated_at":"2025-05-06T09:19:42.344Z","avatar_url":"https://github.com/vertx-howtos.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"= Deploying a Knative service powered by Vert.x\n:author: Julien Ponge \u003cjulien.ponge@gmail.com\u003e\n:page-permalink: /\n:page-github: vertx-howtos/knative-serving-howto\n\nThis how-to shows you how to deploy a Vert.x-based https://cloud.google.com/knative/[Knative] service.\n\n== What you will build\n\n- You will write a service that accepts Asciidoc text, and produces an HTML rendering with Asciidoctor.\n- This service will be written in Kotlin.\n- A container image with the function will be created with https://github.com/GoogleContainerTools/jib[Jib].\n- This service will be deployed with Knative/serving.\n\n== What you need\n\n- A text editor or IDE\n- Java 11 higher\n- Maven or Gradle\n- Docker\n- A working Kubernetes cluster with https://github.com/knative/serving[Knative/serving].\n\n== What is a Knative service and why is Vert.x a good match?\n\nKnative starts container images (3 by default) to respond to requests, and scales down to 0 after some delay without traffic.\nA \"function\" served by Knative/serving is simply an HTTP service written in any language, and packaged as a container image.\n\nVert.x is ideal for writing Knative services on the JVM, because:\n\n. Vert.x applications start very fast since there is no magic happening at run time,\n. GraalVM can be used compilation to further reduce the startup and memory footprint (out of the scope of this how-to),\n. Vert.x applications are resource-efficient and remain responsive even under heavy load,\n. Vert.x offers a large ecosystem of reactive clients to other middlewares (databases, messaging, etc.),\n. a _main_ method / function suffices to bootstrap a Vert.x application!\n\n== Create a project\n\nThe code of this project contains Maven and Gradle build files that are functionally equivalent.\n\n=== With Gradle\n\nHere is the content of the `build.gradle.kts` file that you should be using:\n\n[source,kotlin,role=\"collapsed\"]\n----\ninclude::build.gradle.kts[]\n----\n\u003c1\u003e We need Kotlin, `vertx-web` and `asciidoctorj`.\n\u003c2\u003e The Gradle application plugin allows us to run the application locally with the `run` command.\n\u003c3\u003e Jib configuration to produce an image.\n\n=== With Maven\n\nHere is the content of the `pom.xml` file that you should be using:\n\n[source,xml,role=\"collapsed\"]\n----\ninclude::pom.xml[]\n----\n\u003c1\u003e We need Kotlin, `vertx-web` and `asciidoctorj`.\n\u003c2\u003e Allows running with `mvn exec:java`.\n\u003c3\u003e Jib configuration to produce an image.\n\n== Writing the service\n\nThe service exposes an HTTP server.\nAsciidoc is passed to the function through HTTP POST requests.\nFor each request, Asciidoctor is used to perform the conversion to HTML:\n\n[source,kotlin]\n----\ninclude::src/main/kotlin/io/vertx/howtos/knative/serving/App.kt[]\n----\n\u003c1\u003e We create a Vert.x context.\n\u003c2\u003e We configure a Asciidoctor render.\n\u003c3\u003e We install an HTTP request body handler, so we can just process the whole body rather than manually assemble buffers.\n\u003c4\u003e For each request, we render the HTML from the Asciidoc.\n\nWe 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.\n\n== Running the function locally\n\nWe can easily test that the service works:\n\n. from your IDE, run the `main` function, or\n. with Gradle: `./gradlew run` (Linux, macOS) or `gradle run` (Windows).\n. with Maven: `mvn compile exec:java`.\n\nYou can then upload the content of an Asciidoc file, like the `README.adoc` file at the root of this repository.\nWith https://httpie.org/[HTTPie], you would run a command similar to:\n\n[source,shell]\n----\nhttp POST :8080/ @README.adoc\n----\n\n== Preparing your cluster\n\nYou should go to the https://knative.dev/docs/install/[Knative documentation for installation instructions].\n\nThe commands in this how-to assume that you have installed https://knative.dev/docs/install/quickstart-install/[Knative using quickstart] and Minikube.\n\n== Building your container image\n\nThe 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.\nThe container image then has to be pushed to your favorite repository.\n\nIf you are using Minikube, you can directly build and tag the container image:\n\n[source,shell]\n----\neval $(minikube docker-env -p knative)\n./gradlew jibDockerBuild    # or mvn package jib:dockerBuild\n----\n\nDocker should then list the image:\n\n[source,shell]\n----\ndocker image ls\n----\n\nYou should see something like:\n\n----\nREPOSITORY                                    TAG       IMAGE ID\n(...)\ndev.local/jponge/knative-vertx-asciidoctor    latest    4ca7aafd590c\ndev.local/jponge/knative-vertx-asciidoctor    v1        4ca7aafd590c\n(...)\n----\n\n== Describing a service for Knative\n\nHere is the descriptor in file `service.yaml` for exposing our service with Knative/serving:\n\n[source,yaml]\n----\ninclude::service.yaml[]\n----\n\nWe can then apply the configuration and check that the service is available:\n\n[source,shell]\n----\nkubectl apply -f service.yaml\n----\n\nYou should see something like:\n\n----\nservice.serving.knative.dev/knative-vertx-asciidoctor created\n----\n\nThen:\n\n[source,shell]\n----\nkubectl get ksvc\n----\n\nYou should see something like:\n\n----\nNAME                        URL                                                               LATESTCREATED                     LATESTREADY                       READY   REASON\nknative-vertx-asciidoctor   http://knative-vertx-asciidoctor.default.10.101.169.49.sslip.io   knative-vertx-asciidoctor-00001   knative-vertx-asciidoctor-00001   True\n----\n\n== Testing the service exposed by Knative\n\nWith Minikube, making a request to the function is similar to:\n\n[source,shell]\n----\nhttp POST knative-vertx-asciidoctor.default.10.101.169.49.sslip.io @README.adoc\n----\n\nYou should see HTML in the response.\n\n[NOTE]\n====\nIf your system is not able to resolve `sslip.io` names, extract the IP from the URL and try something this:\n\n[source,shell]\n----\nhttp POST 10.101.169.49 'Host:knative-vertx-asciidoctor.default.10.101.169.49.sslip.io' @README.adoc\n----\n====\n\nYou should also see pods for your service:\n\n[source,shell]\n----\nkubectl get pods\n----\n\nYou should see something like:\n\n----\nNAME                                                          READY   STATUS    RESTARTS   AGE\nknative-vertx-asciidoctor-mlhwq-deployment-5cc999bdb7-jx2ff   3/3     Running   0          2m5s\n----\n\nAfter a while, you can check that the Knative auto-scaler has removed all pods:\n\n[source,shell]\n----\nkubectl get pods\n----\n\nYou should see something like:\n\n----\nNo resources found.\n----\n\nIssue a new request, and see that new pods have been created again.\n\n== Summary\n\n- We wrote a Knative service with Vert.x and Kotlin that renders Asciidoc text to HTML.\n- We built a container image.\n- We deployed this service with Knative/serving.\n\n== See also\n\n- https://vertx.io/docs/vertx-web/java/[Vert.x web APIs]\n- https://kubernetes.io/docs/setup/minikube/[Minikube]\n- https://knative.dev/docs/[Knative documentation]\n- https://knative.dev/docs/serving/[Knative serving]\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvertx-howtos%2Fknative-serving-howto","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvertx-howtos%2Fknative-serving-howto","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvertx-howtos%2Fknative-serving-howto/lists"}