Skip to content

Topic

Topic manages a single administrative topic object (MQSC TOPIC) on an existing IBM MQ queue manager. It defines the topic node's topic string and its publish/subscribe access and scope; the operator reconciles the desired attributes through mqweb and reports drift via status conditions. It does not create the queue manager itself, nor does it manage subscriptions.

  • API group/version: messaging.mkurator.dev/v1beta1 (also served as v1alpha1 via the conversion webhook — see Custom resources).
  • Short name: tp (kubectl get tp).
  • Scope: namespaced; spec.connectionRef resolves in the same namespace (ADR-0023).

Examples

An administrative topic with a topic string and free-form attributes:

apiVersion: messaging.mkurator.dev/v1beta1
kind: Topic
metadata:
  name: retail-orders
  namespace: mkurator-system
spec:
  connectionRef:
    name: qm1
  topicName: RETAIL.ORDERS
  topicString: retail/orders
  description: Retail order events topic
  publish: enabled
  subscribe: enabled

The same object can be expressed with the free-form spec.attributes map (topstr, descr, pub, sub) instead of the typed fields — see config/samples/. A typed field and its matching attribute key are mutually exclusive for the same MQSC attribute (admission rejects setting both).

Fields

API version: messaging.mkurator.dev/v1beta1 · Kind: Topic

.spec

Field Type Required Description
adoptionPolicy enum(Adopt, AdoptIfMatching, FailIfExists) no AdoptionPolicy controls behaviour when the MQ object already exists on first reconcile.
attributes map[string]string no Attributes map to MQSC parameters (lowercase keys in mqweb runCommandJSON). Drift-checked vs define-only keys: docs/ATTRIBUTE_RECONCILIATION.md.
connectionRef object yes ConnectionRef names a QueueManagerConnection in the same namespace.
connectionRef.name string yes —
defPersistence enum(yes, no) no DefPersistence is the default message persistence for new messages (MQSC DEFPSIST). Mutually exclusive with attributes.defpsist; typed field takes precedence when folded into the attribute map for mqadmin.
deletionPolicy enum(Delete, Orphan) no DeletionPolicy controls MQ cleanup when the CR is deleted.
description string no Description is the topic description (MQSC DESCR). Mutually exclusive with attributes.descr; typed field takes precedence when folded into the attribute map for mqadmin.
publish enum(enabled, disabled) no Publish controls whether applications may publish to the topic (MQSC PUB). Mutually exclusive with attributes.pub; typed field takes precedence when folded into the attribute map for mqadmin.
publishScope string no PublishScope is the publish scope for the topic (MQSC PUBSCOPE). Mutually exclusive with attributes.pubscope; typed field takes precedence when folded into the attribute map for mqadmin.
subscribe enum(enabled, disabled) no Subscribe controls whether applications may subscribe to the topic (MQSC SUB). Mutually exclusive with attributes.sub; typed field takes precedence when folded into the attribute map for mqadmin.
subscribeScope string no SubscribeScope is the subscribe scope for the topic (MQSC SUBSCOPE). Mutually exclusive with attributes.subscope; typed field takes precedence when folded into the attribute map for mqadmin.
suspend boolean no Suspend pauses MQ reconciliation for this object. Status shows Synced=False ReasonSuspended.
topicName string yes TopicName is the IBM MQ topic object name (e.g. RETAIL.ORDERS).
topicString string no TopicString is the IBM MQ topic string (MQSC TOPICSTR / attribute topstr). Mutually exclusive with attributes.topstr and attributes.topicstr; typed field takes precedence when folded into the attribute map for mqadmin.

.status

Field Type Required Description
conditions []object no Conditions represent the current state of the topic.
desiredMQSC string no DesiredMQSC is a debug/GitOps aid: the DEFINE TOPIC REPLACE line equivalent to what the operator applies via mqweb. Not authoritative; do not use this field to drive cluster apply or drift detection.
lastSyncTime string no LastSyncTime is set when the object last reconciled successfully.
message string no Message is a short, user-facing summary of reconcile state (especially when Synced=False).
mqObjectExists boolean no MQObjectExists is true when the IBM MQ object was last observed on the queue manager.
observedGeneration integer no ObservedGeneration reflects the generation last successfully synced.

MQSC mapping and drift

Typed fields fold into MQSC attributes; anything without a typed field can be set through the free-form spec.attributes map. The operator drift-checks the attributes it manages and re-applies on divergence. The full per-attribute matrix — including which DISPLAY capabilities are probed at runtime — lives in ATTRIBUTE_RECONCILIATION.md.

Typed field MQSC attribute Notes
topicString TOPICSTR (topstr) The topic node's topic string
description DESCR (descr) Free-text topic description
publish PUB (pub) enabled / disabled publish access
subscribe SUB (sub) enabled / disabled subscribe access
defPersistence DEFPSIST (defpsist) Default persistence for published messages
publishScope PUBSCOPE (pubscope) Publish scope (queue manager / all)
subscribeScope SUBSCOPE (subscope) Subscribe scope (queue manager / all)

Typed field and matching attributes key are mutually exclusive for the same MQSC attribute; admission rejects setting both (ADR-0021, ADR-0025).

See also