Docs: Create procedure doc for use case "Deploy to Openshift in a single step"

docs/src/main/asciidoc/deploying-to-openshift-howto.adoc

@@ -0,0 +1,114 @@
+////
+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
+////
+[id="deploying-to-openshift-howto"]
+= Deploy {project-name} applications to {openshift}
+include::_attributes.adoc[]
+:diataxis-type: howto
+:categories: cloud, native
+:summary: This guide describes how to build and deploy a Quarkus application to OpenShift in a single step.
+:topics: devops,kubernetes,openshift,cloud,deployment
+:extensions: io.quarkus:quarkus-openshift
+
+As an application developer, you build and deploy your {project-name} applications to OpenShift by using a single command.
+
+With this one command, you build your application locally, trigger a container image build, then apply the generated {openshift} resources automatically.
+The generated resources use a Kubernetes `Deployment`, but still make use of OpenShift-specific resources, such as `Route`, `BuildConfig`, and so on.
+
+[IMPORTANT]
+====
+As of {openshift} 4.14, the `DeploymentConfig` object is deprecated.
+`Deployment` is now the default and preferred deployment kind for the Quarkus OpenShift extension.
+
+Because of this change, take the following considerations into account:
+
+* If you redeploy applications that you previously deployed by using `DeploymentConfig`, by default, those applications use `Deployment` but do not remove the previous `DeploymentConfig`.
+This leads to a deployment of both new and old applications, so, you must remove the old `DeploymentConfig` manually.
+If you want to continue to use `DeploymentConfig`, it is still possible to do so by explicitly setting `quarkus.openshift.deployment-kind` to `DeploymentConfig`.
+* `Deployment` is a Kubernetes resource and not OpenShift specific, so it cannot leverage `ImageStream` resources, as is the case with `DeploymentConfig`.
+Therefore, the image references must include the container image registry that hosts the image.
+
+For more information about the deprecation, how to set up and use automatic rollbacks, triggers, lifecycle hooks, and custom strategies, see the Red Hat Knowledgebase article https://access.redhat.com/articles/7041372[DeploymentConfig API is being deprecated in Red Hat OpenShift Container Platform 4.14].
+====
+
+== 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 {maven-version} installed.
+* You have access to an {openshift} cluster and the latest compatible version of the `oc` tool installed.
+* You are working in the correct OpenShift project namespace.
+
+[NOTE]
+====
+To run this deployment, it is not necessary to have the `quarkus-openshift` extension included in your {project-name} project.
+====
+
+== Build and deploy a {project-name} application on OpenShift
+
+. Trigger a build and deployment by running the following command:
+
+:build-additional-parameters: quarkus deploy openshift
+include::{includes}/devtools/build.adoc[]
+:!build-additional-parameters:
+
+[TIP]
+====
+If you want to test your application immediately, set the `quarkus.openshift.route.expose` configuration property to `true` to expose the service automatically.
+For example, add `-Dquarkus.openshift.route.expose=true` to the above command.
+For more information, see xref:deploying-to-openshift.adoc#exposing_routes[Exposing routes].
+====
+
+[[re-deploy-with-service-binding]]
+[NOTE]
+====
+When using `DeploymentConfig` and xref:deploying-to-kubernetes.adoc#service_binding[service binding], redeploying might remove the configuration that is added by {openshift} to allow service discovery.
+
+A new container image build triggers a refresh of the {project-name} application in {openshift}: `-Dquarkus.container-image.build=true`, which might suffice in most situations.
+If you need to update {openshift} resources, delete the binding first and create it again after new deployment.
+====
+
+== Verification
+
+. Verify that an image stream and a service resource is created and the {project-name} application is deployed by using the OpenShift web console.
++
+[source,properties]
+----
+quarkus.container-image.group=<project/namespace name>
+----
++
+Alternatively, run the following OpenShift command-line interface (CLI) commands:
++
+[source,bash,subs=attributes+]
+----
+oc get is <1>
+oc get pods <2>
+oc get svc <3>
+----
+<1> List the image streams created.
+<2> View a list of pods associated with your current OpenShift project.
+<3> Get the list of Kubernetes services.
+
+. To retrieve the log output for your application's pod, enter the following command:
++
+[source,shell,subs="+quotes",options="nowrap"]
+----
+oc logs -f <pod_name>
+----
+
+By default, the service is not exposed to the outside world.
+Therefore, if you did not use the `quarkus.openshift.route.expose` configuation property to expose the created service automatically, you can expose the service manually.
+
+For example:
+[source,bash,subs=attributes+]
+----
+oc expose svc/openshift-quickstart <1>
+oc get routes <2>
+curl http://<route>/hello <3>
+----
+<1> Expose the service.
+<2> Get the list of exposed routes.
+<3> Access your application.
+