Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: Create procedure for Deploying on OpenShift using Docker build strategy #45918

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
+154 −0
Open

Docs: Create procedure for Deploying on OpenShift using Docker build strategy #45918

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3013152
QDOCS-1060: create docker build procedures
sheilamjones Jan 28, 2025
4699d8f
QDOCS-1060: fix attribtes and minor edits
sheilamjones Feb 5, 2025
b87770d
QDOCS-1060: fix build error
sheilamjones Feb 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
154 changes: 154 additions & 0 deletions docs/src/main/asciidoc/deploying-to-openshift-docker-howto.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,154 @@
////
This guide 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
////
[id="deploying-to-openshift-docker-howto"]
= Deploy {project-name} Java applications to {openshift} by using a Docker build strategy
include::_attributes.adoc[]
:diataxis-type: howto
:categories: cloud, native
:summary: This guide describes how to build and deploy a Quarkus application on {openshift} by using the Docker build strategy.
:topics: devops,kubernetes,openshift,cloud,deployment
:extensions: io.quarkus:quarkus-openshift

As an application developer, you can deploy your applications to {openshift} by using the Docker build strategy as a deployment option.
This functionality is provided by the `quarkus-openshift` extension.

The container gets built inside the {openshift} cluster and is provided as an image stream.
sheilamjones marked this conversation as resolved.
Show resolved Hide resolved

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.
sheilamjones marked this conversation as resolved.
Show resolved Hide resolved

== Prerequisites

* You have OpenJDK {JDK-ver-all} installed.
* You have set the `JAVA_HOME` environment variable to the location of the Java SDK.
* You have Apache Maven {maven-version} installed.
* You have a Quarkus project that includes the `quarkus-openshift` extension.
* You have access to a {openshift} cluster and the latest compatible version of the `oc` tool installed.
sheilamjones marked this conversation as resolved.
Show resolved Hide resolved
* You are working in the correct OpenShift project namespace.

== 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:
sheilamjones marked this conversation as resolved.
Show resolved Hide resolved
.. If you are using an untrusted certificate, configure the `KubernetesClient`:
sheilamjones marked this conversation as resolved.
Show resolved Hide resolved
+
[source,properties]
----
quarkus.kubernetes-client.trust-certs=true
----
.. Expose the service to create an {openshift} route:
sheilamjones marked this conversation as resolved.
Show resolved Hide resolved
+
[source,properties]
----
quarkus.openshift.route.expose=true
----
.. Set the path to your custom Dockerfile:
sheilamjones marked this conversation as resolved.
Show resolved Hide resolved
+
[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
sheilamjones marked this conversation as resolved.
Show resolved Hide resolved
----

. Package and deploy your application to the current OpenShift project:
sheilamjones marked this conversation as resolved.
Show resolved Hide resolved
+
[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.
sheilamjones marked this conversation as resolved.
Show resolved Hide resolved


. 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:
Comment on lines +93 to +94
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
. 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:
. To get the log output for your application's pod, use the `oc logs -f` command with its name. For example:

+
[source,shell,subs="+quotes",options="nowrap"]
----
oc logs -f _openshift-helloworld-1-gzzrx_
----
+
[source,shell,subs=attributes+]
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
[source,shell,subs=attributes+]
.Example output
[source,shell,subs=attributes+]

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm unsure whether we want to label outputs, but if we do, we should aim to apply it consistently across all upstream-downstream documentation. Something to think about for the future.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good point and +1. I think it looks better to have the label, but for consistency reasons, I might leave this as it is for now and look to deciding whether or not to apply it in the future across the other guides.

----
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:
sheilamjones marked this conversation as resolved.
Show resolved Hide resolved
+
[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 {openshift} route, ensure you have specified `quarkus.openshift.route.expose=true` in the `application.properties` file.
====
sheilamjones marked this conversation as resolved.
Show resolved Hide resolved
+
[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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd double-check with the SME correctness of the current statement. Is the route is listening on port 80 in addition to port 8080? If so, maybe:

Suggested change
Be aware that the route is now listening on port 80 and no longer at port 8080.
Be aware that the route is now listening on port 80.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@iocanel, perhaps you could advise here?

====
+
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`.


Loading