Add Usage, Signing verification and Install instructions to docs (#83)

Author: Andrew-Lees11

README.md

@@ -4,41 +4,117 @@
 
 A collection of tools for interacting with IBM® MQ queue managers running in containers.
 
-This repository currently includes the MQ MustGather tool, which simplifies the collection of diagnostic information from a running queue manager. Tools are provided as CLI commands, built from a Go binary, and are designed to be lightweight, container-friendly, and easy to integrate into automated environments.
+The following tools are currently available:
 
-Additional tools may be added over time to support broader inspection and interaction use cases.
+ - [MustGather](#mustgather-usage) - Collect diagnostic information required when opening a support case with IBM® MQ containers Support.
+ - [PVCTool](#pvctool-usage) - Provides access to the files on a queue manager PVC where a remote shell cannot be established to the queue manager pod. This might be because the pod is in an Error or CrashLoopBackOff state.
 
-The full source code is available at https://github.com/ibm-messaging/mq-container-inspector
+## Install Instructions
 
-## Build
+To use MQ container inspector, you must install it via one of the following options: 
 
-To build the MQ container inspector tools, simply run:
+- [Build Binary](#build-binary): Build the MQ container inspector binary from the source code
+- [Download Binary](#download-binary): Download the prebuilt MQ container inspector Binary
+- [Prebuilt MQ container inspector image](#prebuilt-mq-container-inspector-image): Use MQ container inspector via the CPFS MustGather Image
 
-`go build`
+### Build Binary
 
-This will produce a single binary containing all available CLI tools. No additional dependencies or setup steps are required. 
+To build and install the MQ container inspector` tool, follow these steps:  
+
+1. Clone MQ container inspector GitHub repository, for example:  
+
+```bash
+git clone https://github.com/ibm-messaging/mq-container-inspector.git 
+cd mq-container-inspector
+```
+
+2. Build MQ container inspector:
+
+```bash
+go build
+```
+
+3. Add mq-container-inspector to your path, for example:
+
+```
+sudo mv mq-container-inspector /usr/local/bin
+```
+
+4. Verify the build was successful:  
+
+`mq-container-inspector version`
+
+### Download Binary
+
+#### Linux
+
+1. Download the latest MQ container inspector tarball and signature for your architecture from the [releases page](https://github.com/ibm-messaging/mq-container-inspector/releases)
+2. Verify the tarball signature by following the instructions in [VerifyBinary.md](https://github.com/ibm-messaging/mq-container-inspector/tree/main/docs/VerifyBinary.md)
+3. Extract the tarball (e.g. for 1.0.0_mq-container-inspector_linux-amd64.tar.gz):  
+`tar -xvzf ~/Downloads/1.0.0_mq-container-inspector_linux-amd64.tar.gz`
+4. Add mq-container-inspector to your path, for example:
+
+```
+sudo mv 1.0.0_mq-container-inspector_linux-amd64 /usr/local/bin/mq-container-inspector
+```
+5. Verify the Installation:  
+`mq-container-inspector version`
+
+#### MacOS
+- Requires [Homebrew](https://brew.sh/)
+- Requires [Go](https://go.dev/)
+
+An MQ container inspector tarball is not available for MacOS, however the binary is available for install via brew.
+
+1. Add the MQ homebrew tap:  
+`brew tap ibm-messaging/ibmmq`
+
+2. Install MQ container inspector:  
+`brew install ibm-messaging/ibmmq/mqcontainerinspector`
+
+3. Verify the Installation:  
+`mq-container-inspector version`
+
+#### Windows
+
+1. Download the latest MQ container inspector zip file and signature from the [releases page](https://github.com/ibm-messaging/mq-container-inspector/releases)
+2. Verify the zip file signature by following the instructions in [VerifyBinary.md](https://github.com/ibm-messaging/mq-container-inspector/tree/main/docs/VerifyBinary.md)
+3. Unzip the Tool, for example:
+- Locate the downloaded .zip file (e.g. 1.0.0_mq-container-inspector_windows-amd64.zip)
+- Right-click the file and choose Extract All...
+- Choose a destination folder and click Extract
+4. Add the executable to your system path:  
+`setx PATH "%PATH%;C:\<Path-to-executable>\mq-container-inspector" /M`
+5. Verify the Installation:  
+`mq-container-inspector version`
+
+### Pre-built MQ container inspector image
+
+The MQ container inspector binary is included in the IBM Cloud Pak foundational services MustGather image (icr.io/cpopen/cpfs/must-gather:latest). For usage instructions, see the [MQ Container troubleshooting docs](https://www.ibm.com/docs/en/ibm-mq/9.4.x?topic=troubleshooting-problems-mq-operator)
 
 ## Mustgather Usage
 
-After building the binary, you can run the MustGather tool with the following command:
+After the binary has been built or installed, you can run the MustGather tool with the following command:
 
-`./mq-container-inspector mustgather --qm-name <queue-manager-name> --qm-namespace <queue-manager-namespace>`
+`mq-container-inspector mustgather --qm-name <queue-manager-name> --qm-namespace <queue-manager-namespace>`
 
 This command collects diagnostic data from the specified queue manager running in a Kubernetes or OpenShift environment.
 
 By default, the output is saved inside a `Must_Gather_<timestamp>` folder in the current working directory.
 
+For full usage and output, see the [Mustgather Usage Guide](https://github.com/ibm-messaging/mq-container-inspector/tree/main/docs/MustGatherUsage.md)
+
 ## PVCtool Usage
 
-After building the binary, you can run the PVC tool with the following command:
+After the binary has been built or installed, you can use the PVC tool to perform a [runmqras](https://www.ibm.com/docs/en/ibm-mq/9.4.x?topic=reference-runmqras-collect-mq-troubleshooting-information) must gather against a failing queue manager, with the following command:
 
-`./mq-container-inspector pvctool --qm-name <queue-manager-name> --qm-namespace <queue-manager-namespace>`
+`mq-container-inspector pvctool --qm-name <queue-manager-name> --qm-namespace <queue-manager-namespace> --runmqras --cleanup` 
 
-This command creates pods attached to the queue manager PVCs for inspecting the PVCs in a Kubernetes or OpenShift environment.
+This command creates kubernetes pods attached to the queue manager PVCs. It then execs into the pvctool pod, runs runmqras and deletes the pods.
 
-To delete the pvctool pods, run the same command with the --cleanup flag:
+By default, the output is saved inside a `PVC_Inspector_<timestamp>` folder in the current working directory.
 
-`./mq-container-inspector pvctool --qm-name <queue-manager-name> --qm-namespace <namespace> --cleanup`
+For full usage and output, see the [PVCTool Usage Guide](https://github.com/ibm-messaging/mq-container-inspector/tree/main/docs/PVCToolUsage.md)
 
 ## Issues and contributions
 

certificates/mq-public.gpg

@@ -0,0 +1,29 @@
+-----BEGIN PGP PUBLIC KEY BLOCK-----
+
+mQINBGP3eKsBEADesGAGhDZL/IVcB48Y/68Lcp/thTLp44WDcTGQ0fVXAtNWzW+X
+1iTW/sn+2XAQv1NoN1bTVsatfvFNKKW7WKSYSi4qnz942yjEAb7wRyylOtb3aMlL
+zlTISHFRwhl98K6J+555vToxK2iGeuTv0CvzGB+2KF4mrB3VlIhHm8JK+QQsD9O6
+IDcar+GzLkd3ZBx5zN7ivEvDcZ/qxiEeFnFIQ2jknqoZ+gsDkpYfHOQtNDR45+WN
+Y3VGkUVPYdAHWbU8uJeGcfhT87pdeMx6zQ+mrkFM2eptsL7muQF66Q5PLvIDWGXs
+N1eCbOAITgXdd1CbhkM11U2pgYZ7ONyAJp22dUJP+43UC3aQt3IVGhDJa2LryUVT
+HfsoJ84T38lH/GQHAxjw7a/0Sq8xy0iEtA81lukiK9D50796mbs25kanxslfDBoX
+5a2UQrX45Grq1h5+vR3QVx/wRmfHCyAo0sMImnHG2SVDZpVhJWChYxWwQOgIDZDE
+scxa+QU3bPy0bNKJdsSBb/4rW4mCYbX5K1119VrtTr0tRHU7ItkW21uzz5oxb9eb
+LsGsM9hwKbQXCaU83UAJy/V7JtJk3nJ+JihLpaUhszoMPgiuvXu+jH3uqoHhLjwc
+SzfSX3aXLzsIvYcDPiKWWrYK5JxWx/AWGP8o1QCflobS4MaAH5UXHBOBCwARAQAB
+tD5JbnRlcm5hdGlvbmFsIEJ1c2luZXNzIE1hY2hpbmVzIENvcnBvcmF0aW9uIDxw
+c2lydEB1cy5pYm0uY29tPokCOgQTAQgAJAUCY/d4qwIbDwULCQgHAgYVCgkICwIE
+FgIDAQIeAQUJAAAAAAAKCRCVFASm54U5I/ThEACDegHJz7Dl4aAz2XHC6c/C5ZrJ
+7W++tckc3tX3wFg2Ux8AWUwc/3oaT63nG3J7JsF0y+FmD2Loi5grReKRIE7IAAga
+aA6y/S73VOm7sApIz4hRvQ8DoWYcuu/pFMZaQKLKh3d7n0Uhlg+IxcnDWYT/xKvn
+1RrCOLhokEu22zRDg+VGClmmiyQ8qZdyA8c6OqjT9U2RFwSUnNPkLsdoCU5KVT5l
+1znNG5gEovgxIRBbeJuoYXBRIlUO7bH0w3poTZ8dPFzOSLTfG5hLF1sZVMfGBlCf
+c94rtLUJyU5LBBe7Py2y0q89v9L1a/BwNRe1ron39PLsmXPUFqV5f796wAnMif9l
+5FI1HDHpkjn3RRHjPMUQSeMOJP9HMLjhEIg9I0bDxsbqCg4XW2xfk8J0YE3GhF2p
+X5BKFThsMQWAKwwCRrD2EMW3YMv7/E385m3QA3xTU4z2SFEyp/KaoTxFw+Z9Z6ta
+7tzdE4NqmcEcVSrOvktIQ3xi9UlngOp7OACe10WhmJiDkAfaTOExHfRLVzvo3ryA
+5pNJ6FkV+eJVljBMUzRSkyyGrnesh6c6ViBcV0rZpiE1f7T4gp9tg2YQaOMaoI6P
+M9LfRKfyxSklz/aX811eRfmJRPkA9pF0DlCV6j9XJwFaSKZhxoVQVu2/pIGzQwuu
+uBfw3hQI0oUbrt3dIw==
+=yKDk
+-----END PGP PUBLIC KEY BLOCK-----

docs/MustGatherUsage.md

@@ -0,0 +1,93 @@
+## MQ container inspector mustgather command
+
+The MQ container inspector `mustgather` command collects diagnostic data from the specified queue manager running in a Kubernetes or OpenShift environment. This data is required when opening a case with IBM® MQ containers Support.
+
+### MustGather usage examples
+
+1. Gather diagnostics data using --qm-name:
+
+`mq-container-inspector mustgather --qm-name <queue-manager-name> --qm-namespace <queue-manager-namespace>`
+
+In this example, MQ container inspector uses the `app.kubernetes.io/instance: <queue-manager-name>` label to identify queue manager resources in the specified namespace. When deploying using the MQ Operator, this label is set to the queue manager custom resource `metadata.name`. When deploying using an mq sample helm chart, this label is set to the helm release name.
+
+2. Gather diagnostics data using --pod-name:
+
+`mq-container-inspector mustgather --pod-name <pod-name> --qm-namespace <queue-manager-namespace>`
+
+In this example, MQ container inspector gets the Kubernetes pod with the specified `<pod-name>` and identifies any resources such as as services, statefulset or other queue manager pods which are connected to the specified pod. Using `--pod-name` is recommended if the queue manager is not deployed via the MQ operator or an mq sample helm chart.
+
+### Kubernetes permissions required for mustgather
+
+- The user requires "get" permissions for the resources listed in the [Example files gathered](#example-files-gathered). If the user doesn't have permissions for any resource, they will not be gathered, but the tool will continue to gather other resources where it does have permissions.
+- The user requires "create" for "pods/exec" to run runmqras on the queue manager and to gather queue manager log files. Gathering these files can be disabled using the `--skip-exec` flag.
+
+### full mustgather usage options
+
+Below is the full usage options of the must gather tool. This is equivent to the output of the `--help` command
+
+```
+Usage of mustgather:
+  --help
+        show help message
+  --kubeconfig
+        path to the kubeconfig file. Ignored when running via mustgather image (default: ~/.kube/config)
+  --operator-namespace
+        namespace where the MQ operator is deployed (default: --qm-namespace)
+  --output-dir
+        directory where the must-gather output folder will be created. Ignored when running via mustgather image (default: current working directory)
+  --pod-name
+        name of a queue manager pod in the target queue manager instance (exactly one of --qm-name or --pod-name are required)
+  --qm-name
+        QueueManager custom resource metadata.name (exactly one of --qm-name or --pod-name are required)
+  --qm-namespace
+        namespace where the queue manager is deployed (required)
+  --skip-exec
+        skip gathering diagnostic data that require container exec access, e.g. runmqras, webconsole logs (default: false)
+  --skip-tar
+        skip compressing the must-gather output into a tar.gz file (default: false)
+```
+
+### Example files gathered
+
+#### Root Files
+- runmqras-&lt;qm-name&gt;-ibm-mq-0.zip
+- must-gather-logs.log
+
+#### mq-operator/
+- ibm-mq-operator-current-pod-log.txt
+- ibm-mq-operator-previous-pod-log.txt
+- ibm-mq-operator-deployment.yaml
+- ibm-mq.&lt;version&gt;-csv.yaml
+
+#### queue-managers/
+- &lt;qm-name&gt;.yaml
+- queue-manager-crd.yaml
+
+#### routes/
+- &lt;qm-name&gt;-ibm-mq-qm-routes-to-qm.yaml
+- &lt;qm-name&gt;-ibm-mq-qm-routes.yaml
+- &lt;qm-name&gt;-ibm-mq-web-routes-to-qm.yaml
+- &lt;qm-name&gt;-ibm-mq-web-routes.yaml
+
+#### services/
+- &lt;qm-name&gt;-ibm-mq-metrics-service.yaml
+- &lt;qm-name&gt;-ibm-mq-service.yaml
+
+#### pods/
+- &lt;qm-name&gt;-ibm-mq-0-current-pod-log.txt
+- &lt;qm-name&gt;-ibm-mq-0-describe-log.txt
+- &lt;qm-name&gt;-ibm-mq-0-pod-events.txt
+- &lt;qm-name&gt;-ibm-mq-0.yaml
+- pod-details.txt
+
+#### statefulsets/
+- &lt;qm-name&gt;-ibm-mq-statefulset-events.txt
+- &lt;qm-name&gt;-ibm-mq-statefulset-revisions.yaml
+- &lt;qm-name&gt;-ibm-mq-statefulset.yaml
+
+#### pvcs/
+- data-&lt;qm-name&gt;-ibm-mq-0-pvc.yaml
+
+#### webconsole/
+- web-&lt;qm-name&gt;-ibm-mq-0-console.log
+- web-&lt;qm-name&gt;-ibm-mq-0-messages.log

docs/PVCToolUsage.md

@@ -0,0 +1,66 @@
+## PVCTool Usage
+
+The MQ container inspector PVC tool creates pod(s) the the same nodes as the queue manager pod(s) attached to the queue manager PVCs. You can then exec into the pvc pods to investigate the pvcs manually or run the tool with the `--runmqras` flag to run the runmqras must gather on the pod.
+
+### PVCTool usage examples
+
+1. Create pvctool pods using --qm-name:
+
+`mq-container-inspector pvctool --qm-name <queue-manager-name> --qm-namespace <queue-manager-namespace>`
+
+This command creates pods attached to the queue manager PVCs. You can exec into these pods to manually inspect the PVCs in a Kubernetes or OpenShift environment. 
+
+**Note**: If you exec into a pvctool pod, any changes to the PVC will affect the corresponding queue manager and could result in a corrupted queue manager or lost messages. 
+
+To delete the pvctool pods, run the same command with the --cleanup flag:
+
+`mq-container-inspector pvctool --qm-name <queue-manager-name> --qm-namespace <namespace> --cleanup`
+
+2. Perform a runmqras must gather using the pvc tool:
+
+`mq-container-inspector pvctool --qm-name <queue-manager-name> --qm-namespace <queue-manager-namespace> --runmqras --cleanup` 
+
+This command creates pods attached to the queue manager PVCs. It then execs into the pvctool pod, runs runmqras and deletes the pvctool pods.
+
+By default, the output is saved inside a `PVC_Inspector_<timestamp>` folder in the current working directory.
+
+### Kubernetes permissions required for pvctool
+
+- The user requires "get" permissions for "pods" and "configmaps".
+- The user requires "create" permissions for "pods" and "configmaps" and will create these resources when it is run. 
+- The user requires "create" for "pods/exec" to run runmqras on the pods created by pvctool.
+
+
+## full pvctool usage options
+
+Below is the full usage options of the must gather tool. This is equivent to the output of the `--help` command
+
+```
+Usage of pvctool:
+  --cleanup
+        delete the pvc-inspector pods at the end of the tool run (default: false)
+  --dry-run
+        run without creating the pvc-inspector pods (default: false)
+  --help
+        show help message
+  --kubeconfig
+        path to the kubeconfig file. Ignored when running via mustgather image. (default: ~/.kube/config)
+  --output-dir
+        directory where the must-gather output folder will be created. Ignored when running via mustgather image. (default: current working directory)
+  --pod-name
+        name of a queue manager pod in the target queue manager instance (exactly one of --qm-name or pod-name are required)
+  --qm-name
+        QueueManager custom resource metadata.name (exactly one of --qm-name or pod-name are required)
+  --qm-namespace
+        namespace where the queue manager is deployed (required)
+  --runmqras
+        execute runmqras on the pvc-inspector pods (default: false)
+  --skip-tar
+        skip compressing the pvctool output into a tar.gz file (default: false)
+```
+
+### Example tool output
+
+If you use the `--runmqras` flag, the pvctool command will create a folder called `PVC_Inspector_<timestamp>` in the `--output-dir` (defaults to current working directory). This will contain a [runmqras](https://www.ibm.com/docs/en/ibm-mq/9.4.x?topic=reference-runmqras-collect-mq-troubleshooting-information) tarball for each queue manager and a logfile for the tool. 
+
+The tool will also create a tarball of the PVC_Inspector_<timestamp> folder which should be uploaded to the support case.