MQ Operator

Hand-written StatefulSet YAML teaches how IBM MQ fits Kubernetes, but production teams on OpenShift and enterprise Kubernetes rarely stop there—they install the IBM MQ Operator so queue managers become declarative custom resources checked into Git, reviewed in pull requests, and reconciled automatically when someone changes storage size or TLS certificates. The operator is a controller process in the cluster that watches QueueManager objects, compares spec to reality, and creates or updates pods, persistent volume claims, services, and certificate resources until status conditions report Ready or surface a clear error. Beginners expect the operator to eliminate MQ expertise; in practice it eliminates boilerplate assembly while you still define channels, queues, authority, and application connectivity. This tutorial covers operator installation sources, the QueueManager CR fields and what each controls, reconciliation and status conditions, storage and version upgrades, integration with cert-manager, differences from raw Helm-only installs, day-two operations like log collection and scaling Native HA roles, and troubleshooting when the CR says Ready but clients still get 2059.

Why an Operator Instead of Raw YAML

Installing the Operator

On OpenShift, install from OperatorHub into a namespace with appropriate permissions; OLM manages subscription channels and CSV upgrades. On Kubernetes, IBM documents Helm-based operator installs or bundled manifests. Pin operator version to MQ queue manager version compatibility table—installing the newest operator against an unsupported QM version fails reconciliation with conditions you must read in kubectl describe queuemanager. Cluster admins need cluster-scoped RBAC to install CRDs; application teams receive namespace-scoped rights to create QueueManager instances.

QueueManager Custom Resource

The spec section names the queue manager, chooses MQ version image, requests CPU and memory, defines storage size and storage class, and enables features such as TLS or metrics per your operator version. status.conditions show Ready, Error, or progressing states. status.version reports running fix pack. Editing spec triggers reconciliation— increasing storage may expand PVC if storage class allows volume expansion. Decreasing storage is usually blocked. Renaming queue manager in spec on existing PVC is destructive—treat name as immutable.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
apiVersion: mq.ibm.com/v1beta1
kind: QueueManager
metadata:
  name: finance-qm
spec:
  version: 9.4.0.0-r1
  license:
    accept: true
  queueManager:
    name: FINANCE
  storage:
    queueManager:
      type: persistent-claim
      size: 100Gi
      class: fast-ssd
  resources:
    requests:
      cpu: "1"
      memory: 1Gi
    limits:
      cpu: "2"
      memory: 2Gi

Reconciliation Loop

When you kubectl apply a QueueManager, the operator observes the change, calculates required child resources, and applies them. If a pod is deleted manually, the operator recreates it to match spec—do not fight the controller without pausing reconciliation. Finalizers may block deletion until queues drain—understand operator deletion policies before kubectl delete in production. Events on the CR and operator pod logs explain most failures.

Explainer: Robot Assistant for MQ Boxes

The operator is a robot that reads a recipe card (the CR) and builds the MQ box (pod plus disk plus wires) exactly as written. If a part falls off, the robot puts it back. You still decide what messages go in which queues—the robot does not write your application logic.

Storage and Native HA

Single-instance QueueManager CR maps to one primary queue manager PVC. Native HA configurations use multiple CRs or HA-specific spec sections per IBM documentation for your operator release—never share one RWO PVC across two active writers. Read IBM architecture for active and replica roles before enabling HA in production.

Certificates and TLS

Operators often integrate cert-manager to issue listener and channel certificates with automatic renewal. Define Issuer or ClusterIssuer cluster-wide; QueueManager spec references certificate secrets mounted into the pod. When certs rotate, channels using SSL must tolerate handshakes during rollover—plan maintenance windows if clients cache trust incorrectly.

Day-Two Operations

1. Backup PVC snapshots and export MQSC or Git definitions on schedule.
2. Upgrade operator channel in OLM during maintenance; then bump QM version in CR.
3. Collect must-gather or operator diagnostics packages for IBM support.
4. Monitor operator pod health—not only QueueManager Ready condition.

Troubleshooting

• CR Error condition — describe CR; check incompatible version or storage class.
• Pod CrashLoop — LICENSE, permissions on /mnt/mqm, or probe too aggressive.
• Clients 2059 — Service or Route hostname wrong; not operator fault alone.
• Stuck Terminating — finalizer waiting for admin action.

Explain Like I'm Five: MQ Operator

The MQ Operator is a helper robot that builds and fixes your MQ toy set whenever you change the instruction card, so you do not have to screw every piece by hand each time.

Practice Exercises

Exercise 1

Install operator in lab; create QueueManager; verify Ready and connect with sample client.

Exercise 2

Describe which child resources exist after CR create (StatefulSet, Service, PVC).

Exercise 3

Simulate cert expiry scenario and document renewal steps for your operator version.

Frequently Asked Questions

Test Your Knowledge