diff --git a/docs/src/main/asciidoc/deploying-to-openshift-howto.adoc b/docs/src/main/asciidoc/deploying-to-openshift-howto.adoc new file mode 100644 index 0000000000000..2dd79e14990b4 --- /dev/null +++ b/docs/src/main/asciidoc/deploying-to-openshift-howto.adoc @@ -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= +---- +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 `` 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 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 +