A Kubernetes operator for declaratively managing resources on an existing IBM MQ Queue Manager — queues, topics, channels, channel auth, and authority records — over the mqweb REST API.
Published site: platformrelay.github.io/MKurator
| Goal | Guide |
|---|---|
| First queue in minutes | Quick start |
| Install + connect + day-2 use | Install and use |
| Upgrade / webhook notes | Upgrade |
| Metrics & scraping | Observability |
Important
MKurator manages objects on an IBM MQ queue manager you already run. It does
not deploy or scale queue managers. The target QM must expose mqweb
(Administrative REST) over HTTPS; credentials come from a Kubernetes Secret.
Status: the only served and stored API is messaging.mkurator.dev/v1beta1.
v1alpha1 and the conversion webhook were removed in v0.15.0; follow the
upgrade runbook before upgrading any
cluster that ever ran v0.12 or earlier. Latest release: see the badge above or
GitHub Releases. Extended
CHLAUTH rule types remain on the roadmap.
| Custom resource | MQ objects | Notes |
|---|---|---|
QueueManagerConnection | (connectivity) | Ping + credentials from a referenced Secret |
Queue | QLOCAL, QALIAS, QREMOTE | spec.type: local (default), alias, remote |
Topic | TOPIC | Drift-checked attributes per ATTRIBUTE_RECONCILIATION.md |
Channel | CHANNEL … CHLTYPE(SVRCONN) | Other channel types planned later |
ChannelAuthRule | CHLAUTH | ADDRESSMAP exercised in kind e2e; BLOCKUSER in Docker integration; USERMAP, SSLPEERMAP, QMGRMAP, BLOCKADDR accepted by schema and admission, MQ-validated at apply time |
AuthorityRecord | SET AUTHREC (OAM) | Queue profile + principal/group authorities |
API version: all six kinds serve v1beta1 only. Access control covers
SET CHLAUTH (one rule per CR) and SET AUTHREC for queue/channel-style
profiles; see PHASE5_AUTH_SKETCH.md for the
rule-type roadmap. API stability:docs/API_STABILITY.md.
Repository:github.com/platformrelay/MKurator — Go module
github.com/platformrelay/MKurator, images
ghcr.io/platformrelay/mkurator (ADR-0006, superseded by ADR-0018). Your
local clone directory may differ from the module/repo name (for example
IBM-Message-Queue-Operator).
| Tier | Scope |
|---|---|
| Unit + envtest | Reconcilers and adapter (mocked MQ); validating admission; Queue, Topic, Channel, auth CRs, QMC |
| Docker integration | Queue, Topic, Channel, AUTHREC against live mqweb; CHLAUTH ADDRESSMAP (GET, replace, delete) and BLOCKUSER (GET) |
kind e2e (KURATOR_E2E_MQ=1) | Queue, Topic, Channel, AuthorityRecord reconcile + delete; CHLAUTH ADDRESSMAP and BLOCKUSERChannelAuthRule reconcile + delete on live QM1 |
Details and commands: DEVELOPMENT.md#test-tiers.
Latest tagged release: GitHub Releases
(current badge above). main may include fixes not yet in a tag. See
CHANGELOG.md for version history (generated from Conventional Commits).
- Reconciles custom resources (
Queue,Topic,Channel,ChannelAuthRule,AuthorityRecord) into MQSC objects on a running Queue Manager. - Talks to the Queue Manager through the IBM MQ Administrative REST API
(
mqweb) over HTTPS — pure Go, no CGO. - Reports status via conditions and cleans up via finalizers.
It does not deploy or operate Queue Manager installations; the Queue
Manager is assumed to already exist and expose mqweb.
You declare desired MQ objects as Kubernetes custom resources. The operator watches those CRs, validates specs at admission, and reconcilers call the mqrest adapter to execute MQSC through mqweb on your queue manager. Status conditions report success, drift correction, and errors. Full design: ARCHITECTURE.md · published docs: platformrelay.github.io/MKurator.
Kubebuilder v4 layout — thin reconcilers, an
MQAdmin port, and an mqweb
adapter. Full design: ARCHITECTURE.md · extended map:
AGENTS.md.
mkurator/
├── 📦 api/v1beta1/ CRD types + deepcopy (QMC, Queue, Topic, Channel, auth)
├── 🚀 cmd/ Manager entrypoint (controller-runtime)
├── 🧠 internal/
│ ├── controller/ Reconcilers (thin) + unit/envtest suites
│ ├── validation/ Admission validation rules (pure functions)
│ ├── webhook/v1beta1/ Validating webhook handlers
│ ├── mqadmin/ MQAdmin port — interface + domain errors
│ ├── adapter/mqrest/ mqweb REST client (sole adapter today)
│ ├── logging/ Structured logging helpers
│ └── metrics/ Prometheus metrics
├── ⚙️ config/ Kustomize — CRDs, RBAC, manager, webhook, samples
├── ⎈ charts/mkurator/ Publishable Helm chart + sample CRs
├── 🧪 test/
│ ├── integration/ Docker MQ tests (build tag `integration`)
│ ├── e2e/ kind + live QM1 (build tag `e2e`)
│ └── mocks/ mockery-generated MQAdmin mocks
├── 🔧 hack/
│ ├── kind-cluster/ Local platform: kind + Terraform + IBM MQ Helm
│ ├── mq-docker/ Standalone IBM MQ container for integration CI
│ └── *.sh verify, release assets, tool install helpers
├── 📚 docs/ Guides, ADRs, MQ research (see docs/README.md)
├── Taskfile.yml Primary task runner (`task local:up`, …)
└── AGENTS.md Go conventions + agent entry point
Start here:docs/INSTALL_AND_USE.md — install the operator (Release manifests, Helm), connect to your queue manager, manage queues, kubectl diagnostics, and uninstall.
Sample YAML with annotations: config/samples/README.md.
# After task deploy:helm or task local:up — preferred one-shot sample apply:
task deploy:samples
kubectl get qmc,mq,tp,chl,car,auth -n mkurator-systemtask deploy:samples is the supported path on kind: it ensures the
mkurator-system namespace exists and server-side-applies
charts/mkurator/samples/resources/ (Secret + all sample CRs). Annotated reference
YAML lives under config/samples/ — edit there, then task samples:sync.
Tool install:docs/LOCAL_SETUP.md — Go, Task, Docker, kind, Terraform, and verification by tier.
Canonical reference:docs/DEVELOPMENT.md — inner loop, local platform, task reference, test tiers, URLs, and credentials.
task local:up # cluster + IBM MQ + operator (Helm) + sample CRs
task local:info # URLs, credentials, CR status
task local:down # tear everything downVerify reconciliation with docs/IBM_MQ_101.md (runmqsc, MQ console).
Operator guides live on the published site (table under Operator docs).
Source Markdown under docs/ is for contributors editing the site.
| Doc | |
|---|---|
| 🎯 Use MKurator | Quick start · Install and use · FAQ · Glossary |
| 🛠️ Develop | Development guide · Contributing · CI/CD |
| 🏗️ Design | Architecture · ADRs · Changelog |
Full index: docs/README.md.
| Link | |
|---|---|
| Contributing | CONTRIBUTING.md |
| Code of Conduct | CODE_OF_CONDUCT.md |
| Governance | GOVERNANCE.md |
| Security | SECURITY.md |
| Changelog | CHANGELOG.md |
MIT — see LICENSE.