SupportConsoleDevelopersStart a trialContact

Chapter 2. Planning a deployment of AMQ Broker on OpenShift Container Platform

This section describes how to plan an Operator-based deployment.

Operators are programs that enable you to package, deploy, and manage OpenShift applications. Often, Operators automate common or complex tasks. Commonly, Operators are intended to provide:

  • Consistent, repeatable installations
  • Health checks of system components
  • Over-the-air (OTA) updates
  • Managed upgrades

Operators enable you to make changes while your broker instances are running, because they are always listening for changes to the Custom Resource (CR) instances that you used to configure your deployment. When you make changes to a CR, the Operator reconciles the changes with the existing broker deployment and updates the deployment to reflect the changes. In addition, the Operator provides a message migration capability, which ensures the integrity of messaging data. When a broker in a clustered deployment shuts down due to failure or intentional scaledown of the deployment, this capability migrates messages to a broker Pod that is still running in the same broker cluster.

2.1. Overview of the AMQ Broker Operator Custom Resource Definitions

In general, a Custom Resource Definition (CRD) is a schema of configuration items that you can modify for a custom OpenShift object deployed with an Operator. By creating a corresponding Custom Resource (CR) instance, you can specify values for configuration items in the CRD. If you are an Operator developer, what you expose through a CRD essentially becomes the API for how a deployed object is configured and used. You can directly access the CRD through regular HTTP curl commands, because the CRD gets exposed automatically through Kubernetes.

You can install the AMQ Broker Operator using either the OpenShift command-line interface (CLI), or the Operator Lifecycle Manager, through the OperatorHub graphical interface. In either case, the AMQ Broker Operator includes the CRDs described below.

Main broker CRD

You deploy a CR instance based on this CRD to create and configure a broker deployment.

Based on how you install the Operator, this CRD is:

  • The broker_activemqartemis_crd file in the crds directory of the Operator installation archive (OpenShift CLI installation method)
  • The ActiveMQArtemis CRD in the Custom Resource Definitions section of the OpenShift Container Platform web console (OperatorHub installation method)
Address CRD

You deploy a CR instance based on this CRD to create addresses and queues for a broker deployment.

Based on how you install the Operator, this CRD is:

  • The broker_activemqartemisaddress_crd file in the crds directory of the Operator installation archive (OpenShift CLI installation method)
  • The ActiveMQArtemisAddresss CRD in the Custom Resource Definitions section of the OpenShift Container Platform web console (OperatorHub installation method)
Security CRD

You deploy a CR instance based on this CRD to create users and associate those users with security contexts.

Based on how you install the Operator, this CRD is:

  • The broker_activemqartemissecurity_crd file in the crds directory of the Operator installation archive (OpenShift CLI installation method)
  • The ActiveMQArtemisSecurity CRD in the Custom Resource Definitions section of the OpenShift Container Platform web console (OperatorHub installation method).
Scaledown CRD

The Operator automatically creates a CR instance based on this CRD when instantiating a scaledown controller for message migration.

Based on how you install the Operator, this CRD is:

  • The broker_activemqartemisscaledown_crd file in the crds directory of the Operator installation archive (OpenShift CLI installation method)
  • The ActiveMQArtemisScaledown CRD in the Custom Resource Definitions section of the OpenShift Container Platform web console (OperatorHub installation method).

Additional resources

2.2. Overview of the AMQ Broker Operator sample Custom Resources

The AMQ Broker Operator archive that you download and extract during installation includes sample Custom Resource (CR) files in the deploy/crs directory. These sample CR files enable you to:

  • Deploy a minimal broker without SSL or clustering.
  • Define addresses.

The broker Operator archive that you download and extract also includes CRs for example deployments in the deploy/examples directory, as listed below.

artemis-basic-deployment.yaml
Basic broker deployment.
artemis-persistence-deployment.yaml
Broker deployment with persistent storage.
artemis-cluster-deployment.yaml
Deployment of clustered brokers.
artemis-persistence-cluster-deployment.yaml
Deployment of clustered brokers with persistent storage.
artemis-ssl-deployment.yaml
Broker deployment with SSL security.
artemis-ssl-persistence-deployment.yaml
Broker deployment with SSL security and persistent storage.
artemis-aio-journal.yaml
Use of asynchronous I/O (AIO) with the broker journal.
address-queue-create.yaml
Address and queue creation.

2.3. Watch options for a Cluster Operator deployment

When the Cluster Operator is running, it starts to watch for updates of AMQ Broker custom resources (CRs).

You can choose to deploy the Cluster Operator to watch CRs from:

  • A single namespace (the same namespace containing the Operator)
  • All namespaces
Note

If you have already installed a previous version of the AMQ Broker Operator in a namespace on your cluster, Red Hat recommends that you do not install the AMQ Broker Operator 7.9 version to watch that namespace to avoid potential conflicts.

2.4. How the Operator chooses container images

When you create a Custom Resource (CR) instance for a broker deployment based on at least version 7.9.4-opr-3 of the Operator, you do not need to explicitly specify broker or Init Container image names in the CR. By default, if you deploy a CR and do not explicitly specify container image values, the Operator automatically chooses the appropriate container images to use.

Note

If you install the Operator using the OpenShift command-line interface, the Operator installation archive includes a sample CR file called broker_activemqartemis_cr.yaml. In the sample CR, the spec.deploymentPlan.image property is included and set to its default value of placeholder. This value indicates that the Operator does not choose a broker container image until you deploy the CR.

The spec.deploymentPlan.initImage property, which specifies the Init Container image, is not included in the broker_activemqartemis_cr.yaml sample CR file. If you do not explicitly include the spec.deploymentPlan.initImage property in your CR and specify a value, the Operator chooses an appropriate built-in Init Container image to use when you deploy the CR.

How the Operator chooses these images is described in this section.

To choose broker and Init Container images, the Operator first determines an AMQ Broker version to which the images should correspond. The Operator determines the version as follows:

  • If the spec.upgrades.enabled property in the main CR is already set to true and the spec.version property specifies 7.7.0, 7.8.0, 7.8.1, or 7.8.2, the Operator uses that specified version.
  • If spec.upgrades.enabled is not set to true, or spec.version is set to an AMQ Broker version earlier than 7.7.0, the Operator uses the latest version of AMQ Broker (that is, 7.9.4).

The Operator then detects your container platform. The AMQ Broker Operator can run on the following container platforms:

  • OpenShift Container Platform (x86_64)
  • OpenShift Container Platform on IBM Z (s390x)
  • OpenShift Container Platform on IBM Power Systems (ppc64le)

Based on the version of AMQ Broker and your container platform, the Operator then references two sets of environment variables in the operator.yaml configuration file. These sets of environment variables specify broker and Init Container images for various versions of AMQ Broker, as described in the following sub-sections.

2.4.1. Environment variables for broker container images

The environment variables included in the operator.yaml configuration file for broker container images have the following naming convention:

OpenShift Container Platform
RELATED_IMAGE_ActiveMQ_Artemis_Broker_Kubernetes_<AMQ_Broker_version_identifier>
OpenShift Container Platform on IBM Z
RELATED_IMAGE_ActiveMQ_Artemis_Broker_Kubernetes_<AMQ_Broker_version_identifier>_s390x
OpenShift Container Platform on IBM Power Systems
RELATED_IMAGE_ActiveMQ_Artemis_Broker_Kubernetes_<AMQ_Broker_version_identifier>_ppc64le

Environment variable names for each supported container platform and specific AMQ Broker versions are shown in the table.

Container platformEnvironment variable names

OpenShift Container Platform

  • RELATED_IMAGE_ActiveMQ_Artemis_Broker_Kubernetes_781
  • RELATED_IMAGE_ActiveMQ_Artemis_Broker_Kubernetes_782
  • RELATED_IMAGE_ActiveMQ_Artemis_Broker_Kubernetes_790

OpenShift Container Platform on IBM Z

  • RELATED_IMAGE_ActiveMQ_Artemis_Broker_Kubernetes_781_s390x
  • RELATED_IMAGE_ActiveMQ_Artemis_Broker_Kubernetes_782_s390x
  • RELATED_IMAGE_ActiveMQ_Artemis_Broker_Kubernetes_790_s390x

OpenShift Container Platform on IBM Power Systems

  • RELATED_IMAGE_ActiveMQ_Artemis_Broker_Kubernetes_781_ppc64le
  • RELATED_IMAGE_ActiveMQ_Artemis_Broker_Kubernetes_782_ppc64le
  • RELATED_IMAGE_ActiveMQ_Artemis_Broker_Kubernetes_790_ppc64le

The value of each environment variable specifies a broker container image that is available from Red Hat. For example: 

- name: RELATED_IMAGE_ActiveMQ_Artemis_Broker_Kubernetes_790
  #value: registry.redhat.io/amq7/amq-broker-rhel8:7.9
  value: registry.redhat.io/amq7/amq-broker-rhel8@sha256:71aef8faa1c661212ef8a7ef450656a250d95b51d33d1ce77f12ece27cdb9442

Therefore, based on an AMQ Broker version and your container platform, the Operator determines the applicable environment variable name. The Operator uses the corresponding image value when starting the broker container.

Note

In the operator.yaml file, the Operator uses an image that is represented by a Secure Hash Algorithm (SHA) value. The comment line, which begins with a number sign (#) symbol, denotes that the SHA value corresponds to a specific container image tag.

2.4.2. Environment variables for Init Container images

The environment variables included in the operator.yaml configuration file for Init Container images have the following naming convention:

RELATED_IMAGE_ActiveMQ_Artemis_Broker_Init_<AMQ_Broker_version_identifier>

Environment variable names for specific AMQ Broker versions are listed below.

  • RELATED_IMAGE_ActiveMQ_Artemis_Broker_Init_781
  • RELATED_IMAGE_ActiveMQ_Artemis_Broker_Init_782
  • RELATED_IMAGE_ActiveMQ_Artemis_Broker_Init_790

The value of each environment variable specifies an Init Container image that is available from Red Hat. For example: 

- name: RELATED_IMAGE_ActiveMQ_Artemis_Broker_Init_790
  #value: registry.redhat.io/amq7/amq-broker-init-rhel8:0.4-21
  value: registry.redhat.io/amq7/amq-broker-init-rhel8@sha256:d327d358e6cfccac14becc486bce643e34970ecfc6c4d187a862425867a9ac8a

Therefore, based on an AMQ Broker version, the Operator determines the applicable environment variable name. The Operator uses the corresponding image value when starting the Init Container.

Note

As shown in the example, the Operator uses an image that is represented by a Secure Hash Algorithm (SHA) value. The comment line, which begins with a number sign (#) symbol, denotes that the SHA value corresponds to a specific container image tag. Observe that the corresponding container image tag is not a floating tag in the form of 0.4-21. This means that the container image used by the Operator remains fixed. The Operator does not automatically pull and use a new micro image version (that is, 0.4-21-n, where n is the latest micro version) when it becomes available from Red Hat.

The environment variables included in the operator.yaml configuration file for Init Container images have the following naming convention:

OpenShift Container Platform
RELATED_IMAGE_ActiveMQ_Artemis_Broker_Init_<AMQ_Broker_version_identifier>
OpenShift Container Platform on IBM Z
RELATED_IMAGE_ActiveMQ_Artemis_Broker_Init_s390x_<AMQ_Broker_version_identifier>
OpenShift Container Platform on IBM Power Systems
RELATED_IMAGE_ActiveMQ_Artemis_Broker_Init_ppc64le_<AMQ_Broker_version_identifier>

Environment variable names for each supported container platform and specific AMQ Broker versions are shown in the table.

Container platformEnvironment variable names

OpenShift Container Platform

  • RELATED_IMAGE_ActiveMQ_Artemis_Broker_Init_781
  • RELATED_IMAGE_ActiveMQ_Artemis_Broker_Init_782
  • RELATED_IMAGE_ActiveMQ_Artemis_Broker_Init_790

OpenShift Container Platform on IBM Z

  • RELATED_IMAGE_ActiveMQ_Artemis_Broker_Init_s390x_781
  • RELATED_IMAGE_ActiveMQ_Artemis_Broker_Init_s390x_782
  • RELATED_IMAGE_ActiveMQ_Artemis_Broker_Init_s390x_790

OpenShift Container Platform on IBM Power Systems

  • RELATED_IMAGE_ActiveMQ_Artemis_Broker_Init_ppc64le_781
  • RELATED_IMAGE_ActiveMQ_Artemis_Broker_Init_ppc64le_782
  • RELATED_IMAGE_ActiveMQ_Artemis_Broker_Init_ppc64le_790

The value of each environment variable specifies an Init Container image that is available from Red Hat. For example: 

- name: RELATED_IMAGE_ActiveMQ_Artemis_Broker_Init_790
  #value: registry.redhat.io/amq7/amq-broker-init-rhel8:0.4-21-1
  value: registry.redhat.io/amq7/amq-broker-init-rhel8@sha256:d327d358e6cfccac14becc486bce643e34970ecfc6c4d187a862425867a9ac8a

Therefore, based on an AMQ Broker version and your container platform, the Operator determines the applicable environment variable name. The Operator uses the corresponding image value when starting the Init Container.

Note

As shown in the example, the Operator uses an image that is represented by a Secure Hash Algorithm (SHA) value. The comment line, which begins with a number sign (#) symbol, denotes that the SHA value corresponds to a specific container image tag. Observe that the corresponding container image tag is not a floating tag in the form of 0.4-21. This means that the container image used by the Operator remains fixed. The Operator does not automatically pull and use a new micro image version (that is, 0.4-21-n, where n is the latest micro version) when it becomes available from Red Hat.

Additional resources

2.5. Operator deployment notes

This section describes some important considerations when planning an Operator-based deployment

  • Deploying the Custom Resource Definitions (CRDs) that accompany the AMQ Broker Operator requires cluster administrator privileges for your OpenShift cluster. When the Operator is deployed, non-administrator users can create broker instances via corresponding Custom Resources (CRs). To enable regular users to deploy CRs, the cluster administrator must first assign roles and permissions to the CRDs. For more information, see Creating cluster roles for Custom Resource Definitions in the OpenShift Container Platform documentation.
  • When you update your cluster with the CRDs for the latest Operator version, this update affects all projects in the cluster. Any broker Pods deployed from previous versions of the Operator might become unable to update their status. When you click the Logs tab of a running broker Pod in the OpenShift Container Platform web console, you see messages indicating that 'UpdatePodStatus' has failed. However, the broker Pods and Operator in that project continue to work as expected. To fix this issue for an affected project, you must also upgrade that project to use the latest version of the Operator.

  • While you can create more than one broker deployment in a given OpenShift project by deploying multiple Custom Resource (CR) instances, typically, you create a single broker deployment in a project, and then deploy multiple CR instances for addresses.

    Red Hat recommends you create broker deployments in separate projects.

  • If you intend to deploy brokers with persistent storage and do not have container-native storage in your OpenShift cluster, you need to manually provision Persistent Volumes (PVs) and ensure that these are available to be claimed by the Operator. For example, if you want to create a cluster of two brokers with persistent storage (that is, by setting persistenceEnabled=true in your CR), you need to have two persistent volumes available. By default, each broker instance requires storage of 2 GiB.

    If you specify persistenceEnabled=false in your CR, the deployed brokers uses ephemeral storage. Ephemeral storage means that that every time you restart the broker Pods, any existing data is lost.

    For more information about provisioning persistent storage in OpenShift Container Platform, see:

  • You must add configuration for the items listed below to the main broker CR instance before deploying the CR for the first time. You cannot add configuration for these items to a broker deployment that is already running.

The procedures in the next section show you how to install the Operator and use Custom Resources (CRs) to create broker deployments on OpenShift Container Platform. When you have successfully completed the procedures, you will have the Operator running in an individual Pod. Each broker instance that you create will run as an individual Pod in a StatefulSet in the same project as the Operator. Later, you will you will see how to use a dedicated addressing CR to define addresses in your broker deployment.

Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.