-
Notifications
You must be signed in to change notification settings - Fork 2.7k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
QDOCS-1059: creation of deploy to openshift proc
Signed-off-by: shjones <[email protected]>
- Loading branch information
1 parent
aec3f34
commit ef47119
Showing
1 changed file
with
166 additions
and
0 deletions.
There are no files selected for viewing
166 changes: 166 additions & 0 deletions
166
docs/src/main/asciidoc/deploying-to-openshift-howto.adoc
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,166 @@ | ||
| //// | ||
| This document is maintained in the main Quarkus repository | ||
| and pull requests should be submitted there: | ||
| https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc | ||
| //// | ||
| //// | ||
| TODO: | ||
| - Title: https://quarkus.io/guides/doc-reference#titles-headings | ||
| - Use the file name as the ID | ||
| - Choose appropriate categories: https://quarkus.io/guides/doc-reference#categories | ||
| //// | ||
| [id="deploying-to-openshift-howto"] | ||
| = Deploy {project-name} Java applications to OpenShift Container Platform | ||
| include::_attributes.adoc[] | ||
| :diataxis-type: howto | ||
| :categories: cloud, native | ||
| :summary: This guide covers how to deploy a Quarkus application on OpenShift. | ||
| :topics: devops,kubernetes,openshift,cloud,deployment | ||
| :extensions: io.quarkus:quarkus-openshift | ||
|
|
||
| As an application developer, you can deploy your Quarkus applications to OpenShift Container Platform by using a single Maven command with the Docker build strategy. | ||
| This functionality is provided by the `quarkus-openshift` extension, which supports multiple deployment options, including the Docker build strategy and the Source-to-Image (S2I) strategy. | ||
|
|
||
| The container is built inside the {RHOSSHORT} cluster and is provided as an image stream. | ||
| Your Quarkus project includes pregenerated Dockerfiles with instructions. | ||
| When you want to use a custom Dockerfile, you must add the file in the `src/main/docker` directory or anywhere inside the module. | ||
| Additionally, you must set the path to your Dockerfile by using the `quarkus.openshift.jvm-dockerfile` property. | ||
|
|
||
| == Prerequisites | ||
|
|
||
| * You have OpenJDK 17 or later installed. | ||
| * You have set the `JAVA_HOME` environment variable to the location of the Java SDK. | ||
| * You have Apache Maven {MavenVersion} installed. | ||
| //* You have a Quarkus project that includes the `quarkus-openshift` extension. | ||
| ** To add the Quarkus OpenShift extension, see xref:proc_adding-the-quarkus-openshift-extension_quarkus-openshift[Adding the {ProductName} OpenShift extension]. | ||
| * You have access to an OpenShift Container Platform cluster and the latest compatible version of the `oc` tool installed. | ||
| //** For information about installing the `oc` tool, see link:https://access.redhat.com/documentation/en-us/openshift_container_platform/{RHOSVersion}/html/cli_tools/index[CLI tools]. | ||
| You are working in the correct OpenShift project namespace, as outlined in xref:proc_verifying-the-openshift-project-namespace_quarkus-openshift[Switching to the required {RHOSSHORT} project]. | ||
|
|
||
| == Procedure | ||
|
|
||
|
|
||
| . Set the Docker build strategy in your `application.properties` configuration file: | ||
| + | ||
| [source, properties] | ||
| ---- | ||
| quarkus.openshift.build-strategy=docker | ||
| ---- | ||
| . Optional: Set the following properties in the `application.properties` file, as required by your environment: | ||
| .. If you are using an untrusted certificate, configure the `KubernetesClient`: | ||
| + | ||
| [source,properties] | ||
| ---- | ||
| quarkus.kubernetes-client.trust-certs=true | ||
| ---- | ||
| .. Expose the service to create an {RHOSSHORT} route: | ||
| + | ||
| [source,properties] | ||
| ---- | ||
| quarkus.openshift.route.expose=true | ||
| ---- | ||
| .. Set the path to your custom Dockerfile: | ||
| + | ||
| [source,properties,subs="attributes+,+quotes"] | ||
| ---- | ||
| quarkus.openshift.jvm-dockerfile=<path_to_your_dockerfile> | ||
| ---- | ||
| The following example shows the path to the `Dockerfile.custom-jvm`: | ||
| + | ||
| [source,properties] | ||
| ---- | ||
| quarkus.openshift.jvm-dockerfile=src/main/resources/Dockerfile.custom-jvm | ||
| ---- | ||
|
|
||
| . Package and deploy your Quarkus application to the current OpenShift project: | ||
| + | ||
| [source,shell,subs="attributes+,+quotes"] | ||
| ---- | ||
| ./mvnw clean package -Dquarkus.openshift.deploy=true | ||
| ---- | ||
|
|
||
| == Verification | ||
|
|
||
| The verification steps and related terminal outputs are demonstrated on the `openshift-helloworld` example application. | ||
|
|
||
| . Display the list of pods associated with your current OpenShift project: | ||
| + | ||
| [source,shell,subs="+quotes",options="nowrap"] | ||
| ---- | ||
| oc get pods | ||
| ---- | ||
| + | ||
| [source,shell,subs="+quotes",options="nowrap"] | ||
| ---- | ||
| NAME READY STATUS RESTARTS AGE | ||
| openshift-helloworld-1-build 0/1 Completed 0 11m | ||
| openshift-helloworld-1-deploy 0/1 Completed 0 10m | ||
| openshift-helloworld-1-gzzrx 1/1 Running 0 10m | ||
| ---- | ||
|
|
||
|
|
||
| . To retrieve the log output for your application's pod, use the `oc logs -f` command with the `<pod_name>` value of the pod you are interested in. | ||
| In this example, we use the `openshift-helloworld-1-gzzrx` pod name that corresponds with the latest pod prefixed with the name of your application: | ||
| + | ||
| [source,shell,subs="+quotes",options="nowrap"] | ||
| ---- | ||
| oc logs -f _openshift-helloworld-1-gzzrx_ | ||
| ---- | ||
| + | ||
| [source,shell,subs=attributes+] | ||
| ---- | ||
| Starting the Java application using /opt/jboss/container/java/run/run-java.sh ... | ||
| INFO exec -a "java" java -Dquarkus.http.host=0.0.0.0 -Djava.util.logging.manager=org.jboss.logmanager.LogManager -XX:MaxRAMPercentage=50.0 -XX:+UseParallelGC -XX:MinHeapFreeRatio=10 -XX:MaxHeapFreeRatio=20 -XX:GCTimeRatio=4 -XX:AdaptiveSizePolicyWeight=90 -XX:+ExitOnOutOfMemoryError -cp "." -jar /deployments/quarkus-run.jar | ||
| __ ____ __ _____ ___ __ ____ ______ | ||
| --/ __ \/ / / / _ | / _ \/ //_/ / / / __/ | ||
| -/ /_/ / /_/ / __ |/ , _/ ,< / /_/ /\ \ | ||
| --\___\_\____/_/ |_/_/|_/_/|_|\____/___/ | ||
| 2024-09-17 10:23:25,254 INFO [io.quarkus] (main) getting-started 1.0.0-SNAPSHOT on JVM (powered by Quarkus {QuarkusCore}) started in 0.653s. Listening on: http://0.0.0.0:8080 | ||
| 2024-09-17 10:23:25,281 INFO [io.quarkus] (main) Profile prod activated. | ||
| 2024-09-17 10:23:25,281 INFO [io.quarkus] (main) Installed features: [cdi, kubernetes, rest, smallrye-context-propagation, vertx] | ||
| ---- | ||
|
|
||
|
|
||
| . Retrieve a list of services: | ||
| + | ||
| [source,shell,subs="+quotes",options="nowrap"] | ||
| ---- | ||
| oc get svc | ||
| ---- | ||
| + | ||
| [source,shell,subs="+quotes",options="nowrap"] | ||
| ---- | ||
| NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE | ||
| openshift-helloworld ClusterIP 172.30.64.57 <none> 80/TCP 14m | ||
| ---- | ||
|
|
||
|
|
||
| . Get a URL to test your application. | ||
| + | ||
| [NOTE] | ||
| ==== | ||
| To create an {RHOSSHORT} route, ensure you have specified `quarkus.openshift.route.expose=true` in the `application.properties` file. | ||
| ==== | ||
| + | ||
| [source,shell,subs="+quotes",options="nowrap"] | ||
| ---- | ||
| oc get routes | ||
| ---- | ||
| + | ||
| [source,shell,subs="+quotes",options="nowrap"] | ||
| ---- | ||
| NAME HOST/PORT PATH SERVICES PORT TERMINATION WILDCARD | ||
| openshift-helloworld openshift-helloworld-username-dev.apps.sandbox-m2.ll9k.p1.openshiftapps.com openshift-helloworld http None | ||
| ---- | ||
| + | ||
| [NOTE] | ||
| ==== | ||
| Be aware that the route is now listening on port 80 and no longer at port 8080. | ||
| ==== | ||
| + | ||
| You can test the application demonstrated in this example with a web browser or a terminal by using `curl` and the complete URL output from `oc get routes`, that is, "\http://openshift-helloworld-username-dev.apps.sandbox-m2.ll9k.p1.openshiftapps.com". | ||
| + | ||
| For example: `curl \http://openshift-helloworld-username-dev.apps.sandbox-m2.ll9k.p1.openshiftapps.com`. | ||
|
|
||
| == References | ||
|
|