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

• If persistent storage is enabled on AMQ Broker, each broker Pod writes its data to a Persistent Volume (PV) that was claimed by using a Persistent Volume Claim (PVC). A PV remains available even after a Pod is deleted. If a broker Pod fails, OpenShift Container Platform restarts the Pod with the same name and uses the existing PV that contains the messaging data.
• You can run multiple broker Pods in a cluster and distribute Pods on separate nodes to protect against a node failure. In a cluster, each broker Pod writes its message data to its own PV which is then available to that broker Pod if it is restarted on a different node.

Additional resources

• To learn how to install the AMQ Broker Operator (and all included CRDs) using:

  • The OpenShift CLI, see Section 3.2, “Installing the Operator using the CLI”
  • The Operator Lifecycle Manager and OperatorHub graphical interface, see Section 3.3, “Installing the Operator using OperatorHub”.

• For complete configuration references to use when creating CR instances based on the main broker and address CRDs, see:

  • Section 8.1.1, “Broker Custom Resource configuration reference”
  • Section 8.1.2, “Address Custom Resource configuration reference”

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

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

• Specify a version number in the spec.version attribute and allow the Operator to choose the broker and init container images to deploy for that version number.
• Specify the registry URLs of the specific broker and init container images that you want the Operator to deploy in the spec.deploymentPlan.image and spec.deploymentPlan.initImage attributes.
• Set the value of the spec.deploymentPlan.image attribute to placeholder, which means that the Operator chooses the latest broker and init container images that are known to the Operator version.

• The Operator checks if the CR contains a spec.version attribute.

  • If the CR does not contain a spec.version attribute, the Operator checks if the CR contains a spec.deploymentPlan.image and a spec.deployment.Plan.initImage attribute.

    • If the CR contains a spec.deploymentPlan.image and a spec.deployment.Plan.initImage attribute, the Operator deploys the container images that are identified by their registry URLs.
    • If the CR does not contain a spec.deploymentPlan.image and a spec.deployment.Plan.initImage attribute, the Operator chooses the container images to deploy. For more information, see Section 2.6, “How the Operator chooses container images”.

  • If the CR contains a spec.version attribute, the Operator verifies that the version number specified is within the valid range of versions that the Operator supports.

    • If the value of the spec.version attribute is not valid, the Operator stops the deployment.

    • If the value of the spec.version attribute is valid, the Operator checks if the CR contains a spec.deploymentPlan.image and a spec.deployment.Plan.initImage attribute.

      • If the CR contains a spec.deploymentPlan.image and a spec.deployment.Plan.initImage attribute, the Operator deploys the container images that are identified by their registry URLs.
      • If the CR does not contain a spec.deploymentPlan.image and a spec.deployment.Plan.initImage attribute, the Operator chooses the container images to deploy. For more information, see Section 2.6, “How the Operator chooses container images”.

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

• 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:

  • Understanding persistent storage

• 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 size and storage class of the Persistent Volume Claim (PVC) required by each broker in a deployment for persistent storage
  • Limits and requests for memory and CPU for each broker in a deployment
• If you update a parameter in your CR that the Operator is unable to dynamically update in the StatefulSet, the Operator deletes the StatefulSet and recreates it with the updated parameter value. Deleting the StatefulSet causes all pods to be deleted and recreated, which causes a temporary broker outage. An example of a CR update that the Operator cannot dynamically update in the StatefulSet is if you change persistenceEnabled=false to persistenceEnabled=true.