diff --git a/docs/src/main/asciidoc/kubernetes.adoc b/docs/src/main/asciidoc/kubernetes.adoc index 392f8a2d2e0d4e..86ecb62b08ae5c 100644 --- a/docs/src/main/asciidoc/kubernetes.adoc +++ b/docs/src/main/asciidoc/kubernetes.adoc @@ -3,7 +3,7 @@ This guide is maintained in the main Quarkus repository and pull requests should be submitted there: https://github.com/quarkusio/quarkus/tree/master/docs/src/main/asciidoc //// -= Quarkus - Generating Kubernetes resources += Quarkus - Kubernetes extension include::./attributes.adoc[] @@ -387,6 +387,8 @@ If you need to generate resources for both platforms (vanilla Kubernetes and Ope quarkus.kubernetes.deployment-target=kubernetes, openshift ---- +Note: In latest versions of Quarkus a wrapper extension of link:openshift[Openshift] is provided. If you use it, there is no need to explicitly set this property. + The OpenShift resources can be customized in a similar approach with Kubernetes. .Openshift diff --git a/docs/src/main/asciidoc/openshift.adoc b/docs/src/main/asciidoc/openshift.adoc new file mode 100644 index 00000000000000..2264a1b49f7929 --- /dev/null +++ b/docs/src/main/asciidoc/openshift.adoc @@ -0,0 +1,176 @@ +//// +This guide is maintained in the main Quarkus repository +and pull requests should be submitted there: +https://github.com/quarkusio/quarkus/tree/master/docs/src/main/asciidoc +//// += Quarkus - Openshift extension + +include::./attributes.adoc[] + +This guide covers generating and deploying Openshift resources based on sane default and user supplied configuration. + + +== Prerequisites + +To complete this guide, you need: + +* roughly 5 minutes +* an IDE +* JDK 1.8+ installed with `JAVA_HOME` configured appropriately +* Apache Maven 3.5.3+ +* access to an Openshift or cluster (Minishift is a viable options) + +== Creating the Maven project + +First, we need a new project that contains the Openshift extension. This can be done using the following command: + +[source, subs=attributes+] +---- +mvn io.quarkus:quarkus-maven-plugin:{quarkus-version}:create \ + -DprojectGroupId=org.acme \ + -DprojectArtifactId=openshift-quickstart \ + -DclassName="org.acme.rest.GreetingResource" \ + -Dpath="/greeting" \ + -Dextensions="openshift" + +cd openshift-quickstart +---- + +=== Openshift + +Quarkus offers the ability to automatically generate Openshift resources based on sane defaults and user supplied configuration. +The Openshift extension is actually a wrapper extension that brings together the link:kubernetes[kubernetes] and link:container-image-s2i[container-image-s2i] +extensions with sensible defaults so that its easier for the user to get started with Quarkus on Openshift. + +When we added the `openshift` extension to the command line invocation above, the following dependency was added to the `pom.xml` + +[source,xml] +---- + + io.quarkus + quarkus-openshift + +---- + +By adding this dependency, we now have the ability to configure the Openshift resource generation and application using the usual `application.properties` approach that Quarkus provides. +The configuration items that are available can be found in: `io.quarkus.kubernetes.deployment.OpenshiftConfig` class. +Furthermore, the items provided by `io.quarkus.deployment.ApplicationConfig` affect the Openshift resources. + +=== Building + +Building is handled by the link:container-image#s2i[container-image-s2i] extension. To trigger a build: + +[source, subs=attributes+] +---- +mvn clean package -Dquarkus.container-image.build=true +---- + +The command above will trigger an s2i binary build. + +=== Deploying + +To trigger a deployment: + +[source, subs=attributes+] +---- +mvn clean package -Dquarkus.kubernetes.deploy=true +---- + +The command above will trigger a container image build and will apply the generated Openshift resources, right after. +The generated resources are using Openshift's `DeploymentConfig` that is configured to automatically trigger a redeployment when a change in the `ImageStream` is noticed. +In other words, any container image build after the inital deployment will automatically trigger redeployment, without the need to delete, update or re-apply the generated resources. + +=== Customizing + +All available customization options are available in the link:kubenretes#openshift[Openshift configuration options]. + +Some examples are provided in the sections below: + +==== Labels + +To add a label in the generated resources: + +[source] +---- +quarkus.openshift.labels.foo=bar +---- + +==== Annotations + +To add an annotation in the generated resources: + +[source] +---- +quarkus.openshift.annotations.foo=bar +---- + +==== Environment variables + +To add an annotation in the generated resources: + +[source] +---- +quarkus.openshift.env-vars.my-env-var.value=foobar +---- + +The command above will add `MY_ENV_VAR=foobar` as an environment variable. +Please, notice that the key `my-env-var` will be converted to uppercase and dashes will be replaced by underscores resulting in `MY_ENV_VAR`. + +You may also noticed that in contrast to labels, and annotations for environment variables you don't just use a key=value approach. +That is because for environment variables there are additonal options rather than just value. + +===== Environment variables from Secret + +To add all key value pairs of a `Secret` as envrionment variables: + +[source] +---- +quarkus.openshift.env-vars.my-env-var.secret=my-secret +---- + +===== Environment variables from ConfigMap + +To add all key value pairs of a `ConfigMap` as envrionment variables: + +[source] +---- +quarkus.openshift.env-vars.my-env-var.configmap=my-secret +---- + +==== Exposing Routes + +To expose a route for the Quarkus application: + +[source] +---- +quarkus.openshift.expose=true +---- + +==== Mounting volumes + +The Openshift extension allows the user to configure both volumes and mounts for the application. + +Any volume can be mounted with a simple configuration: + +[source] +---- +quarkus.openshift.mounts.my-volume.path=/where/to/mount +---- + +This will add a mount to my pod for volume `my-voume` to path `/where/to/mount` + +The volumes themselves can be configured as shown in the sections below: + +===== Secret volumes + +[source] +---- +quarkus.openshift.secret-volumes.my-volume.secret-name=my-secret +---- + +===== ConfigMap volumes + +[source] +---- +quarkus.openshift.config-map-volumes.my-volume.config-map-name=my-secret +----