[Preview]

This chart has been provided for the purposes of a Preview only. It is unsupported and therefore not suitable for production environments.

Feedback may be provided by creating a new issue in this repository, however there is no commitment that we will respond to or resolve all issues that are raised.

Preview of IBM MQ Operator on Amazon Elastic Kubernetes Service (Amazon EKS)

This chart deploys an IBM MQ Operator Deployment into a namespace. The QueueManager CRD will be deployed from this chart if and only if a version of it does not already exist in the cluster. The IBM MQ Operator needs to be installed by a cluster administrator.

Page Contents

Installation

• Installation Part 1 : Pre-Req Instructions
• Installation Part 2 : Installing the Chart
  • Example Steps : Installing the Chart
• Installation Part 3 : Deploying an IBM MQ Queue Manager
  • Example Steps : Deploying an IBM MQ Queue Manager

Upgrade

• Upgrade Part 1 : Pre-Req Instructions
• Upgrade Part 2 : Upgrading the CRD and Chart
  • Example Steps : Upgrading the CRD and Chart
• Upgrade Part 3 : Upgrading an IBM MQ Queue Manager
  • Example Steps : Upgrading an IBM MQ Queue Manager

Connecting to a Queue Manager

• Example : Deploying a Queue Manager using the IBM MQ Operator and making a mutual TLS connection from a client application
• Example : Configuring Ingress to connect to a queue manager from outside an Amazon EKS cluster

Installation

Installation Part 1 : Pre-Req Instructions

In order to secure the validating WebHook for the IBM MQ Operator, you must create a Kubernetes TLS secret in the namespace where the MQ Operator will be installed. This Kubernetes TLS secret must contain a private key and public certificate. The Subject Alternative Name (SAN) for the public certificate must include ibm-mq-operator-webhook.<namespace>.svc - where <namespace> is the namespace where the MQ Operator will be installed.

• The default expected name for this Kubernetes TLS secret is ibm-mq-operator-service-cert
• If you wish to use a different name, you must override the value for operator.webhook.secretName using --set operator.webhook.secretName=<your-secret-name>, or in a file using, for example, --values overrides.yaml when running the Helm install command.

You are also required to provide the CA bundle which will be used to verify your public certificate. This should be in the format of a base64 encoded series of one-or-more PEM encoded certificates.

• You must override the value for operator.webhook.caBundle using --set operator.webhook.caBundle=LS0tLS1CR... or in a file using, for example, --values overrides.yaml when running the Helm install command.

Installation Part 2 : Installing the Chart

To install this chart, first complete the pre-req instructions, then clone this repository and issue the following command from within the chart directory:

helm install ibm-mq-operator --namespace <namespace> <--set arguments> .

For further information regarding configuring your IBM MQ Operator installation and instructions for uninstalling the chart, view the chart README

Example Steps : Installing the Chart

The following steps can be used to get going quickly with the Preview. The Helm v3, OpenSSL and base64 command line tools are required and you must be logged-into your cluster. These instructions were tested with Helm v3.18.2 and OpenSSL v3.3.2.

Note, this method would not be suitable for production environments. Certificate management is a complex subject for advanced users. For production, you must consider things like rotation, revocation, key length, disaster recovery and much more.

Important: in the following set of instructions, replace all occurrences of <namespace> with the namespace where the MQ Operator will be installed. This is required in steps (4), (6) and (7).

1. Clone this repository to your local machine and then issue the following command:

cd chart

2. Create a private key to use for your internal certificate authority

openssl genpkey -algorithm rsa -pkeyopt rsa_keygen_bits:4096 -out ca.key

• A private key for the internal certificate authority is created in a file called ca.key. This file should be kept safe and secret — it will be used to sign certificates for your internal certificate authority.

3. Issue a self-signed certificate for your internal certificate authority

openssl req -x509 -new -nodes -key ca.key -sha512 -days 120 -subj "/CN=example-selfsigned-ca" -out ca.crt

• The -days specifies the number of days that the root CA certificate will be valid. A certificate is created in a file called ca.crt. This certificate contains the public information about the internal certificate authority, and is freely shareable.

4. Create a private key and certificate signing request for the validating WebHook

Important: in the following command, replace <namespace> with the namespace where the MQ Operator will be installed

openssl req -new -nodes -addext 'subjectAltName=DNS:ibm-mq-operator-webhook.<namespace>.svc' -subj '/CN=example-webhook' -out example-webhook.csr -newkey rsa:4096 -keyout example-webhook.key

• A private key is created in a file called example-webhook.key, and a certificate signing request is created in a file called example-webhook.csr.

5. Sign the validating WebHook key with your internal certificate authority

openssl x509 -req -in example-webhook.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out example-webhook.crt -days 120 -sha512 -copy_extensions copy

• The -days specifies the number of days that the certificate will be valid. A signed certificate is created in a file called example-webhook.crt.

6. Create the Kubernetes TLS secret for the validating WebHook

Important: in the following command, replace <namespace> with the namespace where the MQ Operator will be installed

kubectl create secret tls ibm-mq-operator-service-cert -n <namespace> --key=example-webhook.key --cert=example-webhook.crt

• A Kubernetes TLS secret called ibm-mq-operator-service-cert is created. This secret contains the private key and public certificate for the validating WebHook.

7. Install the IBM MQ Operator

Important: in the following command, replace <namespace> with the namespace where the MQ Operator will be installed

helm install ibm-mq-operator --namespace <namespace> --set operator.webhook.caBundle=$(openssl x509 -in ca.crt | base64) .

• The MQ Operator will now be installed in your chosen namespace. Follow the instructions displayed in your terminal to validate the install. The next step is to deploy an IBM MQ Queue Manager.

Installation Part 3 : Deploying an IBM MQ Queue Manager

The IBM MQ Operator deploys queue manager images that are pulled from a container registry that performs a license entitlement check. Follow these instructions to get an entitlement key and create a pull secret.

Note: The entitlement key is not required if only IBM MQ Advanced for Developers (Non-Warranted) queue managers are going to be deployed.

To deploy a queue manager, see Deploying and configuring queue managers using the IBM MQ Operator. Queue managers can be installed by a namespace administrator.

Important: When deploying an IBM MQ queue manager on Amazon Elastic Kubernetes Service (Amazon EKS), all Red Hat OpenShift Container Platform features MUST be explicitly disabled as follows:

# QueueManager YAML snippet
...
spec:
  queueManager:
    ...
    route:
      enabled: false
    metrics:
      serviceMonitor:
        enabled: false
  web:
    ...
    route:
      enabled: false

Example Steps : Deploying an IBM MQ Queue Manager

The following steps can be used to get going quickly with the Preview, they will deploy a basic MQ V9.4.3.0 queue manager.

Note: Unless you have performed a cluster-scoped (AllNamespaces) install of the IBM MQ Operator, you should deploy your queue manager in the same namespace where you installed the IBM MQ Operator. Replace <namespace> with the appropriate namespace in steps (3) and (4).

1. Create an Entitlement Key Secret

Follow these instructions to get an entitlement key and create a pull secret.

2. Create a QueueManager YAML file

Create the file mq-quickstart.yaml with the following contents:

apiVersion: mq.ibm.com/v1beta1
kind: QueueManager
metadata:
  name: quickstart
  annotations:
    com.ibm.mq/write-defaults-spec: 'false'
spec:
  version: 9.4.3.0-r1
  license:
    accept: false
    license: L-NUUP-23NH8Y
  queueManager:
    name: "QUICKSTART"
    storage:
      queueManager:
        type: ephemeral
    route:
      enabled: false
    metrics:
      serviceMonitor:
        enabled: false
  web:
    enabled: false
    route:
      enabled: false

Important: If you accept the license agreement, change accept: false to accept: true. See mq.ibm.com/v1beta1: Current license versions for details on the license.

3. Create the Queue Manager

kubectl apply -f mq-quickstart.yaml -n <namespace>

4. Verify the Queue Manager Status

kubectl get queuemanager quickstart -n <namespace>

Upgrade

Upgrade Part 1 : Pre-Req Instructions

• Ensure the installed MQ operator, and any Queue Managers, are running.
• Ensure the local git branch is uptodate, for example by running git fetch, git pull.
• Before updating the CRD, validate that a newer version of the CRD was not previously installed on the cluster.
• Compared with the first preview, there have been changes to the following values fields. If you changed or overrode any of these when installing or upgrading previously, you must specify the equivalent new fields when upgrading.
  • operator.deployment.repository
  • operator.deployment.image
• For all other values fields, you must specify the same fields and values specified on previous installs or upgrades. You may have previous set values by:
  • using --set <field=value>
  • using --values <afile.yaml>
  • changing the original values.yaml (This is not recommended.)

Upgrade Part 2 : Upgrading the CRD and Chart

To upgrade, first complete the pre-req instructions, then complete the following two steps from within the chart directory:

1. Upgrade CRD

   kubectl apply --server-side --force-conflicts -f crds/queuemanagers.yaml
   

   Note: --force-conflicts is only needed the first time the CRD is upgraded.

2. Upgrade Helm release

   a. Check the user-supplied values specified when performing the previous install or upgrade:

   helm get values ibm-mq-operator
   

   b. Upgrade the helm chart, specifying the same values:

   helm upgrade --reset-values ibm-mq-operator --namespace <namespace> <--set arguments> .
   

   Note: helm upgrade has an alternative flag --reset-then-reuse-values. The flag's documented behavior is 'reset the values to the ones built into the chart, apply the last release's values and merge in any overrides from the command line via --set and -f.' This flag may reduce the likelihood of accidentally omittting previously specified values. However, the final state following upgrades using --reset-then-reuse-values is dependent on the initial state, so can vary for each upgrade, or for each environment.

Example Steps : Upgrading the CRD and Chart

The following example steps assume the IBM MQ Operator was previously installed following the Installation instructions.

To upgrade, first complete the Upgrade Part 1 : Pre-Req Instructions, and then run the following two commands:

1. Upgrade CRD

   kubectl apply --server-side --force-conflicts -f crds/queuemanagers.yaml
   

2. Upgrade Helm chart

   a. Check the user-supplied values specified when performing the previous install or upgrade:

   helm get values ibm-mq-operator
   

   b. Ensure you have the previously used ca.crt file

   You must have the ca.crt file from the previous install or upgrade, which contains the public information about the internal certificate authority. You can retrieve the contents of the ca.crt file from the cluster if required, for example by changing <namespace> twice in the following command, then executing it:

   kubectl get ValidatingWebhookConfiguration ibm-mq-operator-webhook-<namespace> -n <namespace> -o jsonpath='{.webhooks[0].clientConfig.caBundle}' | base64 -D > ca.crt
   

   c. Upgrade the release

   To perform the upgrade of the helm chart, change <namespace> in the following command, then execute it:

   helm upgrade --reset-values ibm-mq-operator --namespace <namespace> --set operator.webhook.caBundle=$(openssl x509 -in ca.crt | base64) .
   

   The MQ Operator will now be upgraded in your chosen namespace. Follow the instructions displayed in your terminal to validate the upgrade. The next step is to upgrade an IBM MQ Queue Manager.

Upgrade Part 3 : Upgrading an IBM MQ Queue Manager

To upgrade an installed and running queue manager, update the following field of the Queue Manager YAML:

• spec.version

For some upgrades, you may also need to update the license.

• spec.license.license

See Current license versions for more details.

To upgrade, update the field(s) in the Queue Manager yaml by, for example, running:

kubectl edit queuemanager <Queue Manager's metadata.name> -n <namespace>

Example Steps : Upgrading an IBM MQ Queue Manager

The following example steps assume an IBM MQ Queue Manager was previously installed following the Installation Part 3 : Deploying an IBM MQ Queue Manager.

1. Ensure the existing quickstart queue manager is running:

   kubectl get qmgr quickstart -n <namespace>
   

2. Upgrade the Queue Manager

   To upgrade the quickstart queue manager to 9.4.4, update the following field of the Queue Manager YAML: - spec.version: 9.4.4.0-r1

   Update the version field in the Queue Manager yaml, by running the following command:

   kubectl edit queuemanager quickstart -n <namespace>
   

3. Verify the Queue Manager Status

   kubectl get queuemanager quickstart -n <namespace>
   

Connecting to a Queue Manager

For example steps to connect to a Queue Manager, see:

Example : Deploying a Queue Manager using the IBM MQ Operator and making a mutual TLS connection from a client application

• To connect a client application to a new queue manager, see Configuring a LoadBalancer to connect to a queue manager with mutual TLS from a client application on your laptop for AWS EKS deployments

Example : Configuring Ingress to connect to a queue manager from outside an Amazon EKS cluster

• To configure an Ingress to access the IBM MQ Console/REST APIs Services of an existing queue manager, see Configuring Ingress to connect to a queue manager from outside an AWS EKS cluster