RobParker
Published on 08/12/2017 / Updated on 19/12/2017
IBM has now announced a collaboration with Pivotal to provide the community of Spring developers with more tools for creating new applications and extending existing applications to new areas. You can read more about the announcement in Andrew Hoyts blog post. One of Pivotal’s offering of interest to both Spring developers and users of MQ alike is a production grade Kubernetes Service called Pivotal Container Service or PKS for short. As part of this announcement the IBM MQ team have tested running IBM MQ on PKS to provide Guidance and a sample for anybody who wants to use IBM MQ in a PKS environment.
The existing support statement for IBM MQ in docker containers covers orchestration software such as IBM Cloud Private, Kubernetes, PKS. As such you can take IBM MQ, run a production driver in PKS and use your existing support entitlement to raise issues encountered with IBM Support. However you must adhere to the restrictions outlined in the Docker support on Linux Systems knowledge centre page.
In this blog post we will show how you can use the ibm-messaging/mq-container sample in PKS to deploy both a free developer edition and a production version of IBM MQ into your PKS cluster.
Prerequisites
Before you can begin deploying the IBM MQ sample into PKS we need to ensure you have the following tools available on your machine:
Once you have installed the tools above you should configure your kubectl to interact with your PKS environment by following the PKS documentation which will detail the exact process.
Next you need to set up Helm to interact with your PKS environment. Because PKS uses Role based access control (RBAC), Helm may not be able to interact with the default namespace. As such, you will need to create a namespace, a service ID and install Helm into that namespace. To do this follow the Helm instructions to deploy Tiller into a namespace.
With Kubectl and Helm configured to point to your PKS environment the last thing we need to obtain is the mq-container sample source from GitHub. Navigate to a directory you wish to store the source in then run the following command, if you have golang installed we suggest you run git clone in $(GOROOT)/src/github.com/ibm-messaging.
git clone https://github.com/ibm-messaging/mq-container.git
Once git has finished downloading the source you should see a new directory called mq-container. This directory contains all the files we need to deploy both versions of the IBM MQ chart.
Deploying the IBM MQ Advanced Developer helm chart
The IBM MQ Advanced Developer helm chart found in mq-container/charts/ibm-mqadvanced-server-dev can be used to deploy a IBM MQ Advanced for Developers Queue Manager in your PKS environment. The IBM MQ Advanced for Developers version of IBM MQ is free to use for Development only; it cannot be used in production environments and is unwarranted and unsupported.
The IBM MQ Advanced Developer chart deploys a container image that is stored on docker hub. This image is currently built from the ibm-messaging/mq-docker GitHub source and stored under the ibmcom/mq repository in docker hub. Because of this we don’t need to build our own image meaning you are ready to deploy the Helm chart! (you must have completed all the steps in the Prerequisites section of this blog post)
Before we can deploy the IBM MQ chart we have to learn the name of a Kubernetes storageclass we can use. The MQ pod uses persistent storage to retain Queue Manager data between pod restarts. To discover what storageclasses are available to us run the following command:
kubectl get storageclass --namespace <your-namespace>
Choose a storageclass from the returned list and make a note of the name to use in the Helm chart deployment. For example, here you can see there is only one storageclass called slow.
If you want your Kubernetes cluster to be public facing, then you will need to create a LoadBalancer service. You can do this when you deploy the Helm Chart. If you do not want the Queue Manager to be externally accessible and instead want to only access it via pods internal to the Kubernetes cluster then do not set the service.type helm flag.
To deploy the Helm chart to your PKS environment run the following commands:
cd mq-container/charts/ibm-mqadvanced-server-dev
helm install . --tiller-namespace <your-namespace> --namespace <your-namespace> --set license=accept --set queueManager.name=<Queue-Manager-name> --set dataPVC.storageClassName=<your-storageclass-name> --set service.type=LoadBalancer
You should see output from the command telling you the names of your deployment and how to retrieve the admin password for your Queue Manager.
Congratulations! You have successfully deployed IBM MQ into your PKS environment and the Queue Manager should be starting. You can see the status of the Queue Manager pod by executing kubectl get pods --namespace <your-namespace>. Once the pod is running you can see the output from the startup script by running kubectl logs <pod-name> --namespace <your-namespace>. If you wish to see the Queue Manager logs you can either log into the pod by executing kubectl exec -it <pod-name> --namespace <your-namespace> bash or just view the Queue Manager log by running kubectl exec <pod-name> --namespace <your-namespace> cat /var/mqm/qmgrs/<Queue-Manager-Name>/errors/AMQERR01.LOG
You will notice that your helm chart has named everything randomly using two words separated by a hyphen. For example, in the output above my deployment has been called kissing-turtle. You should make a note of this as you will need to know your deployment name to ensure you connect to and delete the correct deployment.
You can now follow the steps in the Connecting to your Queue Manager section of this blog post to connect to your Queue Manager.
Once you are finished with your deployment follow the steps in the Deleting your Helm deployment section of this blog post to delete the Queue Manager and its associated resources from your PKS environment.
Deploying the IBM MQ Advanced production helm chart
The IBM MQ Advanced production helm chart found in mq-container/charts/ibm-mqadvanced-server-prod can be used to deploy a IBM MQ Advanced Queue Manager in your PKS environment. This chart expects a container image to be provided to it that contains a production version of IBM MQ 9 Continuous delivery. This image must be built by yourself and stored in a private registry ready to be used.
The image the helm chart expects is the image that can be built using the make files in the ibm-messaging/mq-container Github repository. Before we can build the image, however, we need a few additional tools. You should ensure your environment has the following tools:
- docker – https://www.docker.com/
- Glide – https://github.com/Masterminds/glide
- GoLang –
- deps – https://github.com/golang/dep
- make
If you haven’t already done so, you should move the mq-container folder you downloaded using the Git clone command in the Prerequisites section into your go-lang source root. The location it should be moved to is:
$(GOROOT)/src/github.com/ibm-messaging
You should now follow the instructions on the mq-container page to build your IBM MQ Advanced production image.
With the image built you should now push the image to a private registry using docker login and docker push. You should follow instructions given by your private registry on how to log docker into that registry and push images to it.
Before we can deploy the helm chart we need to create a Kubernetes secret which contains our private container registry login details. These credentials are used by PKS to pull the image from your private registry when it creates the pod. For more information on pulling images from private registry’s see the Kubernetes documentation on using a private registry.
Run the following command to create a Kuberenetes secret called myregistrykey:
kubectl create secret --namespace <your-namespace> docker-registry myregistrykey --docker-server=<Private container-registry-server> --docker-username=<Username-for-private-registry> --docker-password=<Password-for-private registry> --docker-email=<Email-associated-with-private-registry-account>
Before we can deploy the IBM MQ production chart we have to learn the name of a Kubernetes storageclass we can use. The MQ pod uses persistent storage to retain Queue Manager data between pod restarts. To discover what storageclasses are available to us run the following command:
kubectl get storageclass --namespace <your-namespace>
Choose a storageclass from the returned list and make a note of the name to use in the Helm chart deployment. For example, here you can see there is only one storageclass called slow:
If you want your Kubernetes cluster to be public facing, then you will need to create a LoadBalancer service. You can do this when you deploy the Helm Chart. If you do not want the Queue Manager to be externally accessible and instead want to only access it via pods internal to the Kubernetes cluster then do not set the service.type helm flag.
Now that the Kubernetes secret has been created and you have all the necessary information about your PKS environment we can deploy the Helm chart referencing the image in your private container registry. Run the following commands to deploy a IBM MQ Advanced Queue Manager:
cd mq-container/charts/ibm-mqadvanced-server-prod
helm install . --tiller-namespace <your-namespace> --namespace <your-namespace> --set license=accept --set queueManager.name=<Queue-Manager-name> --set dataPVC.storageClassName=<your-storageclass-name> --set service.type=LoadBalancer --set image.repostitory=<Your-full-image-name-with-registry> --set image.tag=<Tag-of-the-image-you-want-to-use> --set image.pullSecret=<Your-secret,-i.e.-myregistrykey>
You should see output from the command telling you the names of your deployment.
Congratulations! You have successfully deployed IBM MQ into your PKS environment and the Queue Manager should be starting. You can see the status of the Queue Manager pod by executing kubectl get pods --namespace <your-namespace>. Once the pod is running you can see the output from the startup script by running kubectl logs <pod-name> --namespace <your-namespace>. If you wish to see the Queue Manager logs you can either log into the pod by executing kubectl exec -it <pod-name> --namespace <your-namespace> bash or just view the Queue Manager log by running kubectl exec <pod-name> --namespace <your-namespace> cat /var/mqm/qmgrs/<Queue-Manager-Name>/errors/AMQERR01.LOG
You will notice that your helm chart has named everything randomly using two words separated by a hyphen. You should make a note of this as you will need to know your deployment name to ensure you connect to and delete the correct deployment.
You can now follow the steps in the Connecting to your Queue Manager section of this blog post to connect to your Queue Manager.
Once you are finished with your deployment follow the steps in the Deleting your Helm deployment section of this blog post to delete the Queue Manager and its associated resources from your PKS environment.
Connecting to your Queue Manager in PKS
If you deployed your Helm chart using the LoadBlancer service your Queue Manager will have an external endpoint. To be able to connect to the Queue Manager we need to find what IP address the LoadBalancer is serving on. To do this run the following command:
kubectl get service --namespace <your-namespace>.
You should see a list of services, one of these services will be named with a prefix that matches your helm deployment name. For example, my deployment is called kissing-turtle so in the kubectl output I will look at the external IP associated with that service
For obvious reasons I have blanked out the external IP addresses of my services. If your external IP says then you should wait a few mins before running the kubectl command again.
You can now connect to the IBM MQ Console by navigating to the following URL in a Web Browser:
https://<IP-Address>:9443/ibmmq/console
Please note: The IBM MQ console is currently not available on the production helm chart or image.
The credentials to log into the IBM MQ console are admin and the password can be retrieved by executing the command that was displayed when the helm chart was deployed.
If you want to connect a IBM MQ Client application (including MQ explorer) then you should use a connection name of <IP-Address>(1414).
Deleting your Helm deployment
Once you are ready to delete your Helm deployment you need to know the name of your deployment. If you have forgotten the name of your Helm deployment you can run the following command to list all the deployments running in your PKS environment under your namespace
helm list --tiller-namespace <your-namespace>
Once you have the name of your helm deployment you want to delete run the following command to delete it:
helm delete --tiller-namespace <your-namespace> --purge <Helm-deployment-name>
Once your command returns you need to delete the Kubernetes persistent volume claim (PVC) as this is not deleted by Helm. Run the following command to list your PVCs available on your PKS environment:
kubectl get pvc --namespace <your-namespace>
From the list returned you should see one that has a prefix that matches your deployment name. Once you have this run the following command to delete the PVC from your PKS environment using the full PVC name.
This will cause the Persistent volume to be deleted and so all data on that volume deleted. (i.e. you Queue Manager data)
kubectl delete pvc --namespace <your-namespace> <PVC name>
Command quick reference
In this section you will find commands mentioned in this blog post and what they do.
git clone https://github.com/ibm-messaging/mq-container.git
Downloads the ibm-messaging/mq-container repository from GitHub which contains the source of the sample we used in this blog post.
kubectl get storageclass --namespace <your-namespace>
Returns the storageclasses configured in your PKS environment that are available for use in your namespace.
kubectl get pods --namespace <your-namespace>
Lists all the pods and their status in your namespace in your PKS environment. You can also add the -w flag to have it constantly update when a pod is added/deleted or changes status.
kubectl logs <pod-name> --namespace <your-namespace>
Displays the pod logs of the given pod running in your namespace. These logs are the outputs of the start-up program that runs on the pod to create, start and configure your Queue Manager. You can append the -f flag to follow the logs and see new updates as they happen.
kubectl exec -it <pod-name> --namespace <your-namespace> bash
Connects your terminal to the specified pod and opens a bash terminal. This allows you to navigate around the pod to view logs or debug problems. However please remember, any changes you make to the pod will be lost when the pod restarts.
kubectl exec <pod-name> --namespace <your-namespace> cat /var/mqm/qmgrs/<Queue-Manager-Name>/errors/AMQERR01.LOG
Displays the Queue Manager AMQERR01.LOG on the specified pod.
kubectl create secret --namespace <your-namespace> docker-registry <Secret-name> --docker-server=<Private container registry server> --docker-username=<Username for private registry> --docker-password=<Password for private registry> --docker-email=<Email associated with private registry account>
Creates a Kubernetes secret that can be used by PKS to log into a private container registry and retrieve an image.
kubectl get service --namespace <your-namespace>
Returns a list of the Kubernetes services running in your namespace. You can also add the -w flag to have it constantly update when a service is added/deleted or changes status.
helm list --tiller-namespace <your-namespace>
Lists all of the helm deployments in your namespace
helm delete --tiller-namespace <your-namespace> --purge <Helm deployment name>
Deletes a helm deployment from your namespace.
kubectl get pvc --namespace <your-namespace>
Returns a list of all the Persistent Volume Claims in your namespace.
kubectl delete pvc --namespace <your-namespace> <PVC name>
Deletes a specified Persistent Volume Claims from your namespace.
This will cause the Persistent volume to be deleted and so all data on that volume deleted. (i.e. you Queue Manager data)