commit ccc6a3071ef2eac703ca63645a2d6b8ba9753508 Author: jamesfalkner Date: Fri Jun 14 10:14:47 2019 -0400 initial commit diff --git a/README.adoc b/README.adoc new file mode 100644 index 0000000..1256943 --- /dev/null +++ b/README.adoc @@ -0,0 +1,39 @@ += Quarkus Workshop Guide + +This workshop focuses on https://quarkus.io[Quarkus], supersonic, subatomic container-native Java. The workshop uses https://eclipse.org/che[Eclipse Che] to develop Quarkus apps and deploy them to a Kubernetes cluster (based on OpenShift), and covers several other developer topics such as: + +* Dependency Injection +* Testing Quarkus Apps +* Debugging Quarkus Apps +* Building Native Quarkus Apps +* Developing Cloud Native with Quarkus +* Using Quarkus extensions +* Hibernate ORM with Panache +* Event-driven Messaging +* Streaming Data with Quarkus and Kafka +* Monitoring with Prometheus and Grafana +* Tracing Quarkus Apps with Jaeger and MicroProfile Tracing + + +== Prerequisites + +Assumes you have a running OpenShift 4 cluster and have: + +- CLI Utils: `htpasswd` (part of Apache HTTPD) - used to generate users for OpenShift +- https://github.com/mikefarah/yq[`yq`] (YAML processor) +- OpenShift 4 CLI `oc` for your environment from https://mirror.openshift.com/pub/openshift-v4/clients/ocp/latest/. + +[IMPORTANT] +==== +If you not have OCP4 cluster then please proceed to https://try.openshift.com[try.openshift.com] to get one installed and configured before proceeding to next section. +==== + +== Setup Workshop + +Login to OpenShift with `cluster-admin` privileges and run: + +[source, none] +``` +setup/preparelab.sh -a [ADMIN_PASSWORD] -c [COUNT] +``` + diff --git a/docs/_modules.yml b/docs/_modules.yml new file mode 100644 index 0000000..5ddaa35 --- /dev/null +++ b/docs/_modules.yml @@ -0,0 +1,27 @@ +modules: + intro: + name: Lab Instructions + basics: + name: Getting Started with Quarkus + cdi: + name: Dependency Injection + testing: + name: Testing Quarkus Apps + debugging: + name: Debugging Quarkus Apps + native: + name: Building Native Quarkus Apps + cloudnative: + name: Developing Cloud Native with Quarkus + extensions: + name: Using Quarkus extensions + panache: + name: Hibernate ORM with Panache + messaging: + name: Event-driven Messaging + kafka: + name: Streaming Data with Quarkus and Kafka + monitoring: + name: Monitoring with Prometheus and Grafana + tracing: + name: Tracing Quarkus Apps diff --git a/docs/_workshop.yml b/docs/_workshop.yml new file mode 100644 index 0000000..8ff51aa --- /dev/null +++ b/docs/_workshop.yml @@ -0,0 +1,24 @@ +--- +id: quarkus-lab +name: Quarkus Hands-on Lab + +vars: + ROUTE_SUBDOMAIN: + MASTER_URL: + CHE_URL: + +modules: + activate: + - intro + - basics + - cdi + - testing + - debugging + - native + - cloudnative + - extensions + - panache + - messaging + - kafka + - monitoring + - tracing diff --git a/docs/basics.adoc b/docs/basics.adoc new file mode 100644 index 0000000..c77a382 --- /dev/null +++ b/docs/basics.adoc @@ -0,0 +1,124 @@ +## The Basics + +In this step, you will create a straightforward application serving a `hello` endpoint. To demonstrate dependency injection this endpoint uses a `greeting` bean. + +image::imgs/arch.png[] + +## Import new project + +In Che, click on **Import Project...**. In the dialog box, select **GITHUB** as the type of import, and then enter the following URL into the URL field and click **Import**. + +[source,none,role="copypaste"] +---- +https://github.com/jamesfalkner/summit-2019-devzone +---- + +image::imgs/import.png[] + +After a few seconds, you'll get a _Project Configuration_ Dialog. Select **Maven** as the project type, and click **Save**. + +image::imgs/importmaven.png[] + +This will tell Che that the project is a Maven-based project, and be able to resolve dependencies and do error checking on the `pom.xml` file. + +The structure of the project can be seen in the project browser to the left of the code editor: + +image::imgs/structure.png[] + +The project has + +* The Maven structure +* An `org.acme.quickstart.GreetingResource` resource exposed on `/hello` +* A landing page that is accessible on `http://localhost:8080` after starting the application +* The application configuration file + +Double-click on `pom.xml` in the project browser to open it in the editor. You will find the import of the Quarkus BOM, allowing to omit the version on the different Quarkus dependencies. In addition, you can see the `quarkus-maven-plugin` responsible of the packaging of the application and also providing the development mode. + +[source,xml] +---- + + + + io.quarkus + quarkus-bom + ${quarkus.version} + pom + import + + + +---- + +And a few more `` imports and other ancillary sections. We will be adding things to our `pom.xml` in future sections. + +Navigate to `src -> main -> java -> org.acme.quarkus.sample` in the project tree and double click on `GreetingResource.java`. This class has a very simple RESTful endpoint definition: + +[source, java] +---- +@Path("/hello") +public class GreetingResource { + + @GET + @Produces(MediaType.TEXT_PLAIN) + public String hello() { + return "hello"; + } +} +---- + +It’s a very simple REST endpoint, returning "hello" to requests on `/hello`. + +[NOTE] +==== +Compared to vanilla JAX-RS, with Quarkus there is no need to create an `Application` class. It’s supported but not required. In addition, only one instance of the resource is created and not one per request. You can configure this using the different `*Scoped` annotations (`ApplicationScoped`, `RequestScoped`, etc). +==== + +## Running the Application + +Now we are ready to run our application. In Che, select the _Command Palette_ by clicking on its icon in the upper right, and double-click on **Run Locally**: + +image::images/runlocally.png[] + +This will compile and run the app using `mvn compile quarkus:dev` in a Terminal window. + +You should see: + +[source,none] +---- +2019-02-28 17:05:22,347 INFO [io.qua.dep.QuarkusAugmentor] (main) Beginning quarkus augmentation +2019-02-28 17:05:22,635 INFO [io.qua.dep.QuarkusAugmentor] (main) Quarkus augmentation completed in 288ms +2019-02-28 17:05:22,770 INFO [io.quarkus] (main) Quarkus started in 0.668s. Listening on: http://localhost:8080 +2019-02-28 17:05:22,771 INFO [io.quarkus] (main) Installed features: [cdi, resteasy] +---- + +Note the amazingly fast startup time! The app is now running "locally" (within the Che container in which the workspace is also running). Che also makes the app accessible from outside the container by creating a Route (ingress) that is displayed at the top of the Terminal window. Look for _Preview URL_: + +image::imgs/previewurl.png[] + +Click on this link to open the link in a new tab, which will access the default Quarkus HTML page included in this app: + +image::images/defaultpage.png[] + +Since our RESTful endpoint listens on the `/hello` endpoint, add `/hello` to the end of the URL in your browser tab to access it. + +You should see `hello` in your browser tab, which means its working! + +Now, let's exercise the **live reload** capabilities of Quarkus. In Che, edit the `GreetingResource.java` file and change `return "hello";` to `return "hola";` in the editor. Press `CTRL-S` (or `CMD-S` on Mac OS) to save the file. Don't recompile or restart anything. Just try to reload the same brower tab that was showing `hello`. It should now show `hola`. + +Wow, how cool is that? Supersonic Subatomic live reload! Go ahead and change it a few more times and access the endpoint again. And we're just getting started. + +[NOTE] +==== +`quarkus:dev` runs Quarkus in development mode. This enables live reload with background compilation, which means that when you modify your Java files your resource files and refresh your browser these changes will automatically take effect. +==== + +[NOTE] +==== +This will also listen for a debugger on port `5005`. If your want to wait for the debugger to attach before running you can pass `-Ddebug` on the command line. If you don’t want the debugger at all you can use `-Ddebug=false`. We'll use this later. +==== + +## Congratulations! + +You've seen how to build a basic app, package it as an executable JAR and start it up very quickly. We'll leave the app running and rely on hot reload for the next steps. + +In the next step we'll inject a custom bean to showcase Quarkus' CDI capabilities. diff --git a/docs/cdi.adoc b/docs/cdi.adoc new file mode 100644 index 0000000..9817c1b --- /dev/null +++ b/docs/cdi.adoc @@ -0,0 +1 @@ +## The Basics diff --git a/docs/cloudnative.adoc b/docs/cloudnative.adoc new file mode 100644 index 0000000..9817c1b --- /dev/null +++ b/docs/cloudnative.adoc @@ -0,0 +1 @@ +## The Basics diff --git a/docs/debugging.adoc b/docs/debugging.adoc new file mode 100644 index 0000000..9817c1b --- /dev/null +++ b/docs/debugging.adoc @@ -0,0 +1 @@ +## The Basics diff --git a/docs/extensions.adoc b/docs/extensions.adoc new file mode 100644 index 0000000..9817c1b --- /dev/null +++ b/docs/extensions.adoc @@ -0,0 +1 @@ +## The Basics diff --git a/docs/imgs/50pods.png b/docs/imgs/50pods.png new file mode 100644 index 0000000..b4d0321 Binary files /dev/null and b/docs/imgs/50pods.png differ diff --git a/docs/imgs/arch.png b/docs/imgs/arch.png new file mode 100644 index 0000000..b174605 Binary files /dev/null and b/docs/imgs/arch.png differ diff --git a/docs/imgs/login.png b/docs/imgs/login.png new file mode 100644 index 0000000..56eed72 Binary files /dev/null and b/docs/imgs/login.png differ diff --git a/docs/imgs/logo.png b/docs/imgs/logo.png new file mode 100644 index 0000000..65c16e6 Binary files /dev/null and b/docs/imgs/logo.png differ diff --git a/docs/imgs/native-image-process.png b/docs/imgs/native-image-process.png new file mode 100644 index 0000000..bbe58dd Binary files /dev/null and b/docs/imgs/native-image-process.png differ diff --git a/docs/imgs/openshift-console-tab.png b/docs/imgs/openshift-console-tab.png new file mode 100644 index 0000000..4d385fc Binary files /dev/null and b/docs/imgs/openshift-console-tab.png differ diff --git a/docs/imgs/overview.png b/docs/imgs/overview.png new file mode 100644 index 0000000..680cae7 Binary files /dev/null and b/docs/imgs/overview.png differ diff --git a/docs/imgs/panache-datatable.png b/docs/imgs/panache-datatable.png new file mode 100644 index 0000000..c875f98 Binary files /dev/null and b/docs/imgs/panache-datatable.png differ diff --git a/docs/imgs/panache-overview-empty.png b/docs/imgs/panache-overview-empty.png new file mode 100644 index 0000000..5aa9124 Binary files /dev/null and b/docs/imgs/panache-overview-empty.png differ diff --git a/docs/imgs/panache-overview.png b/docs/imgs/panache-overview.png new file mode 100644 index 0000000..a189134 Binary files /dev/null and b/docs/imgs/panache-overview.png differ diff --git a/docs/imgs/panache-projects.png b/docs/imgs/panache-projects.png new file mode 100644 index 0000000..f37e55a Binary files /dev/null and b/docs/imgs/panache-projects.png differ diff --git a/docs/imgs/projects.png b/docs/imgs/projects.png new file mode 100644 index 0000000..2936b26 Binary files /dev/null and b/docs/imgs/projects.png differ diff --git a/docs/imgs/scaling.png b/docs/imgs/scaling.png new file mode 100644 index 0000000..356b517 Binary files /dev/null and b/docs/imgs/scaling.png differ diff --git a/docs/imgs/ui.png b/docs/imgs/ui.png new file mode 100644 index 0000000..1cb8c7b Binary files /dev/null and b/docs/imgs/ui.png differ diff --git a/docs/intro.adoc b/docs/intro.adoc new file mode 100644 index 0000000..2c7630c --- /dev/null +++ b/docs/intro.adoc @@ -0,0 +1,49 @@ +## What is Quarkus? + +image::imgs/logo.png[] + +Quarkus is a Kubernetes Native Java stack tailored for GraalVM & OpenJDK HotSpot, crafted from the best of breed Java libraries and standards. Amazingly fast boot time, incredibly low RSS memory (not just heap size!) offering near instant scale up and high density memory utilization in container orchestration platforms like Kubernetes. Quarkus uses a technique called https://quarkus.io/vision/container-first[compile time boot] and offers a unified imperative and reactive programming model and a number of other developer features like Live Reload to bring _real joy to your development_. + +## Conventions +You will see various code and command blocks throughout these exercises. Some of +the command blocks can be copy/pasted directly. Others will require modification +of the command before execution. If you see a command block with a red border +(see below), the command will require slight modification. + +[source,none,role="copypaste copypaste-warning"] +---- +some command to modify +---- + +Others, including source code snippets can by copy/pasted directly, and do not require modification. + +[source,java,role="copypaste"] +---- +/* A sample Java snippet that you can copy/paste by clicking */ +public class CopyMeDirectly { + public static void main(String[] args) { + System.out.println("You can copy this whole class with a click!"); + } +} +---- + +Most command blocks support auto highlighting with a click. If you hover over +the command block above and left-click, it should automatically highlight all the +text to make for easier copying. + +## Your Development Environment + +You will be using Red Hat CodeReady Workspaces, an online IDE based on https://www.eclipse.org/che/[Eclipe Che]. To get started, {{ CHE_URL }}[access the Che instance] and register as a new user using the username you've been assigned (e.g. `user32`, `user8`, etc): + +image::imgs/che-register.png[] + +Once you register, you'll be placed on your personal dashboard allowing you to spawn new workspaces to work on code in a traditional IDE environment. Click on the **Add Workspace** tab on the left, and select the "J4K Stack - Java, Quarkus, odo", and click **Create & Open** to start the workspace: + +image::imgs/che-createworkspace.png[] + +After a minute or two, you'll be placed in the workspace: + +image::imgs/che-workspace.png[] + +Users of Eclipse, IntelliJ IDEA or Visual Studio Code will see a familiar layout: a project/file browser on the left, a code editor on the right, and a terminal at the bottom. You'll use all of these during the course of this workshop, so keep this browser tab open throughout. If things get weird, you can simply reload the browser tab to refresh the view. + diff --git a/docs/kafka.adoc b/docs/kafka.adoc new file mode 100644 index 0000000..9817c1b --- /dev/null +++ b/docs/kafka.adoc @@ -0,0 +1 @@ +## The Basics diff --git a/docs/messaging.adoc b/docs/messaging.adoc new file mode 100644 index 0000000..9817c1b --- /dev/null +++ b/docs/messaging.adoc @@ -0,0 +1 @@ +## The Basics diff --git a/docs/monitoring.adoc b/docs/monitoring.adoc new file mode 100644 index 0000000..9817c1b --- /dev/null +++ b/docs/monitoring.adoc @@ -0,0 +1 @@ +## The Basics diff --git a/docs/native.adoc b/docs/native.adoc new file mode 100644 index 0000000..9817c1b --- /dev/null +++ b/docs/native.adoc @@ -0,0 +1 @@ +## The Basics diff --git a/docs/panache.adoc b/docs/panache.adoc new file mode 100644 index 0000000..9817c1b --- /dev/null +++ b/docs/panache.adoc @@ -0,0 +1 @@ +## The Basics diff --git a/docs/runlocal.sh b/docs/runlocal.sh new file mode 100755 index 0000000..01da4f0 --- /dev/null +++ b/docs/runlocal.sh @@ -0,0 +1,11 @@ +#!/bin/bash -x + +docker run -it --rm -p 8080:8080 -v $(pwd):/app-data \ + -e CONTENT_URL_PREFIX="file:///app-data" \ + -e WORKSHOPS_URLS="file:///app-data/_workshop.yml" \ + -e LOG_TO_STDOUT=true \ + -e ROUTE_SUBDOMAIN=".route.subdomain.com" \ + -e MASTER_URL="https://master.url.com:8443" \ + -e CHE_URL="http://che-che.master.com" \ + quay.io/osevg/workshopper + diff --git a/docs/testing.adoc b/docs/testing.adoc new file mode 100644 index 0000000..9817c1b --- /dev/null +++ b/docs/testing.adoc @@ -0,0 +1 @@ +## The Basics diff --git a/docs/tracing.adoc b/docs/tracing.adoc new file mode 100644 index 0000000..9817c1b --- /dev/null +++ b/docs/tracing.adoc @@ -0,0 +1 @@ +## The Basics diff --git a/setup/htpass.yaml b/setup/htpass.yaml new file mode 100644 index 0000000..08047c3 --- /dev/null +++ b/setup/htpass.yaml @@ -0,0 +1,8 @@ +spec.identityProviders[+]: + name: htpassidp + type: HTPasswd + mappingMethod: claim + htpasswd: + fileData: + name: workshop-user-secret + diff --git a/setup/preparelab.sh b/setup/preparelab.sh new file mode 100755 index 0000000..3ec4267 --- /dev/null +++ b/setup/preparelab.sh @@ -0,0 +1,210 @@ +#!/bin/bash +# +# Prereqs: a running ocp 4 cluster, logged in as kubeadmin +# +MYDIR="$( cd "$(dirname "$0")" ; pwd -P )" +function usage() { + echo "usage: $(basename $0) [-c/--count usercount] -a/--admin-password admin_password" +} + +# Defaults +USERCOUNT=10 +ADMIN_PASSWORD= + +POSITIONAL=() +while [[ $# -gt 0 ]] +do +key="$1" + +case $key in + -c|--count) + USERCOUNT="$2" + shift # past argument + shift # past value + ;; + -a|--admin-pasword) + ADMIN_PASSWORD="$2" + shift # past argument + shift # past value + ;; + *) # unknown option + echo "Unknown option: $key" + usage + exit 1 + ;; +esac +done +set -- "${POSITIONAL[@]}" # restore positional parameters +echo "USERCOUNT: $USERCOUNT" +echo "ADMIN_PASSWORD: $ADMIN_PASSWORD" + +if [ -z "$ADMIN_PASSWORD" ] ; then + echo "Admin password (-a) required" + usage + exit 1 +fi + +if [ ! "$(oc get clusterrolebindings)" ] ; then + echo "not cluster-admin" + exit 1 +fi + +# get routing suffix +TMP_PROJ="dummy-$RANDOM" +oc new-project $TMP_PROJ +oc create route edge dummy --service=dummy --port=8080 -n $TMP_PROJ +ROUTE=$(oc get route dummy -o=go-template --template='{{ .spec.host }}' -n $TMP_PROJ) +HOSTNAME_SUFFIX=$(echo $ROUTE | sed 's/^dummy-'${TMP_PROJ}'\.//g') +oc delete project $TMP_PROJ +MASTER_URL=$(oc whoami --show-server) + +# create users +TMPHTPASS=$(mktemp) +for i in {1..$USERCOUNT} ; do + htpasswd -b ${TMPHTPASS} "user$i" "pass$i" +done + +# Add openshift cluster admin user +htpasswd -b ${TMPHTPASS} admin "${ADMIN_PASSWORD}" + +# Create user secret in OpenShift +! oc -n openshift-config delete secret workshop-user-secret +oc -n openshift-config create secret generic workshop-user-secret --from-file=htpasswd=${TMPHTPASS} +rm -f ${TMPHTPASS} + +# Set the users to OpenShift OAuth +oc -n openshift-config get oauth cluster -o yaml | \ + yq d - spec.identityProviders | \ + yq w - -s ${MYDIR}/htpass.yaml | \ + oc apply -f - + +# sleep for 30 seconds for the pods to be restarted +echo "Wait for 30s for new OAuth to take effect" +sleep 30 + +# Make the admin as cluster admin +oc adm policy add-cluster-role-to-user cluster-admin admin + +# create projects for users +for i in {1..$USERCOUNT} ; do + PROJ="user${i}-project" + oc new-project $PROJ --display-name="Working Project for user${i}" >&- && \ + oc label namespace $PROJ quarkus-workshop=true && \ + oc adm policy add-role-to-user admin user${i} -n $PROJ +done + +# deploy guides +oc new-project guides +oc new-app quay.io/osevg/workshopper --name=web \ + -e ROUTE_SUBDOMAIN=${HOSTNAME_SUFFIX} \ + -e MASTER_URL=${MASTER_URL} \ + -e CHE_URL=http://codeready-che.${ROUTE_SUBDOMAIN} \ + -e WORKSHOPS_URLS="https://raw.githubusercontent.com/openshift-evangelists/workshopper-template/master/_workshop.yml" \ + -e LOG_TO_STDOUT=true +oc expose svc/web + +# Install Che +oc new-project che +cat < $HOME/.curlrc \ No newline at end of file