Using a Messaging server
Add components to a Messaging server so they can be consumed by messaging clients or application integrations to serve your use cases.
These components can be added to a Messaging server:
Messaging channel - creates a channel in the underlying Queue manager.
Messaging queue - creates a queue in the underlying Queue manager.
Messaging user - creates users, provides access to channels and queues, sets up an SSL peer mapping, and reports user statuses as conditions. The Messaging user creates a Certificate (with name
<.metadata.name>-client-cert) that an MQ client application uses to connect to the Queue manager via a channel and access the queues, including MQ client applications such as Integration design, or Integration runtimes.
You can add components by using the canvas or the UI Form view in the Platform UI, or the CLI.
Using the canvas
In the canvas, you can easily add users, channels, and queues, then consume these resources from Integration design or Integration runtimes instance that are created in the same canvas.
Log in to the Platform UI.
On the home page, click Build with assembly canvas. The canvas opens.
In the palette, expand Independent instances to find all the messaging instance types.
Do one of the following:
Skip this step if you want to reference an existing Messaging server but not add it to the canvas.
To create a new Messaging server for this canvas, drag and drop a Messaging server from the palette to the canvas.
To import an existing Messaging server to the canvas, click the Import existing instances button and select a pre-existing Messaging server.
Drag and drop the users, channels, and queues that you want to create.
Add channels and queues to a Messaging server by connecting them:
If the Messaging server is on the canvas already, simply draw a line from the queues and channels to the Messaging server.
If the Messaging server is not on the canvas (because you don't want to add that server to this canvas) double-click the queues and channels. The Edit panel opens. Select the Messaging server name in the same namespace.
Double-click each item to configure it.
(Optional) If you're not ready to deploy your assembly, save a draft version of it. Click the overflow menu (three-dot icon), then click Save as draft. The configuration for the assembly is stored in the Platform UI. You can continue editing the draft version until you are ready to create the assembly from it.
When all the messaging instances are configured, click Create to initiate deployment. You are redirected to the home page. The instances begin deployment and are initially in the Pending state. Click Pending to confirm the progress of the deployment.
The following example canvas has two messaging servers with queues, a channel, and a user, for processing customer orders and payments, respectively. The Messaging queue for payments is referencing a Messaging server that is not on this canvas.
Note that the components are connected to the left of the Messaging server.
Using the UI Form view
Follow these steps to create Messaging channels, Messaging queues, and Messaging users.
Log in to Platform UI.
Click Create an instance.
Click the tile for the messaging instance type you want to create, then click Next.
Click the tile for the instance template that you want, then click Next. You can customize the template in the next step.
To deploy by using a template from Automation assets, click Select a template from Automation assets.
On the Create page, enter values in the UI Form or YAML views to configure the queue, channel, or user. For more information, see Custom resource values.
(Optional) If you're not ready to deploy your instance, save a draft version of it. Click the overflow menu (three-dot icon), then click Save as draft. The configuration for the instance is stored in the Platform UI. You can continue editing the draft version until you are ready to create the instance from it.
Click Create to initiate deployment. You are redirected to the home page. The instance begins installing and is initially in the Pending state. Click Pending to get status details. When the deployment completes, the status changes to Ready (you can click the refresh button next to Create to refresh the status column).
Custom resource values
Configure the following custom resources to update Messaging channels, queues, and users.
Messaging server custom resource
The following table lists the configurable parameters and default values for the Messaging server custom resource.
| Parameter | Description | Default |
|---|---|---|
apiVersion |
The API version that identifies which schema is used. | integration.ibm.com/v1beta1 |
kind |
The resource type | MessagingServer |
metadata.name |
The unique short name by which the instance can be identified | |
metadata.namespace |
The namespace (project) in which the instance is deployed | |
spec.license.accept |
Set the value to true if you accept and to false if you do not. To install, this value must be set to true. |
false |
spec.license.license |
Select the appropriate license ID. For more information, see Licensing. | |
spec.license.use |
The type of license being accepted. For more information, see Licensing. | |
spec.queueManager |
The configuration of the Queue manager that is managed by this Messaging server. | |
spec.queueManager.storage |
The storage that you specify for the underlying Queue manager. For more information, see Storage considerations. | |
spec.queueManager.availability |
Configures the availability of the Queue manager that is managed by this Messaging server. When you specify NativeHA, the required certificates are automatically created and the Queue manager is configured to use them. |
SingleInstance |
spec.queueManager.name |
The name of the Queue manager that is managed by this Messaging server | Same as metadata.name |
spec.version |
The Messaging server version. Specify with a channel or a fully qualified version. |
Messaging queue custom resource
The following table lists the configurable parameters and default values for the Messaging queue custom resource.
| Parameter | Description | Default |
|---|---|---|
apiVersion |
The API version that identifies which schema is used | integration.ibm.com/v1beta1 |
kind |
The resource type | MessagingQueue |
metadata.name |
The unique short name by which the instance can be identified | |
metadata.namespace |
The namespace (project) in which the instance is deployed | |
spec.messagingServer.name |
The name of the Messaging server (in the same namespace as this Messaging queue) to which the queue should be added | |
spec.queue.type |
The type of queue to create | Local |
spec.queue.name |
The name of the queue that is created | Same as metadata.name |
spec.queue.maxQueueDepth |
The maximum number of messages allowed on the queue | 5000 |
spec.queue.maxMessageLength |
The maximum length for messages on the queue | 4194304 |
spec.queue.backoutQueueName |
The name of another Messaging queue where a message is transferred when a backout occurs | |
spec.queue.backoutThreshold |
The number of times a message can be backed out before it is transferred to the backout queue specified by spec.queue.backoutRequeueName |
0 |
spec.queue.defaultPersistence |
Specifies the default for message persistence on the queue. Message persistence determines whether messages are preserved across restarts of the Queue manager. | false |
Messaging channel custom resource
The following table lists the configurable parameters and default values for the Messaging channel custom resource.
| Parameter | Description | Default |
|---|---|---|
apiVersion |
The API version that identifies which schema is used | integration.ibm.com/v1beta1 |
kind |
The resource type | MessagingChannel |
metadata.name |
The unique short name by which the instance can be identified | |
metadata.namespace |
The namespace (project) in which the instance is deployed | |
spec.messagingServer.name |
The name of the Messaging server (in the same namespace as this Messaging channel) to which the channel should be added | |
spec.channel.name |
The name of this channel | Same as metadata.name |
spec.channel.type |
The type of this channel | ServerConnMTLS |
spec.sniRoute.enabled |
An SNI route is required if the MQ client is configured to use CHANNEL for OutboundSNI, but not required if it is configured to use HOSTNAME. Integration design always requires this route. If required, set this value to true to automatically create an SNI route. For more information about OutboundSNI, see OutboundSNI property in the MQ documentation. |
Messaging user custom resource
The following table lists the configurable parameters and default values for the Messaging user custom resource.
| Parameter | Description | Default |
|---|---|---|
apiVersion |
The API version that identifies which schema is used | integration.ibm.com/v1beta1 |
kind |
The resource type | MessagingUser |
metadata.name |
The unique short name by which the instance can be identified | |
metadata.namespace |
The namespace (project) in which the instance is deployed | |
spec.user.name |
The name of the (Messaging) user | Same as metadata.name |
spec.user.channel.name |
The name of the Messaging channel (in the same namespace) that this user will use | |
spec.user.queues |
A list of Messaging queues to which the user has access, and the permissions that the user has for each queue | |
spec.user.queues[].name |
The name of the Messaging queue (in the same namespace) to which this user has access | |
spec.user.queues[].auth |
A list of permissions this user has on the queue. Valid values are BROWSE, GET, INQ, PUT, and PASSALL | |
spec.configurations |
The list of App Connect account Configurations where the account information for this user is added | |
spec.configurations[].name |
The name of a Configuration. By default, it is in the same namespace as this Messaging user. | |
spec.configurations[].namespace |
The namespace containing the Configuration | Same as metadata.namespace |
spec.configurations[].accountName |
The account name to use in the Configuration | Same as metadata.name |
spec.designerAuthorings |
The list of Integration design instances where the account information for this user is added | |
spec.designerAuthorings[].name |
The name of an Integration design instance. By default, it is in the same namespace as this Messaging user. | |
spec.designerAuthorings[].namespace |
The namespace containing the Integration design instance | Same as metadata.namespace |
spec.designerAuthorings[].accountName |
The account name to use in the Integration design instance's Configuration | Same as metadata.name |
Connecting an MQ client by using a Messaging user
The Messaging user automatically creates a certificate that can be used to connect to the Queue manager as that user through the specified channel so that it has access to the queues listed in the Messaging user. The following sections describe how to obtain the connection details that you need to specify for the MQ client.
Host
The host is found in the Queue manager's route. The route is named <Messaging server .metadata.name>-ibm-mq-qm. For example,
if the Messaging server is named smallmessagingserver run this command to return the host:
oc get route smallmessagingserver-ibm-mq-qm -o jsonpath="{.spec.host}"Port
The port is 443
Channel name
The channel name is found in the the Messaging channel in metadata.name, unless it has be overridden by spec.channel.name. For example,
if the Messaging channel is named channel1 run this command to return the channel name:
oc get MessagingChannel channel1 -o json | jq -r ".spec.channel.name // .metadata.name"Queue manager name
The queue manager name is found in the Messaging server in metadata.name, unless it has be overridden by spec.queueManager.name. For example,
if the Messaging server is named smallmessagingserver run this command to return the queue manager name:
oc get MessagingServer smallmessagingserver -o json | jq -r ".spec.queueManager.name // .metadata.name"Certificates for the key repository
To get each of the certificates that you need to add to the key repository, run the following commands (which get the certficates from the secret for the Messenging user). Replace the example value, user1, with the name of the Messaging user.
oc get secret user1-client-cert -o json | jq -r '.data["ca.crt"]' | base64 --decode
oc get secret user1-client-cert -o json | jq -r '.data["tls.key"]' | base64 --decode
oc get secret user1-client-cert -o json | jq -r '.data["tls.crt"]' | base64 --decode