From d1a0b74b12d685967e2c2cde8334e590301c337b Mon Sep 17 00:00:00 2001 From: Miroslav Novak Date: Wed, 4 Dec 2024 15:31:37 +0100 Subject: [PATCH] [#697] Add guide for deploying WildFly messaging application with AMQ 7 on OpenShift --- _data/guides.yaml | 3 + ...messaging-high-availability-openshift.adoc | 254 ++++++++++++++++++ 2 files changed, 257 insertions(+) create mode 100644 guides/messaging-high-availability-openshift.adoc diff --git a/_data/guides.yaml b/_data/guides.yaml index 0f7adaaa..845867f4 100644 --- a/_data/guides.yaml +++ b/_data/guides.yaml @@ -61,6 +61,9 @@ categories: - title: Configuring High Availability Messaging in WildFly url: /guides/messaging-high-availability description: Learn how to configure two WildFly servers with messaging (ActiveMQ Artemis broker) in a high availability topology using a shared journal. + - title: Deploying High-Availability Messaging with WildFly and AMQ 7 on OpenShift + url: /guides/messaging-high-availability-openshift + description: Discover how to configure WildFly with AMQ 7 (ActiveMQ Artemis) on OpenShift, using a clustered, high-availability topology for reliable messaging. - category: MicroProfile cat-id: microprofile guides: diff --git a/guides/messaging-high-availability-openshift.adoc b/guides/messaging-high-availability-openshift.adoc new file mode 100644 index 00000000..39fe71a3 --- /dev/null +++ b/guides/messaging-high-availability-openshift.adoc @@ -0,0 +1,254 @@ += Deploying High-Availability Messaging with WildFly and AMQ 7 on OpenShift +:summary: Discover how to configure WildFly with AMQ 7 (ActiveMQ Artemis) on OpenShift, using a clustered, high-availability topology for reliable messaging. +:includedir: _includes +include::{includedir}/_attributes.adoc[] +:prerequisites-time: 20 + +In this guide you will learn how to configure WildFly server connected to remote AMQ 7 cluster on OpenShift using operators. + +include::{includedir}/_prerequisites.adoc[] +* Access to an OpenShift cluster (try the "Self-managed" variant of local development machine https://developers.redhat.com/products/openshift/download[Red Hat OpenShift +] for free) +* https://docs.openshift.com/container-platform/{ocp-version}/cli_reference/openshift_cli/getting-started-cli.html[OpenShift CLI] tool + +// login to OpenShift cluster +include::{includedir}/_proc-log-into-openshift-cluster.adoc[] + +== Install and deploy AMQ 7 using operator + +To install the AMQ 7 Operator, follow the instructions in the Red Hat documentation: https://access.redhat.com/documentation/en-us/red_hat_amq_broker/7.11/html-single/deploying_amq_broker_on_openshift/index#proc-br-installing-operator-to-project-from-operatorhub_broker-ocp[Installing the Operator using OperatorHub] + +Next, create a file named `broker.yaml` with the following content to deploy the AMQ 7 cluster: +[source, yaml] +---- +apiVersion: broker.amq.io/v1beta1 +kind: ActiveMQArtemis +metadata: + name: amq-broker + application: amq-broker-app +spec: + acceptors: + - name: acceptor + protocols: core,amqp + port: 61616 + sslEnabled: false + enabledProtocols: TLSv1,TLSv1.1,TLSv1.2 + needClientAuth: true + wantClientAuth: true + verifyHost: true + sslProvider: JDK + sniHost: localhost + expose: true + anycastPrefix: jms.queue. + multicastPrefix: /topic/ + console: + expose: true + deploymentPlan: + journalType: nio + messageMigration: true + persistenceEnabled: true + requireLogin: false + size: 2 + storage: + size: "1Gi" + upgrades: + enabled: false + minor: false +---- + +This Custom Resource (CR) file configures an AMQ 7 cluster with two brokers deployed as a StatefulSet. This setup ensures +high availability because, in the event of a pod failure, the StatefulSet will automatically restart the failed pod. +However, to maintain data integrity, Persistent Volumes must be configured to store the messaging journal. Without them, +messages will be lost during restarts. + +Additionally, the `messageMigration: true` setting enables the graceful scaling down of AMQ 7 pods. This ensures that messages +from the scaled-down node are migrated to another node in the cluster, preventing data loss. + +Run following command to deploy AMQ 7 on OpenShift: +[source, shell] +---- +oc create -f broker.yaml +---- + +Check that AMQ 7 broker is in `Running` state by checking running pods: + +[source, bash ,options="nowrap"] +---- +$ oc get pods +NAME READY STATUS RESTARTS AGE +amq-broker-ss-0 1/1 Running 0 35m +amq-broker-ss-1 1/1 Running 0 36m +... +---- + +== Build WildFly with messaging application image using WildFly Maven Plugin + +We're going to use the https://github.com/wildfly/quickstart/tree/main/remote-helloworld-mdb[WildFly Quickstart: remote-helloworld-mdb] +to demonstrate how to build a trimmed WildFly server with a deployed messaging application. This quickstart leverages the WildFly Maven plugin +to create a trimmed WildFly server and deploy the `remote-helloworld-mdb.war` application. It then produces a new container image based on +the quay.io/wildfly/wildfly-runtime:latest[WildFly Runtime Image], incorporating the application. + +This quickstart includes a `HelloWorldMDBServletClient` servlet, which sends messages to the `HELLOWORLDMDBQueue` queue, +and a `HelloWorldQueueMDB` message-driven bean (MDB) that consumes messages from this queue. + +To build the https://github.com/wildfly/quickstart/tree/main/remote-helloworld-mdb[remote-helloworld-mdb] quickstart, +execute the following commands: +[source, bash, options="nowrap"] +---- +git clone git@github.com:wildfly/quickstart.git +cd quickstart/remote-helloworld-mdb +mvn clean package wildfly:image -Popenshift +---- + +There is used `openshift` profile which provides additional configuration for WildFly server to work correctly on Openshift +environment. Maven goal `wildfly:image` instructs WildFly Maven Plugin to build a container image. + +You can verify newly built image by running: +[source, bash, options="nowrap"] +---- +$ podman images +REPOSITORY TAG IMAGE ID CREATED SIZE +localhost/remote-helloworld-mdb latest cf9a174a5311 14 minutes ago 621 MB +... +---- + +=== Push WildFly image to OpenShift registry + +We need to expose created image in the registry, so it can be later referenced from Custom Resource for WildFly operator. +We can utilize integrated OpenShift registry and push the image into it through the ImageStream. First crate new +ImageStream in your namespace: +[source, bash, options="nowrap"] +---- +oc create imagestream remote-helloworld-mdb +---- + +Now push your image into the ImageStream: + +[source, bash, options="nowrap"] +---- +export REGISTRY="$(oc get routes -n openshift-image-registry default-route -o=jsonpath='{.spec.host}')" +podman login --tls-verify=false -u admin -p $(oc whoami -t) $REGISTRY +podman tag localhost/remote-helloworld-mdb $REGISTRY/$(oc config view --minify -o jsonpath='{..namespace}' +)/remote-helloworld-mdb +podman push --tls-verify=false $REGISTRY/$(oc config view --minify -o jsonpath='{..namespace}' +)/remote-helloworld-mdb +---- + +=== Install WildFly operator + +First we need to install WildFly operator to OpenShift cluster. Because WildFly operator is not part of OpenShift OperatorHub +by default, we need to add it first. Create file `community-catalog-source.yaml` with content: +[source, yaml, options="nowrap"] +---- +apiVersion: operators.coreos.com/v1alpha1 +kind: CatalogSource +metadata: +name: operatorhubio-catalog +namespace: openshift-marketplace +spec: +displayName: Community Operators +grpcPodConfig: +securityContextConfig: restricted +image: quay.io/operatorhubio/catalog:latest +publisher: OperatorHub.io +sourceType: grpc +updateStrategy: +registryPoll: +interval: 60m +---- + +Execute the following command to add the community catalog to the OperatorHub: + +[source, bash, options="nowrap"] +---- +oc apply -f community-catalog-source.yaml +---- + +You can now install the WildFly Operator using the `wildfly-operator.yml` file: + +[source, yaml, options="nowrap"] +---- +apiVersion: operators.coreos.com/v1alpha1 +kind: Subscription +metadata: + name: subscription-wildfly-operator +spec: + channel: alpha + installPlanApproval: Automatic + name: wildfly-operator + source: operatorhubio-catalog + sourceNamespace: openshift-marketplace +---- + +and install it by: + +[source, bash, options="nowrap"] +---- +oc apply -f wildfly-operator.yml +---- + +Now you should the installed operator in your namespace. + +=== Deploy application image using WildFly operator + +We can now configure the WildFly Operator to deploy a WildFly image with the messaging application. To do this, we need +to specify the location of the AMQ 7 broker by setting the environment variables +`JBOSS_MESSAGING_CONNECTOR_HOST` and `JBOSS_MESSAGING_CONNECTOR_PORT`: + +[source, yaml, options="nowrap"] +---- +apiVersion: wildfly.org/v1alpha1 +kind: WildFlyServer +metadata: + name: wildfly-remote-activemq +spec: + applicationImage: "remote-helloworld-mdb:latest" + replicas: 1 + env: + - name: JBOSS_MESSAGING_CONNECTOR_HOST + value: amq-broker-acceptor-0-svc + - name: JBOSS_MESSAGING_CONNECTOR_PORT + value: '61616' +---- + +=== Test the Application + +We're going to test the application by sending 5 messages to the `HELLOWORLDMDBQueue` to AMQ 7 broker by using servlet and will check that MDB consumed those messages from this queue: +[source, bash, options="nowrap"] +---- +curl http://$(oc get route wildfly-remote-activemq-route --template='{{ .spec.host }}')/remote-helloworld-mdb +---- + +This will invoke the servlet to send messages to the `HelloWorldMDBServletClient`. Check the server logs of both servers to ensure they contain entries similar to the following: +[source, bash, options="nowrap"] +... +14:54:32,439 INFO [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (Thread-19 (ActiveMQ-client-global-threads)) Received Message from queue: This is message 2 +14:54:32,447 INFO [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (Thread-19 (ActiveMQ-client-global-threads)) Received Message from queue: This is message 3 +... +---- + +The presence of these log entries in the server log confirms that messages were successfully load balanced. + +== What's Next? + +Now that you have deployed WildFly with a messaging application connected to AMQ 7, explore the following resources to enhance your understanding and further extend your deployment: + +- *Deploying AMQ Broker on OpenShift*: Dive deeper into deploying and managing AMQ Broker on OpenShift with detailed guides and best practices. +https://docs.redhat.com/en/documentation/red_hat_amq/7.7/html-single/deploying_amq_broker_on_openshift/index[Deploying AMQ Broker on OpenShift] + +- *WildFly Operator Repository*: Learn more about the WildFly Operator, its features, and advanced configuration options directly from the official GitHub repository. +https://github.com/wildfly/wildfly-operator[WildFly Operator GitHub] + +- *WildFly Maven Plugin Documentation*: Explore the WildFly Maven Plugin for automating deployment, configuration, and management of WildFly applications during your build process. +https://docs.wildfly.org/wildfly-maven-plugin/releases/5.0/[WildFly Maven Plugin Documentation] + +These resources provide valuable insights and tools to optimize your WildFly and AMQ deployments, automate workflows, and build robust applications on OpenShift. + +[[references]] +== References + +* https://github.com/wildfly/wildfly-operator[WildFly Operator GitHub] +* https://docs.redhat.com/en/documentation/red_hat_amq/7.7/html-single/deploying_amq_broker_on_openshift/index[Deploying AMQ Broker on OpenShift] +* https://docs.wildfly.org/wildfly-maven-plugin/releases/5.0/[WildFly Maven Plugin Documentation] +* https://activemq.apache.org/components/artemis/documentation/latest/clusters.html#overview[Apache ActiveMQ Artemis Documentation - Clusters] +* https://docs.redhat.com/en/documentation/red_hat_jboss_enterprise_application_platform/7.4/html-single/configuring_messaging/index#clusters_overview[EAP 7.4 Messaging Clusters Overview].