Ansible

Ansible is how platform teams turn IBM MQ administration into repeatable, reviewable automation. Instead of SSHing to each broker and pasting MQSC, you describe desired state in YAML playbooks: install the client on app servers, deploy channel definitions, run a smoke-test put, or promote a tested MQSC bundle from TEST to PROD with the same role and different inventory variables. Ansible does not replace the queue manager—it orchestrates the same runmqsc, setmqaut, and dspmq commands you already trust, but adds inventory, parallelism, secrets management, and audit trails that shell-only shops outgrow. Beginners should start with one playbook that runs one MQSC file against one host, then grow into roles shared across environments. This tutorial covers playbook structure, wrapping runmqsc safely, IBM MQ collection concepts, variable design for queue names and channels, ansible-vault for credentials, AWX or Automation Controller for approvals, idempotency with DEFINE REPLACE, rolling updates across a cluster of queue managers, and how Ansible fits beside Terraform and CI pipelines.

Why Ansible for IBM MQ

Enterprise MQ estates span dozens of queue managers on Linux, Windows, and sometimes appliance form factors. Manual drift appears when QM_LONDON has an extra channel nobody documented. Ansible encodes the intended configuration in Git: reviewers see the diff, pipelines run check mode or dry-run where possible, and operators apply with --limit to one host during incidents. Compared to cron plus bash, Ansible reports per-task success in JSON for Splunk; compared to clicking MQ Explorer, Ansible scales to hundreds of objects without human typo risk on DEFINE CHANNEL names.

Minimal Playbook: runmqsc Task

The pattern mirrors bash: ensure MQ binaries are on PATH (often by sourcing setmqenv in a wrapper script), then pipe MQSC into runmqsc. Use args chdir and become_user so the task runs as the mq m service account, not root. Register stdout and fail when AMQ error lines appear—Ansible failed_when is clearer than silent success on partial MQSC failure.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
- name: Deploy baseline queues to QM1
  hosts: mq_linux
  become: true
  become_user: mqm
  vars:
    qmgr_name: QM1
  tasks:
    - name: Copy MQSC bundle
      ansible.builtin.copy:
        src: files/01-queues.mqsc
        dest: /tmp/01-queues.mqsc
        mode: "0640"
 
    - name: Apply MQSC
      ansible.builtin.shell: |
        . /opt/mqm/bin/setmqenv -s
        runmqsc {{ qmgr_name }} < /tmp/01-queues.mqsc
      register: mqsc_out
      changed_when: "'AMQ' in mqsc_out.stdout"
 
    - name: Fail on MQSC errors
      ansible.builtin.fail:
        msg: "MQSC reported errors"
      when: mqsc_out.stdout is search('AMQ[0-9]{4}E')

Variables and Environments

Never hardcode production queue names in a role defaults file without guards. Use group_vars/mq_test.yml and group_vars/mq_prod.yml with keys like orders_queue: TEST.ORDERS.IN versus PROD.ORDERS.IN. Channel CONNAME should reference DNS names that differ per inventory: mq-test.corp versus mq-prod.corp. Jinja2 templates generate MQSC lines: DEFINE QLOCAL('orders_queue') REPLACE. The REPLACE keyword makes second playbook runs idempotent—they alter existing objects instead of failing with object already exists.

• host_vars — override one broker in a DR site.
• group_vars — shared naming standard per environment.
• extra-vars -e @secrets.yml — emergency hotfix with approval.
• assert module — qmgr_name must equal dspmq -m output before destructive steps.

IBM MQ Collection and Modules

IBM and partners publish Ansible content (search Galaxy for IBM MQ collections for your release). Collections may wrap PCF or REST admin instead of raw MQSC text—understand which layer owns truth. If a module creates a queue via API, do not also DEFINE the same queue in a parallel MQSC file or you fight dual maintenance. When collections are unavailable, command and shell wrapping runmqsc remains the portable approach every MQ administrator already understands.

Client-Side Automation

Application servers need IBM MQ client installs, MQCHLLIB pointing at CCDT directories, and TLS trust stores. Ansible roles on app tier copy AMQCLCHL.TAB from template, set environment in systemd drop-ins, and verify with a short compiled amqsputc or Python pymqi smoke task. Separating broker playbooks (mq_linux group) from client playbooks (app_servers group) mirrors how networks actually connect—do not mix strmqm on app hosts.

Explainer: Recipe Card for Every Server

Ansible is a recipe card that tells many kitchen stations the same steps at once: chop onions (copy MQSC), sauté (runmqsc), taste (grep for AMQ errors). If one station burns the dish, the head chef sees which step failed without visiting every station personally.

Secrets with ansible-vault

TLS keystore passwords, LDAP bind passwords for CONNAUTH testing, and break-glass admin credentials belong in vault-encrypted files. Playbooks reference vault_mq_secrets.yml; operators run ansible-playbook --ask-vault-pass or use AWX credentials inject. Rotate vault keys on HR policy. Never log decrypted secrets—set no_log: true on tasks that pass passwords to shell scripts.

AWX and Change Control

Red Hat Ansible Automation Platform (AWX) adds job templates, RBAC, and survey prompts (which queue manager?). Production job templates require peer approval workflow integration. Schedule nightly channel health playbooks with email on failure. Store playbook Git revision in job output for audit: who deployed ALTER CHANNEL at 02:14.

Idempotency and Ordering

1. Install MQ packages or verify version tag.
2. Create file systems and mqm user if greenfield.
3. strmqm when queue manager not running.
4. Apply MQSC in numbered files: 01-qmgr, 02-queues, 03-channels, 04-auth.
5. START LISTENER and START CHANNEL only after definitions exist.
6. Smoke test put/get from controller or bastion.

Handlers restart listeners only when MQSC changes listener PORT—avoid bouncing production listeners on every playbook dry run. Use tags (--tags channels) for partial deploys during incidents.

CI Integration

GitLab CI or Jenkins runs ansible-playbook --check against a containerized MQ test image on pull request. Merge to main triggers deploy to TEST inventory; manual gate promotes to PROD. Lint with ansible-lint. YAML reviews include MQSC diff side by side. Pair with Terraform apply that created the VM before Ansible configures MQ software on it.

Troubleshooting Ansible MQ Runs

• command not found runmqsc — missing setmqenv in non-login task environment.
• Permission denied — become_user not mqm or wrong file mode on keystore.
• Playbook succeeded but objects missing — runmqsc exited 0 while MQSC had warnings; tighten failed_when.
• Wrong QM — inventory typo; add assert comparing expected qmgr_name to hostname fact.
• Parallel runs collided — use serial: 1 on strmqm tasks for shared storage multi-instance QMs.

Explain Like I'm Five: Ansible

Ansible is a list of chores you give to a robot that can visit many IBM MQ computers and do the same chores on each one, checking off each chore only when it worked.

Practice Exercises

Exercise 1

Write a playbook with one host that copies an MQSC file and runs runmqsc, failing on AMQ error lines.

Exercise 2

Split group_vars for mq_dev and mq_prod with different queue name prefixes in a Jinja2 template.

Exercise 3

Document how your team would use AWX survey to pick queue manager name before apply.

Frequently Asked Questions

Test Your Knowledge