Procedure

1. Log in to OpenShift as a cluster administrator:

   $ oc login -u system:admin

2. Switch to the openshift project.

   $ oc project openshift

3. Verify that the latest version of the AMQ Interconnect image stream is available:

   $ oc get imagestreamtag -n openshift | grep amq-interconnect:latest

   If the latest version of the image stream is available in your environment, you should see amq-interconnect:latest in the command output.

4. Is the latest version of AMQ Interconnect image stream available?

   • If yes, proceed to the next step.

   • If no, install the latest version of the image stream.

     This command imports the latest AMQ Interconnect image stream into the openshift namespace:

     $ oc import-image amq-interconnect:latest -n openshift --from=registry.access.redhat.com/amq7/amq-interconnect --confirm

5. Install the AMQ Interconnect application templates:

   $ curl https://raw.githubusercontent.com/jboss-container-images/amq-interconnect-1-openshift-image/amq-interconnect-1.3/templates/amq-interconnect-1-basic.yaml | oc create -f -
   
   $ curl https://raw.githubusercontent.com/jboss-container-images/amq-interconnect-1-openshift-image/amq-interconnect-1.3/templates/amq-interconnect-1-tls-auth.yaml | oc create -f -
   
   $ curl https://raw.githubusercontent.com/jboss-container-images/amq-interconnect-1-openshift-image/amq-interconnect-1.3/templates/amq-interconnect-1-sasldb-auth.yaml | oc create -f -

   This creates three AMQ Interconnect application templates, which you can use to deploy AMQ Interconnect on OpenShift Container Platform:

   amq-interconnect-1-basic.yaml

   Deploys a router with a basic, default configuration and no security.

   amq-interconnect-1-tls-auth.yaml

   Deploys a router with both inter-router and client traffic secured by TLS authentication.

   amq-interconnect-1-sasldb-auth.yaml

   Deploys a router with inter-router traffic secured by TLS authentication and client traffic secured by SASL user name and password authentication.

Procedure

1. If you do not have an existing certificate authority (CA) certificate for inter-router connections, create one.

   These commands create a self-signed CA certificate for inter-router connections:

   # Create a new directory for the inter-router certificates.
   $ mkdir internal-certs
   
   # Create a private key for the CA.
   $ openssl genrsa -out internal-certs/ca-key.pem 2048
   
   # Create a certificate for the CA.
   $ openssl req -new -batch -key internal-certs/ca-key.pem -out internal-certs/ca-csr.pem
   
   # Self sign the certificate.
   $ openssl x509 -req -in internal-certs/ca-csr.pem -signkey internal-certs/ca-key.pem -out internal-certs/ca.crt

2. Create a certificate for the router signed by the CA.

   These commands create a private key and a certificate, and sign the certificate using the CA created in the previous step:

   # Create a private key.
   $ openssl genrsa -out internal-certs/tls.key 2048
   
   # Create a certificate for the router.
   $ openssl req -new -batch -subj "/CN=amq-interconnect.myproject.svc.cluster.local" -key internal-certs/tls.key -out internal-certs/server-csr.pem
   
   # Sign the certificate using the CA.
   $ openssl x509 -req -in internal-certs/server-csr.pem -CA internal-certs/ca.crt -CAkey internal-certs/ca-key.pem -out internal-certs/tls.crt -CAcreateserial

3. Create a secret containing the private key, router certificate, and CA certificate.

   This command creates the secret using the key and certificates that were created in the previous steps:

   $ oc create secret generic inter-router-certs --from-file=tls.crt=internal-certs/tls.crt  --from-file=tls.key=internal-certs/tls.key  --from-file=ca.crt=internal-certs/ca.crt

4. If you want to use SSL/TLS to authenticate client connections (as opposed to authenticating clients using SASL), create a CA certificate for client connections.

   These commands create a self-signed CA certificate for client connections:

   # Create a new directory for the client certificates.
   $ mkdir client-certs
   
   # Create a private key for the CA.
   $ openssl genrsa -out client-certs/ca-key.pem 2048
   
   # Create a certificate for the CA.
   $ openssl req -new -batch -key client-certs/ca-key.pem -out client-certs/ca-csr.pem
   
   # Self sign the certificate.
   $ openssl x509 -req -in client-certs/ca-csr.pem -signkey client-certs/ca-key.pem -out client-certs/ca.crt

5. Create a certificate for client connections signed by the CA.

   These commands create a private key and a certificate, and then sign the certificate using the CA created in the previous step:

   # Create a private key.
   $ openssl genrsa -out client-certs/tls.key 2048
   
   # Create a certificate for the client connections.
   $ openssl req -new -batch -subj "/CN=myclient" -key client-certs/tls.key -out client-certs/client-csr.pem
   
   # Sign the certificate using the CA.
   $ openssl x509 -req -in client-certs/client-csr.pem -CA client-certs/ca.crt -CAkey client-certs/ca-key.pem -out client-certs/tls.crt -CAcreateserial

6. Create a secret containing the CA certificate used to sign client certificates.

   This command creates the secret using the certificate that was created in the previous steps:

   $ oc create secret generic client-ca --from-file=ca.crt=client-certs/ca.crt

Procedure

1. Create a text file containing the client user names and passwords.

   Use the following syntax: <username>=<password>.

   In this example, the user names and passwords are defined for three users:

   users.txt

   guest=guest
   admin=admin123
   dev=dev123

2. Create a secret containing the user names and passwords.

   This command creates a secret (users) containing the users.txt file created in the previous step.

   $ oc create secret generic users --from-env-file=./users.txt --dry-run=true -o yaml | oc apply -f -

Procedure

1. Navigate to Applications → Routes.
2. Click Create Route.

3. Enter a Name for the route.

   The name will be the first part of the route host name.

4. If necessary, enter a Hostname and Path.

5. Select the Target Port.

   To create a route for…​	Select this port…​
   External clients or message brokers to connect to the router mesh without authentication	5672
   External clients or message brokers to connect to the router mesh with authentication	5671
   External routers to connect to the router mesh	55672
   Accessing the web console	8672

6. If necessary, secure the route.

   1. Click Secure route.

   2. In the TLS Termination drop-down, select Passthrough.

      The route is secured using the security certificates that you created and passed to OpenShift as secrets.

7. Click Create.

   The route is created.

Procedure

1. Navigate to Resources → Config Maps.

   The amq-interconnect config map contains the configuration for each router in the router mesh.

2. Click amq-interconnect.
3. Select Actions → Edit.

4. In the Value text box, add a connector entity.

   A connector defines an outgoing connection from a router to an external AMQP container (in this case, a broker).

   This example defines a connection to a broker:

   connector {
       name: broker
       role: route-container
       host: 192.0.2.1  1
       port: 61616
       saslMechanisms: ANONYMOUS
   }

   1

   If the broker is running in the same OpenShift cluster as the router mesh, then use the service IP address. If the broker is running in a different OpenShift cluster, then use the fully-qualified domain name of that OpenShift cluster’s route.

5. Click Save.

6. To apply the changes, trigger a new deployment.

   1. Navigate to Applications → Deployments.
   2. Click amq-interconnect.

   3. Click Deploy.

      A new deployment is started and becomes active.

7. In a terminal, run the qdstat command from one of the router pods to verify that the routers can connect to the broker.

   This example shows that the router is connected to the broker on the 192.0.2.1 host.

   $ oc exec amq-interconnect-4-5qkqz -it -- qdstat -c
   Connections
     id  host                 container                             role             dir  security     authentication  tenant
     ==========================================================================================================================
     1   192.0.2.1:61616      0.0.0.0                               route-container  out  no-security  anonymous-user
     6   203.0.113.10:49806   amq-interconnect-4-mshr4              inter-router     in   no-security  anonymous-user
     4   203.0.113.11:33312   amq-interconnect-4-5qkqz              inter-router     in   no-security  anonymous-user
     5   203.0.113.3:40484    amq-interconnect-4-ds7lp              inter-router     in   no-security  anonymous-user
     39  127.0.0.1:60678      e3c03c50-4d6d-4962-bc53-65480ab8ae0e  normal           in   no-security  no-auth

Procedure

1. In the first OpenShift cluster, create a route that is accessible to the second OpenShift cluster.

   The route should target port 55672, and it should be secured with SSL/TLS passthrough. For more information, see Section 4.1, “Creating routes”.

2. In the second OpenShift cluster, create a connector to the route that you created in the previous step.

   1. Navigate to Resources → Config Maps.

      The amq-interconnect config map contains the configuration for each router in the router mesh.

   2. Click amq-interconnect.
   3. Select Actions → Edit.

   4. In the Value text box, add a connector entity.

      A connector defines an outgoing connection from a router to an external AMQP container (in this case, the routers in the first OpenShift cluster).

      This example defines a connection to a router running in a different OpenShift cluster:

      connector {
          name: router
          role: inter-router
          host: first-router-mesh-myproject.192.0.2.1.nip.io  1
          port: 443
          sslProfile: inter_router_tls  2
          verifyHostname: no
      }

      1

      The host name of the route that you created in the first OpenShift cluster.

      2

      The name of the SSL/TLS profile that defines the private keys and certificates used to secure inter-router traffic.

   5. Click Save.

3. Start a new deployment to apply the configuration change to the routers.

   1. Navigate to Applications → Deployments.
   2. Click amq-interconnect.

   3. Click Deploy.

      A new deployment is started and becomes active. The routers in the second OpenShift cluster connect to the routers in the first OpenShift cluster to form a distributed router mesh that spans OpenShift clusters.

Procedure

1. Navigate to the URL for the HTTP route.

   To see a list of routes for your OpenShift cluster, navigate to Applications → Routes.

   The Red Hat AMQ Interconnect Console opens. If you deployed AMQ Interconnect using the Red Hat AMQ Interconnect Router 1.x with TLS authentication template, the Connect tab is displayed.

2. If necessary, log in to the web console.

   If you deployed AMQ Interconnect using the Red Hat AMQ Interconnect Router 1.x with TLS authentication template, use the user name and password that you entered when you deployed the template. To find the user name and password, navigate to Resources → Secrets → amq-interconnect-users.

   The syntax for the user name is <user>@<domain> (the domain is the OpenShift application name; amq-interconnect is the default value). For example, admin@amq-interconnect.

3. Use the tabs to monitor the router mesh.

   This tab…​	Provides…​
   Overview	Aggregate information about routers, addresses, links, connections, and logs.
   Entities	Detailed information about each AMQP management entity for each router in the router mesh.
   Topology	A graphical view of the router network. The topology shows how the routers are connected, and how messages are flowing through the network.
   Charts	Graphs of the information that is displayed on the Entities tab.
   Message Flow	A chord diagram showing the real-time message flow by address.
   Schema	The management schema that controls each of the routers in the router mesh.

Procedure

1. Navigate to the Overview page.

2. Do one of the following:

   • To add routers to the mesh, click the up arrow next to the pods diagram.

     A new pod is deployed, with a router running inside of it. The router automatically connects to each router in the mesh to maintain a full mesh topology.

   • To remove routes from the mesh, click the down arrow next to the pods diagram.

     A pod is removed from the deployment, and its router is shut down. Any clients that were connected to the router are disconnected, but can fail over to any of the remaining routers in the mesh.

Procedure

1. Navigate to Resources → Config Maps.

   The amq-interconnect config map contains the configuration for each router in the router mesh.

2. Click amq-interconnect.
3. Select Actions → Edit.
4. In the Value text box, change the router configuration as needed.
5. Click Save.
6. Navigate to Applications → Deployments.
7. Click amq-interconnect.

8. Click Deploy.

   A new deployment is started and becomes active. The configuration changes you made are applied to each router in the router mesh.