-
Notifications
You must be signed in to change notification settings - Fork 2.6k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
doc: Add doc for openshift extension
- Loading branch information
Showing
2 changed files
with
189 additions
and
1 deletion.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,186 @@ | ||
//// | ||
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 default 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 it's 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] | ||
---- | ||
<dependency> | ||
<groupId>io.quarkus</groupId> | ||
<artifactId>quarkus-openshift</artifactId> | ||
</dependency> | ||
---- | ||
|
||
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: | ||
|
||
==== Exposing Routes | ||
|
||
To expose a `Route` for the Quarkus application: | ||
|
||
[source] | ||
---- | ||
quarkus.openshift.expose=true | ||
---- | ||
|
||
Tip: You don't necesserily need to add this property in the `application.properties`. You can pass it as a command line argument: | ||
|
||
[source, subs=attributes+] | ||
---- | ||
mvn clean package -Dquarkus.openshift.expose=true | ||
---- | ||
|
||
The same applies to all properties listed 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 note 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 additional options rather than just value. | ||
|
||
===== Environment variables from Secret | ||
|
||
To add all key value pairs of a `Secret` as environment 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 environment variables: | ||
|
||
[source] | ||
---- | ||
quarkus.openshift.env-vars.my-env-var.configmap=my-secret | ||
---- | ||
|
||
|
||
==== 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 | ||
---- |