Merge pull request #119 from redhat-developer-demos/openshift-sandbox

Add Openshift Sandbox as a deployment target

Author: kdubois

documentation/modules/ROOT/assets/images/Dev_Services_Stopped.png

@@ -1,6 +1,6 @@
 = Dev Services
 
-Quarkus supports the automatic provisioning of unconfigured services in *development and test* mode. 
+Quarkus supports the automatic provisioning of unconfigured services in *dev and test* mode. 
 We refer to this capability as Dev Services. From a developer's perspective this means that if you include an extension and don't configure it then Quarkus will automatically start the relevant service (usually using https://www.testcontainers.org/[Testcontainers] behind the scenes) and wire up your application to use this service, even pre-configuring access credentials.
 
 NOTE: Dev Services will only be enabled in dev/test mode, so it will not affect the application running in production.  If you want to disable all Dev Services you can use the quarkus.devservices.enabled=false config property, or you can simply configure the service in which case it will result in the Dev Service being disabled automatically.
@@ -11,7 +11,7 @@ More on zero config setup of datasources can be found https://quarkus.io/guides/
 
 == Replace Database Extensions 
 
-Instead of the built-in h2 database, we're now going to use an external database.  Swapping out from one database provider to another is fairly trivial with Quarkus.  We just remove the h2 extension and add the postgresql extension instead:
+Instead of the built-in h2 database, we're now going to use an external database.  Swapping out from one database provider to another is fairly trivial with Quarkus.  In our case we just need to remove the h2 extension and add the postgresql extension instead:
 
 
 [tabs]
@@ -42,9 +42,9 @@ quarkus extension add quarkus-jdbc-postgresql
 
 == Update configuration
 
-We'll also need to update the configuration and change h2 to postgresql:
+Update the configuration and change h2 to postgresql by updating the application.properties:
 
-TIP: Technically you don't need to add the db-kind property since there is only one jdbc driver in this case.  We added it for clarity's sake.
+TIP: You technically don't need to add the db-kind property since there is only one jdbc driver in our application.  We added it for clarity's sake.
 
 [#quarkuspdb-update-props]
 [.console-input]
@@ -58,22 +58,17 @@ quarkus.hibernate-orm.database.generation=drop-and-create
 ----
 
 
-
-
-You will now see that Quarkus has reloaded and started up a Postgresql database dev service:
+Notice in the logs how Quarkus has reloaded and started up a Postgresql database dev service:
 
 [.console-output]
 [source,text]
 ----
-
---
-Checking Podman Environment
 2023-03-16 08:06:56,882 INFO  [io.qua.dat.dep.dev.DevServicesDatasourceProcessor] (build-13) Dev Services for the default datasource (postgresql) started - container ID is c7c9a6ccf029
 ----
 
 == Verify Postgresql testcontainer is running
 
-You can now also verify/access the dev services container via Podman:
+Let's verify in Docker/Podman that the dev services container is running.  You should see 2 containers, one testcontainers/ryuk container which orchestrates the dev services, and another postgres container which is running the database and which is automatically wired into our Quarkus dev mode:
 
 [.console-input]
 [source,bash,subs="+macros,+attributes"]
@@ -84,7 +79,7 @@ docker ps
 [.mt-4.center]
 image::Dev_Services_Podman_ps.png[Dev Services Container,800,100,align="left"]
 
-You can check to see that the fruit endpoint is still working, but in this case the data is coming from the postgresql database. 
+Call the fruit endpoint again. The data is now coming from the postgresql database container. 
 
 [.console-input]
 [source,bash,subs="+macros,+attributes"]
@@ -109,6 +104,70 @@ curl localhost:8080/fruit?season=Spring
 ]
 ----
 
+== Run Unit Tests with TestContainers
+
+Let's stop dev mode for now to verify that the Postgres container also stops when we're done with dev mode by sending a `CTRL+C` in the terminal and checking again with docker ps. Notice that the postgres container has disappeared as expected.
+
+[.console-input]
+[source,bash,subs="+macros,+attributes"]
+----
+docker ps 
+----
+
+[.mt-4.center]
+image::Dev_Services_Stopped.png[Dev Services Stopped,800,100,align="left"]
+
+Run the tests:
+
+[tabs%sync]
+====
+Maven::
++ 
+--
+[.console-input]
+[source,bash,subs="+macros,+attributes"]
+----
+mvn test
+----
+
+--
+Quarkus CLI::
++
+--
+[.console-input]
+[source,bash,subs="+macros,+attributes"]
+----
+quarkus test
+----
+
+Reminder: Once the tests have run, send `CTRL+C` since Quarkus CLI starts tests in continuous mode.
+--
+====
+
+Notice in the logs that Quarkus and TestContainers work in unison to spin up the Postgres container again, run the tests, and then tear down the container again once done. 
+
+[.console-output]
+[source,text]
+----
+[INFO] -------------------------------------------------------
+[INFO]  T E S T S
+[INFO] -------------------------------------------------------
+[INFO] Running com.redhat.developers.GreetingResourceTest
+2023-07-04 17:40:04,096 INFO  [org.tes.doc.DockerClientProviderStrategy] (build-23) Found Docker environment with Environment variables, system properties and defaults. Resolved dockerHost=unix:///run/user/1000/podman/podman.sock
+2023-07-04 17:40:04,100 INFO  [org.tes.DockerClientFactory] (build-23) Docker host IP address is localhost
+2023-07-04 17:40:04,235 INFO  [org.tes.DockerClientFactory] (build-23) Connected to docker: 
+  Server Version: 4.5.1
+  API Version: 1.41
+  Operating System: fedora
+  Total Memory: 31787 MB
+2023-07-04 17:40:04,254 INFO  [org.tes.uti.ImageNameSubstitutor] (build-23) Image name substitution will be performed by: DefaultImageNameSubstitutor (composite of 'ConfigurationFileImageNameSubstitutor' and 'PrefixingImageNameSubstitutor')
+2023-07-04 17:40:04,257 INFO  [org.tes.DockerClientFactory] (build-23) Checking the system...
+2023-07-04 17:40:04,258 INFO  [org.tes.DockerClientFactory] (build-23) ✔︎ Docker server version should be at least 1.6.0
+2023-07-04 17:40:05,038 INFO  [tc.doc.io/postgres:14] (build-23) Creating container for image: docker.io/postgres:14
+----
+
+
+
 
 == [Optional] Re-deploy to Kubernetes
 
@@ -132,9 +191,9 @@ NOTE: We added a %prod. prefix to some of the properties.  This prefix makes it
 
 === Create a postgresql database
 
-There are several ways to deploy a Postgresql Database to Kubernetes.  If you're using Openshift, you could create one easily through the UI (Developer Perspective > +Add > Database > PostgreSQL).  Just make sure your database name, username and password match up with what you have configured in your application.properties or secrets.  
+There are several ways to deploy a Postgresql Database to Kubernetes.  If you're using Openshift, you could create one easily through the UI (Developer Perspective > +Add > Database > PostgreSQL).  Make sure your database name, username and password match up with what you have configured in your application.properties or secrets.  
 
-You can also create the following Kubernetes manifest for a simple ephemeral instance:
+Alternatively you can also create the following Kubernetes manifest for a simple ephemeral instance:
 
 [.console-input]
 [source,bash,subs="+macros,+attributes"]

documentation/modules/ROOT/assets/images/openshift_sandbox.png

@@ -1,13 +1,18 @@
 =  Deploying to Kubernetes
 
-IMPORTANT: You will need a public container registry to store your image. If you don't have an account, we recommend you to create a free account at http://quay.io[window=_blank]. 
+[.mt-4.right]
+image::openshift_sandbox.png[Openshift Sandbox,250,250,align="right",link="https://developers.redhat.com/developer-sandbox"]
+
+In this chapter we will push our newly built application to Kubernetes. If you don't have a Kubernetes instance at your disposal, you can create a free Openshift Sandbox instance on https://developers.redhat.com/developer-sandbox[developers.redhat.com/sandbox].
+
+
+ 
+IMPORTANT: You will need a public container registry to store your image. If you don't have an account, we recommend to create a free account at http://quay.io[window=_blank]. 
 
 Our examples will be using the `quay.io` container registry and the `myrepo` organization, but you should change it to match your configuration.
 
 == Adding the Kubernetes and Jib extensions
 
-You need a container registry that is accessible from your Kubernetes cluster to deploy the application container image in it.
-
 In this chapter we'll be using the Quarkus Kubernetes Extension to create the Kubernetes deployment file, and the Quarkus Jib Extension to create and push the container image to your container registry without the need of a local podman/docker instance.
 
 Let's add the required extensions:
@@ -54,12 +59,13 @@ quarkus.container-image.registry=quay.io#<1>
 quarkus.container-image.group=myrepo#<2>
 quarkus.container-image.name=tutorial-app#<3>
 quarkus.container-image.tag=1.0-SNAPSHOT#<4>
-quarkus.kubernetes.service-type=load-balancer
+quarkus.kubernetes.service-type=load-balancer<5>
 ----
 <1> Registry where image is pushed. By default this is Docker Hub.
 <2> Group name of the container image.
 <3> Container name. By default is the `artifactId` element of `pom.xml`.
 <4> Tag of the container image. By default is the `version` element of `pom.xml`.
+<5> Create an external ip for the service.
 
 IMPORTANT: Change `quay.io` to your container registry and `myrepo` to your organization. 
 If you don't, your push *will* fail.
@@ -74,7 +80,7 @@ In order to push the container image, you need to authenticate to your container
 docker login quay.io
 ----
 
-Now create and push your container image using jib:
+Now we're going to create the artifact, build a container and push it to our registry in one go using jib.
 
 [tabs]
 ====
@@ -84,7 +90,7 @@ Maven::
 [.console-input]
 [source,bash,subs="+macros,+attributes"]
 ----
-mvn clean package -DskipTests -Dquarkus.container-image.push=true
+mvn clean package -DskipTests -Dquarkus.container-image.push=true -Dquarkus.container-image.builder=jib
 ----
 
 --
@@ -94,11 +100,13 @@ Quarkus CLI::
 [.console-input]
 [source,bash,subs="+macros,+attributes"]
 ----
-quarkus image push --also-build --no-tests
+quarkus image build jib --no-tests -Dquarkus.container-image.push=true
 ----
 --
 ====
 
+NOTE: You can also use Docker/Podman to build & push.  To do so, just omit 'jib' from the command.
+
 [.console-output]
 [source,text]
 ----
@@ -115,15 +123,35 @@ quarkus image push --also-build --no-tests
 [INFO] ------------------------------------------------------------------------
 ----
 
+
+
 == Deploy your application to your Kubernetes cluster
 
-When a Kubernetes extension is present in the classpath, a Kubernetes deployment file is scaffolded for you during the package phase.
+When a Kubernetes extension is present in the classpath, Quarkus will scaffold a Kubernetes deployment file in your target folder during the package phase.  We can apply it to deploy the application to our Kubernetes cluster:  
+
+NOTE: You will need the https://kubernetes.io/docs/tasks/tools/[kubectl] or oc cli tool installed locally for the apply command below. https://developers.redhat.com/blog/2021/04/21/access-your-developer-sandbox-for-red-hat-openshift-from-the-command-line#[Here are instructions] to install the oc tool and log in to your Openshift Sandbox.
 
+[tabs]
+====
+kubectl::
++
+--
 [.console-input]
 [source,bash]
 ----
 kubectl apply -f target/kubernetes/kubernetes.yml
 ----
+--
+oc::
++
+--
+[.console-input]
+[source,bash]
+----
+oc apply -f target/kubernetes/kubernetes.yml
+----
+--
+====
 
 [.console-output]
 [source,text]
@@ -133,52 +161,63 @@ service/tutorial-app created
 deployment.apps/tutorial-app created
 ----
 
-You might need to wait for some seconds until your application is up and running.
+[TIP]
+=====
+With the Quarkus CLI tool deploying is even easier.  Instead of the above `kubectl apply` command, you can simply run `quarkus deploy` to deploy the application to your cluster:
+[.console-input]
+[source,bash,subs="+macros,+attributes"]
+----
+quarkus deploy
+----
+=====
+
+You might need to wait a few seconds until your application is up and running.  Once it is, let's get the url to test:
+
 
 [tabs]
 ====
-Minikube::
+Openshift Sandbox / Kubernetes on AWS::
 +
 --
+If using a hosted Kubernetes cluster like OpenShift (Sandbox) on AWS then use curl and the EXTERNAL-IP address with port `8080` or get it using `kubectl`:
+
 :tmp-service-exposed: tutorial-app
 
-[#{section-k8s}-ip-port-minikube]
+[#{section-k8s}-ip-port-service]
 [.console-input]
 [source,bash,subs="+macros,+attributes"]
 ----
-IP=$(minikube ip)
-PORT=$(kubectl get service/{tmp-service-exposed} -o jsonpath="{.spec.ports[*].nodePort}")
+IP=$(kubectl get service {tmp-service-exposed} -o jsonpath="{.status.loadBalancer.ingress[0].hostname}")
+PORT=$(kubectl get service {tmp-service-exposed} -o jsonpath="{.spec.ports[0].port}")
 echo $IP:$PORT
 ----
 --
-Hosted::
+Minikube::
 +
 --
-If using a hosted Kubernetes cluster like OpenShift then use curl and the EXTERNAL-IP address with port `8080` or get it using `kubectl`:
-
 :tmp-service-exposed: tutorial-app
 
-[#{section-k8s}-ip-port-openshift]
+[#{section-k8s}-ip-port-minikube]
 [.console-input]
 [source,bash,subs="+macros,+attributes"]
 ----
-IP=$(kubectl get service {tmp-service-exposed} -o jsonpath="{.status.loadBalancer.ingress[0].ip}")
-PORT=$(kubectl get service {tmp-service-exposed} -o jsonpath="{.spec.ports[*].port}")
+IP=$(minikube ip)
+PORT=$(kubectl get service/{tmp-service-exposed} -o jsonpath="{.spec.ports[*].nodePort}")
 echo $IP:$PORT
 ----
 --
-Hosted on AWS::
+Hosted::
 +
 --
 If using a hosted Kubernetes cluster like OpenShift then use curl and the EXTERNAL-IP address with port `8080` or get it using `kubectl`:
 
 :tmp-service-exposed: tutorial-app
 
-[#{section-k8s}-ip-port-service]
+[#{section-k8s}-ip-port-openshift]
 [.console-input]
 [source,bash,subs="+macros,+attributes"]
 ----
-IP=$(kubectl get service {tmp-service-exposed} -o jsonpath="{.status.loadBalancer.ingress[0].hostname}")
+IP=$(kubectl get service {tmp-service-exposed} -o jsonpath="{.status.loadBalancer.ingress[0].ip}")
 PORT=$(kubectl get service {tmp-service-exposed} -o jsonpath="{.spec.ports[*].port}")
 echo $IP:$PORT
 ----
@@ -200,4 +239,19 @@ curl $IP:$PORT/hello
 Hello y'all!
 ----
 
-TIP: You can build, push and deploy the container image by running: `./mvnw clean package -Dquarkus.kubernetes.deploy=true`
+[sidebar]
+--
+TIP: If you're using Openshift (Sandbox) and would like to create a url you can share to the outside world, you can create it like so:
+[.console-input]
+[source,bash,subs="+macros,+attributes"]
+----
+oc create route edge --service=tutorial-app 
+url=$(oc get route tutorial-app -o jsonpath='{.spec.host}')
+curl https://$url/hello
+----
+[.console-output]
+[source,text]
+----
+Hello y'all!
+----
+--

documentation/modules/ROOT/pages/dev-services.adoc

@@ -37,7 +37,7 @@ Maven::
 [.console-input]
 [source,bash,subs="+macros,+attributes"]
 ----
-mvn quarkus:add-extension -Dextensions=quarkus-rest-client
+mvn quarkus:add-extension -Dextensions=quarkus-rest-client-reactive,quarkus-rest-client-reactive-jsonb
 ----
 
 --
@@ -47,7 +47,7 @@ Quarkus CLI::
 [.console-input]
 [source,bash,subs="+macros,+attributes"]
 ----
-quarkus extension add quarkus-rest-client
+quarkus extension add rest-client-reactive rest-client-reactive-jsonb
 ----
 --
 ====