Skill Level: Beginner

This recipe describes how to deploy IBM MQ, IBM’s messaging middleware, into IBM Cloud Private, our Kubernetes-based private cloud, using helm charts and persistent volumes.


  • IBM Cloud private 2.1
  • Kubectl command line
  • MQ Helm chart
  • Persistent volume

To learn more about IBM MQ, visit this link.


  1. Install IBM Cloud Private 2.1

    First, you will need to install IBM Cloud Private 2.1. Detailed instructions are here. Once you have it installed, then the steps will be:

    • Create a persistent volume
    • Install MQ with advanced options
    • Validate with opening the MQ management UI


    If IBM Cloud Private is already installed, make sure you have the Kubectl command line installed on your laptop/workstation so you can target any Kubernetes cloud you want. You can get the Kubectl command line here.

    OK, let’s continue…

  2. Create Persistent Volume

    To deploy IBM MQ-Dev, you need to create a persistent volume that uses the “ReadWriteOnce” (RWO) access mode. You can create the storage volume from the UI, and should ideally be created before the deployment.

    To create the volume, log into IBM Cloud Private, and use the upper left menu to navigate to the Storage page


    Once on the storage page, click “Create PersistentVolume”


    In this example, I created a 2GB NFS volume with “Read Write Once” access mode, and it will be retained if the pod is removed. If you are just trying things out, you can also create a HostPath volume, which uses local storage on whatever VM the pod happens to be deployed on.

    The value of using a persistent volume is that even though this recipe only deploys a single MQ queue manager, you can still achieve a level of availability in that if the queue manager pod or the node itself were to fail, IBM Cloud Private automatically re-schedules the queue manager to another node.

    You will soon see that the default volume size for the MQ deployment specified in the helm chart is 2GB, so if you need more, go ahead and create a larger volume first, then match the size in the installation configuration fields that you will see shortly.


    Note: If you have set up Gluster, you can use storage classes to dynamically provision storage when the service is deployed…this can be a great time saver!

  3. Get to the MQ Helm Chart

    Next, install MQ itself. With IBM Cloud Private, you have 2 ways to install IBM MQ:

    1. IBM Cloud Private’s Catalog UI
    2. From the command line using “Helm” commands


    For this example, we will use the catalog. However, if you want to use the command line, you can directly access the helm charts here: https://github.com/IBM/charts. Either path is fine, and as we both know, if you love kubectl and helm commands, then using the helm charts directly is a great option (you can get helm command line here)

    For the UI path, open IBM Cloud Private, and navigate to the catalog.


    Scroll until you see IBM MQ, or search from the top, and click to see the details.


    As a general rule, most all services have important fields you need to fill in before you can properly install, and IBM MQ is no different.

    From this details view, select the “Install” button at the bottom, then go to the next step.


  4. Specify Advanced Settings

    There are quite a few settings in the MQ install, but I’ll just highlight the ones you need to worry about.

    Install Options 1 of 2:


    In this first section you need to give your deployment a name, then accept the license, otherwise the deployment will fail.


    Install Options 2 of 2:


    There are 4 fields you should consider in this last section.


    This is where you can customize how large you want your storage to be, but remember, it can’t be bigger than the persistent volume you created earlier.


    If you keep it ‘ClusterIP’, then only apps running inside the IBM Cloud Private cluster will be able to access the MQ service. However, if you change it to ‘NodePort’, then you will be able to call the MQ service from anywhere in the network (your data center, or wherever your firewalls allow).


    The name of the queue manager that your app will use.


    The admin password. This is not required but useful…otherwise you’ll have to obtain the automatically generated password.

  5. Deploy the MQ Helm Chart

    Once you are ready (you have accepted the license, created your persistent volume, and filled in all the advanced installation details) click “Install”, and you are installing!

    Depending on compute and storage speeds, it may take a few minutes to install, create default queues, and start the management UI. I tend to use the management UI URL (next step), and get frustrated when it says “not found”, but just be patient. It will load up.

    To monitor the progress, you have two options:

    From the UI, click on “Workloads”, select the MQ application (it’s actually a ‘deployment’ in Kubernetes terms), locate the pod and select it, then select the Logs tab.

    From the command line: find the pod name and monitor its log:

    kubectl get pods

    kubectl logs <podname> -f


  6. Start Using MQ

    Once MQ is installed, you can start using MQ in two ways:

    • As a developer through the API port
    • As an operator through the console UI port

    To find the ports, you also need to decide if you want to access MQ from a pod in the private cloud or from another environment in your data center. Remember the “NodePort” setting I added in the installation? That lets you connect from both while you are developing (then later you can remove the NodePort and only use the internal endpoint.

    I like to select NodePort because it is quite useful for developers that want to initially develop their code and run from an existing environment (or in a dev-focused cloud like Mini-Kube) where they can iterate very quickly, access the MQ service, and then once they are ready they can move their application inside IBM Cloud Private and use the internal endpoints.

    To find which URLs to use, run the following to get the list of services:

    kubectl get svc

    Then once you identify the service name, run:

    kubectl describe service <service Name>

    Here is an example of what you will see:  


    Notice there are 2 sets of ports. MQ uses 1414 for the API, and 9443 for the web UI. Make sure you use the correct NodePort when accessing the UI.

    For external access (through NodePort URL), fill in the following with one of your node IP addresses (any of your node IP addresses will do…I chose the proxy node IP address):

    • Console:  https://<publicIP>:31049/ibmmq/console  
    • Queue manager: <publicIP>(31935)


    Once you see the login on the console, you can start with the default userID and password is “admin/passw0rd”

    To start using MQ from an application, you will want to use the application user ID, not the admin user ID. The application user ID is “app” (with no default password). Click here to learn more and see examples.

  7. Conclusion

    IBM MQ can help you accelerate the integration of diverse applications and business data across multiple platforms. Using this recipe, you can quickly get IBM MQ running in IBM Cloud Private.

    Good luck and happy MQ’ing!

9 comments on"Deploy MQ-Dev into IBM Cloud Private 2.1"

  1. Surprised there isn’t an ibmmq tag on this?

  2. Hello,
    Happy new year to all of you.
    This is my question:
    Instead of using existing helm charts in the catalog, I would like to know how deploy my own helm chart in the catalog.

    • GregHintermeister January 03, 2018


      You can certainly deploy your own helm charts into IBM Cloud Private. You can:

      1) Create your own helm repo and just reference it when deploying into IBM Cloud Private (the helm repo does not need to be listed in the ICP Catalog).
      2) Import your helm charts into IBM Cloud Private’s helm repo (which then shows up in ICP Catalog)
      3) Just run `helm install ` from the directory where you have your locally customized helm chart.

  3. I deployed a mq server. I followed all instructions above. After I click “Install” , I go to “Helm Releases” the Pod Status is pending ..and nothing happens. I removed and installed, but this situation persist.

    • GregHintermeister September 24, 2018


      Usually when a Pod is in “Pending” it’s a PV issue or image pull issue.
      1) This article is for 2.1, we are now at 3.1 ICP so be sure to go to the ICP catalog, read the MQ Readme for all install tips.
      2) Create the PV exactly as the Readme suggests (or select dynamic provisioning if you have Gluster storage used)
      3) To see why it’s in “Pending”, on the CLI do a “kubectl describe pod and you’ll see the events and what the pod is waiting for. (In the UI, from the Helm Release navigate to the pod and there is a “Events” and “Logs” tab. Click “Events”…which are the kube messages in creating the pod. The “Logs” will be messages from the container itself…so should be empty until the container is running).

  4. Hi,
    i have issues connecting my spring boot app to mq on icp so how can i define the ibm.mq.connName= because i always get this execption :
    Caused by: com.ibm.mq.jmqi.JmqiException: CC=2;RC=2538;AMQ9204: Connection to host ‘’ rejected. [1=com.ibm.mq.jmqi.JmqiException[CC=2;RC=2538;AMQ9213: A communications error for ‘TCP’ occurred. [1=java.net.ConnectException[Connection refused (Connection refused)],3=connnectUsingLocalAddress,4=TCP,5=Socket.connect]],3=,5=RemoteTCPConnection.connnectUsingLocalAddress]
    how can i get the correct host and the port ?

    • GregHintermeister January 04, 2019


      When you deploy MQ, you’ll find the correct host and port by doing a “kubectl describe service ” where the service name in the above example is default-mq-mq. If you’re accessing MQ from inside the same namespace, you can use that service name as the host. Otherwise you’ll want to use the internal IP address of that service. If you’re connecting from external app, you’ll want to see what node port is listed as paired with 1414 (in the above example it’s 31935…but it’s auto generated so will be different in your case).

      • Hi,
        i have always the same exception !!! and i don’t know why ?
        this is my application.properties :
        this is the output of kubectl describe service
        Name: mymq-ibm-mq
        Namespace: lab
        Labels: app=ibm-mq
        Selector: app=ibm-mq,release=mymq
        Type: NodePort
        Port: console-https 9443/TCP
        TargetPort: 9443/TCP
        NodePort: console-https 32575/TCP
        Port: qmgr 1414/TCP
        TargetPort: 1414/TCP
        NodePort: qmgr 30803/TCP
        Session Affinity: None
        External Traffic Policy: Cluster

Join The Discussion