Skip to content

Commit 0d1f6a9

Browse files
martinevansibmmartinevansibm
authored
Merge pull request #2 from ibm-messaging/enhancements-r1
Playbook and documentation enhancements.
2 parents 60cc568 + a6fd6ac commit 0d1f6a9

File tree

12 files changed

+185
-137
lines changed

12 files changed

+185
-137
lines changed

‎README.md

Lines changed: 86 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
| :memo: | Interested in contributing to this project? Please read our [IBM Contributor License Agreement](CLA.md) and our [Contributing Guide](CONTRIBUTING.md). |
44
|---------------|:------------------------|
55

6-
A collection for automating the installation and configuration of IBM MQ using Ansible on Ubuntu machines. Our aim is to make MQ-Ansible extensible for further and more detailed IBM MQ configuration.
6+
A collection for automating the installation and configuration of IBM MQ using Ansible on Ubuntu machines. Our aim is to make MQ-Ansible extensible for other platforms and more detailed IBM MQ configuration.
77

88
This directory contains:
99
- ansible [`roles`](https://github.com/ibm-messaging/mq-ansible/tree/main/ansible_collections/ibm/ibmmq/roles) for the installation and configuration of IBM MQ.
@@ -14,46 +14,81 @@ For a detailed explanation and documentation on how MQ-Ansible works, click [her
1414

1515
## Requirements
1616

17-
- `ansible` and `ansible-lint` are required on your local machine to run playbooks implementing this collection.
17+
- `ansible`, `passlib` and `ansible-lint` are required on your local machine to run playbooks implementing this collection.
1818
- An Ubuntu target machine is required to run MQ.
1919

20-
## Roles for IBM MQ installation
20+
##### *Ansible* installation ([Installation guide](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html))
2121

22-
The roles in this collection carry out an installation of IBM MQ Advanced on an Ubuntu target machine with ansible roles as yaml files. The roles have been implemented to set up the required users on the machine, download the software, install and configure IBM MQ, copy over a configurable `dev-config.mqsc` file ready to be run on the target machine, and set and start the web console. Developers can change this file to allow better configuration of their queue managers.
22+
## Playbooks and Roles for IBM MQ installation
2323

24+
The playbooks and roles in this collection carryout an installation of IBM MQ Advanced on an Ubuntu target machine. The roles have been implemented to set up the required users on the machine, download the software, install and configure IBM MQ, copy over a configurable `dev-config.mqsc` file ready to be run on the target machine, and setup and start the web console. Developers can change this file to customise the configuration of their queue managers. Here we use a playbook that calls other playbooks but you can run the roles in playbooks to suit your requirements.
2425

25-
### Example
26+
### Example Playbooks
27+
28+
ibmmq.yml - this playbook calls the mq-install and mq-setup playbooks, host names are passed into the imported playbook variable as {{ ansible_play_batch }}
29+
30+
```yaml
31+
- name: Install and setup IBM MQ
32+
hosts: ['servers']
33+
34+
- name: Run the install playbook
35+
import_playbook: mq-install.yml
36+
37+
- name: Run the setup playbook
38+
import_playbook: mq-setup.yml
39+
```
40+
41+
mq-install.yml - this playbook installs IBM MQ with the SSH user specified in the inventory
2642
2743
```yaml
28-
- hosts: [YOUR_TARGET_MACHINES]
44+
- hosts: "{{ ansible_play_batch }}"
45+
serial: 1
2946
become: false
3047
environment:
3148
PATH: /opt/mqm/bin:{{ ansible_env.PATH }}
3249

33-
roles:
50+
roles:
3451
- role: setupusers
3552
vars:
36-
gid: 989
53+
gid: 909
3754
- downloadmq
3855
- installmq
56+
```
57+
mq-setup.yml - this playbook sets up IBM MQ using the 'mqm' user
58+
59+
```yaml
60+
- hosts: "{{ ansible_play_hosts }}"
61+
serial: 1
62+
become: yes
63+
become_user: mqm
64+
environment:
65+
PATH: /opt/mqm/bin:{{ ansible_env.PATH }}
66+
67+
roles:
3968
- getconfig
4069
- setupconsole
4170
- startconsole
42-
```
4371

72+
tasks:
73+
74+
- name: Create a queue manager
75+
queue_manager:
76+
qmname:
77+
- 'QM1'
78+
- 'QM2'
79+
state: 'present'
80+
```
4481
## Modules for IBM MQ resources' configuration
4582
4683
- `queue_manager.py`- Creates, starts, deletes an IBM MQ queue manager and runs an MQSC file. See the documentation [here.](QUEUE_MANAGER.md)
4784

4885
# Run our sample playbook
4986

50-
### Setup (inventory.ini)
87+
##### *Note*: *Ansible* must be installed on the local machine ([Installation guide](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html))
5188

52-
##### Note: *Ansible* must be installed on the local machine. ([Installation guide](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html))
89+
Before running the playbook and implementing our modules and roles for IBM MQ:
5390

54-
Before running the playbook implementing our modules and roles for IBM MQ:
55-
56-
1. Check if you have an *ssh* key pair in order to access the target machines via Ansible. Go to the `~/.ssh` directory in your machine and look for the `id_rsa` and `id_rsa.pub` files.
91+
1. Check if you have an *ssh* key pair in order to access the target machines via SSH. Go to the `~/.ssh` directory in your machine and look for the public and private key files e.g. `id_rsa` and `id_rsa.pub`.
5792

5893
```shell
5994
cd ~/.ssh
@@ -65,68 +100,70 @@ Before running the playbook implementing our modules and roles for IBM MQ:
65100
ssh-keygen
66101
```
67102

68-
3. Once the keys have been generated, these need to be copied to the target machine's user `ssh` directory.
103+
3. Once the keys have been generated, you need to copy the public key to the target machine's user `ssh` directory.
69104

70105
```shell
71-
ssh-copy-id -i id_rsa.pub [USER]@[YOUR_TARGET_MACHINE_IP]
106+
ssh-copy-id -i id_rsa.pub [USER]@[YOUR_TARGET_HOST]
72107
```
73108

74109
4. To confirm the keys have been copied successfully, connect to your target machine by:
75110

76111
```shell
77-
ssh [USER]@[YOUR_TARGET_MACHINE_IP]
112+
ssh [USER]@[YOUR_TARGET_HOST]
78113
```
79114
This should connect to your target machine without asking for a password.
80115

81-
5. Go to the `ansible_collections/ibm/ibmmq/` directory.
116+
5. On your local machine clone this repository.
117+
118+
6. Go to the `ansible_collections/ibm/ibmmq/` directory.
82119

83120
```shell
84-
cd ..
85-
cd ansible_collections/ibm/ibmmq/
121+
cd mq-ansible/ansible_collections/ibm/ibmmq/
86122
```
87123

88124

89-
6. Create a file `inventory.ini` inside the directory with the following content:
125+
7. Create a file `inventory.ini` inside the directory with the following content:
90126

91127
```ini
92-
[YOUR_TARGET_MACHINES]
93-
[YOUR_MACHINE_IP] ansible_ssh_user=[YOUR_USER]
94-
```
128+
129+
[servers]
130+
YOUR_HOST_ALIAS ansible_host=YOUR_HOSTNAME ansible_ssh_user=YOUR_SSH_USER
131+
YOUR_HOST_ALIAS ansible_host=YOUR_HOSTNAME ansible_ssh_user=YOUR_SSH_USER
95132
96-
- Change `YOUR_TARGET_MACHINES` to your machines' group name, for example `fyre`.
97-
- Change `YOUR_MACHINE_IP` to your target machine's public IP
98-
- Change `YOUR_USER` to your target machine's user.
99-
##### *NOTE* : user on the target machine MUST NOT be root but MUST have `sudo` privileges.
133+
```
134+
##### *Note*: you can specify one or more hosts
135+
- Change `YOUR_HOST_ALIAS` to an alias name that you wish to use e.g. `mq-host-1` , you can omit aliases if you prefer
136+
- Change `YOUR_HOSTNAME` to your server/hostname, e.g. `myserver-1.fyre.com`
137+
- Change `YOUR_SSH_USER` to your target machine's SSH user
138+
##### *Note*: the user on the target machine MUST have `root` or `sudo` privileges
100139

101140
### ibmmq.yml
102141

103142
The sample playbook [`ibmmq.yml`](ansible_collections/ibm/ibmmq/ibmmq.yml) installs IBM MQ Advanced with our roles and configures a queue manager with the `queue_manager.py` module.
104143

105-
1. Before running the playbook, ensure that you have added the directory path to the PATH environment variable.
144+
1. Before running the playbook, ensure that you have added the following directory path to the ANSIBLE_LIBRARY environment variable.
106145

107-
##### *NOTE* : change `<PATH-TO>` to your local directory path:
146+
##### *Note*: change `<PATH-TO>` to your local directory path:
108147

109148
- On Mac:
110149

111-
```shell
112-
export ANSIBLE_LIBRARY=<PATH-TO>/ansible_mq/ansible_collections/ibm/ibmmq/library
113-
```
114-
115-
- On Windows:
150+
```shell
151+
export ANSIBLE_LIBRARY=${ANSIBLE_LIBRARY}:<PATH-TO>/ansible_mq/ansible_collections/ibm/ibmmq/library
152+
```
116153

117-
```shell
118-
set ANSIBLE_LIBRARY=<PATH-TO>/ansible_mq/ansible_collections/ibm/ibmmq/library
119-
```
120-
121-
2. Make sure you update the hosts in `ibmmq.yml` name to `YOUR_TARGET_MACHINES` group from your inventory file.
154+
- On Windows:
155+
156+
```shell
157+
set ANSIBLE_LIBRARY=%ANSIBLE_LIBRARY%;<PATH-TO>/ansible_mq/ansible_collections/ibm/ibmmq/library
158+
```
122159

123-
3. Run the following command to execute the tasks within the playbook:
160+
2. Run the following command to execute the tasks within the playbook:
124161
```shell
125-
ansible-playbook ./ibmmq.yml -i inventory.ini -K
162+
ansible-playbook ./ibmmq.yml -i inventory.ini
126163
```
127-
- ##### *NOTE* : `-K` will prompt the user to enter the sudo password for [YOUR_USER] on the target machine.
164+
- ##### *Note*: you can optionally add `-K` (uppercase) to the command, this will prompt the user to enter the sudo password for [YOUR_SSH_USER] on the target machine, you can omit if you have setup SSH keys
128165

129-
4. The playbook should return the result of `dspmq` with the queue manager created listed. Log into your target machine and check it manually:
166+
3. The playbook should return the result of `dspmq` with the queue manager created listed. Log into your target machine and check it manually:
130167

131168
```shell
132169
dspmq
@@ -139,9 +176,9 @@ If one of the following errors appears during the run of the playbook, run the f
139176
- `Please add this host's fingerprint to your known_hosts file to manage this host.` - Indicates that an SSH password cannot be used instead of a key.
140177

141178
Fix:
142-
##### *NOTE* : change `[YOUR_MACHINE_IP]` to the target machine's public IP address
179+
##### *Note*: change `[YOUR_HOST]` to the target machine's network address
143180
```shell
144-
ssh-keyscan -H [YOUR_MACHINE_IP] >> ~/.ssh/known_hosts
181+
ssh-keyscan -H [YOUR_HOST] >> ~/.ssh/known_hosts
145182
```
146183
- `zsh: command not found: dspmq` - Appears that MQ environment variables have not been set.
147184

@@ -170,10 +207,10 @@ To run the test playbooks first:
170207
```
171208
2. export the modules to your Ansible library
172209
```shell
173-
export ANSIBLE_LIBRARY=<PATH-TO>/ansible_mq/ansible_collections/ibm/ibmmq/library
210+
export ANSIBLE_LIBRARY=${ANSIBLE_LIBRARY}:<PATH-TO>/ansible_mq/ansible_collections/ibm/ibmmq/library
174211
```
175-
- ##### *NOTE* : change `<PATH-TO>` to your local directory path:
176-
3. run all test playbooks with `main.py`
212+
- ##### *Note*: change `<PATH-TO>` to your local directory path:
213+
3. run all test playbooks with `python3 main.py`
177214

178215
## License
179216

‎ansible_collections/ibm/ibmmq/ibmmq.yml

Lines changed: 6 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1,38 +1,8 @@
1-
- hosts: [YOUR_TARGET_MACHINES]
2-
become: false
3-
environment:
4-
PATH: /opt/mqm/bin:{{ ansible_env.PATH }}
1+
- name: Install and setup IBM MQ
2+
hosts: ['servers']
53

6-
roles:
7-
- role: setupusers
8-
vars:
9-
gid: 999
10-
- downloadmq
11-
- installmq
12-
- getconfig
13-
- setupconsole
14-
- startconsole
15-
16-
tasks:
4+
- name: Run the install playbook
5+
import_playbook: mq-install.yml
176

18-
- name: Create a queue manager
19-
queue_manager:
20-
qmname:
21-
- 'QM1'
22-
- 'QM2'
23-
state: 'present'
24-
25-
- name: Start a queue manager
26-
queue_manager:
27-
qmname:
28-
- 'QM1'
29-
- 'QM2'
30-
state: 'running'
31-
32-
- name: Run MQSC File
33-
queue_manager:
34-
qmname:
35-
- 'QM1'
36-
- 'QM2'
37-
state: 'running'
38-
mqsc_file: '/home/{{ ansible_ssh_user }}/dev-config.mqsc'
7+
- name: Run the setup playbook
8+
import_playbook: mq-setup.yml

‎ansible_collections/ibm/ibmmq/mq-install.yml

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
- hosts: "{{ ansible_play_batch }}"
2+
serial: 1
3+
become: false
4+
environment:
5+
PATH: /opt/mqm/bin:{{ ansible_env.PATH }}
6+
7+
roles:
8+
- role: setupusers
9+
vars:
10+
appUid: 909
11+
appGid: 909
12+
- downloadmq
13+
- installmq

‎ansible_collections/ibm/ibmmq/mq-setup.yml

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
- hosts: "{{ ansible_play_hosts }}"
2+
serial: 1
3+
become: yes
4+
become_user: mqm
5+
environment:
6+
PATH: /opt/mqm/bin:{{ ansible_env.PATH }}
7+
8+
roles:
9+
- getconfig
10+
- setupconsole
11+
- startconsole
12+
13+
tasks:
14+
15+
- name: Create a queue manager
16+
queue_manager:
17+
qmname:
18+
- 'QM1'
19+
- 'QM2'
20+
state: 'present'
21+
22+
- name: Start a queue manager
23+
queue_manager:
24+
qmname:
25+
- 'QM1'
26+
- 'QM2'
27+
state: 'running'
28+
29+
- name: Run MQSC File
30+
queue_manager:
31+
qmname:
32+
- 'QM1'
33+
- 'QM2'
34+
state: 'running'
35+
mqsc_file: '/var/mqm/dev-config.mqsc'

‎ansible_collections/ibm/ibmmq/roles/downloadmq/tasks/main.yml

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,14 @@
22

33
- name: Download MQ Advanced for Developers
44
get_url:
5-
url: https://public.dhe.ibm.com/ibmdl/export/pub/software/websphere/messaging/mqadv/mqadv_dev920_ubuntu_x86-64.tar.gz
5+
url: https://public.dhe.ibm.com/ibmdl/export/pub/software/websphere/messaging/mqadv/mqadv_dev931_ubuntu_x86-64.tar.gz
66
dest: /tmp/mq.tar.gz
77
force: no
8+
tags: download
89

910
- name: Extract MQ fom TAR
1011
unarchive:
1112
src: /tmp/mq.tar.gz
1213
remote_src: yes
13-
dest: /tmp
14+
dest: /tmp
15+
tags: download

‎ansible_collections/ibm/ibmmq/roles/getconfig/tasks/main.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,4 +3,4 @@
33
- name: Copy developer config file to target
44
copy:
55
src: ../../../dev-config.mqsc
6-
dest: "/home/{{ ansible_ssh_user }}"
6+
dest: "/var/mqm"

‎ansible_collections/ibm/ibmmq/roles/installmq/tasks/main.yml

Lines changed: 0 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -44,17 +44,6 @@
4444
apt-get update
4545
changed_when: 'installed_mq_packages.stdout_lines | string is not search("ibmmq")'
4646

47-
- name: Add the user to group mqm
48-
become: true
49-
shell: adduser ${SUDO_USER:-${USER}} mqm
50-
51-
- name: Add the user to group mqm
52-
become: true
53-
user:
54-
name: "{{ ansible_ssh_user }}"
55-
groups: mqm
56-
append: yes
57-
5847
- name: reset ssh connection
5948
meta: reset_connection
6049

0 commit comments

Comments
 (0)