Chapter 6. Connecting external clients to templates-based broker deployments
This section describes how to configure SSL to enable connections from clients outside OpenShift Container Platform to brokers deployed using application templates.
6.1. Configuring SSL
For a minimal SSL configuration to allow connections outside of OpenShift Container Platform, AMQ Broker requires a broker keystore, a client keystore, and a client truststore that includes the broker keystore. The broker keystore is also used to create a secret for the AMQ Broker on OpenShift Container Platform image, which is added to the service account.
The following example commands use Java KeyTool, a package included with the Java Development Kit, to generate the necessary certificates and stores.
For a more complete example of deploying a broker instance that supports SSL, see Deploying a basic broker with SSL.
Procedure
Generate a self-signed certificate for the broker keystore:
$ keytool -genkey -alias broker -keyalg RSA -keystore broker.ks
Export the certificate so that it can be shared with clients:
$ keytool -export -alias broker -keystore broker.ks -file broker_cert
Generate a self-signed certificate for the client keystore:
$ keytool -genkey -alias client -keyalg RSA -keystore client.ks
Create a client truststore that imports the broker certificate:
$ keytool -import -alias broker -keystore client.ts -file broker_cert
Export the client’s certificate from the keystore:
$ keytool -export -alias client -keystore client.ks -file client_cert
Import the client’s exported certificate into a broker SERVER truststore:
$ keytool -import -alias client -keystore broker.ts -file client_cert
6.2. Generating the AMQ Broker secret
The broker keystore can be used to generate a secret for the namespace, which is also added to the service account so that the applications can be authorized.
Procedure
At the command line, run the following commands:
$ oc create secret generic <secret-name> --from-file=<broker-keystore> --from-file=<broker-truststore> $ oc secrets add sa/<service-account-name> secret/<secret-name>
6.3. Creating an SSL Route
To enable client applications outside your OpenShift cluster to connnect to a broker, you need to create an SSL Route for the broker Pod. You can expose only SSL-enabled Routes to external clients because the OpenShift router requires Server Name Indication (SNI) to send traffic to the correct Service.
When you use an application template to deploy a broker on OpenShift Container Platform, you use the AMQ_PROTOCOL template parameter to specify the messaging protocols that the broker uses, in a comma-separated list. Available options are amqp, mqtt, openwire, stomp, and hornetq. If you do not specify any protocols, all protocols are made available.
For each messaging protocol that the broker uses, OpenShift exposes a dedicated port on the broker Pod. In addition, OpenShift automatically creates a multiplexed, all protocols port. Client applications outside OpenShift always use the multiplexed, all protocols port to connect to the broker, regardless of which of the supported protocols they are using.
Connections to the all protocols port are via a Service that OpenShift automatically creates, and an SSL Route that you create. A headless service within the broker Pod provides access to the other protocol-specific ports, which do not have their own Services and Routes that clients can access directly.
The ports that OpenShift exposes for the various AMQ Broker transport protocols are shown in the following table. Brokers listen on the non-SSL ports for traffic within the OpenShift cluster. Brokers listen on the SSL-enabled ports for traffic from clients outside OpenShift, if you created your deployment using an SSL-based (that is, *-ssl.yaml) template.
| AMQ Broker transport protocol | Default port |
|---|---|
| All protocols (OpenWire, AMQP, STOMP, MQTT, and HornetQ) | 61616 |
| All protocols -SSL (OpenWire AMQP, STOMP, MQTT, and HornetQ) | 61617 |
| AMQP | 5672 |
| AMQP (SSL) | 5671 |
| MQTT | 1883 |
| MQTT (SSL) | 8883 |
| STOMP | 61613 |
| STOMP (SSL) | 61612 |
Below are some other things to note when creating an SSL Route on your broker Pod:
When you create a Route, setting TLS Termination to Passthrough relays all communication to AMQ Broker without the OpenShift router decrypting and resending it.
NoteRegular HTTP traffic does not require a TLS passthrough Route because the OpenShift router uses
HAProxy, which is an HTTP proxy.External broker clients must specify the OpenShift router port (443, by default) when setting the broker URL for SSL connections. When a client connection specifies the OpenShift router port, the router determines the appropriate port on the broker Pod to which the client traffic should be directed.
NoteBy default, the OpenShift router uses port 443. However, the router might be configured to use a different port number, based on the value specified for the
ROUTER_SERVICE_HTTPS_PORTenvironment variable. For more information, see OpenShift Container Platform Routes.Including the failover protocol in the broker URL preserves the client connection in case the Pod is restarted or upgraded, or a disruption occurs on the router.
Both of the previous settings are shown in the example below.
... factory.setBrokerURL("failover://ssl://<broker-pod-route-name>:443"); ...
Additional resources
- For a complete example of deploying a broker that supports SSL and of creating an SSL Route to enable external client access, see Deploying a basic broker with SSL.
- For an example of creating Routes for clustered brokers to connect to their own instances of the AMQ Broker management console, see Creating routes for the AMQ Broker management console.
