Configure NodePort service for direct mqtt access to the broker and d…

…ocument connecting devices to the Openshift

dev-tools/src/main/openshift/kapua-template.yml

@@ -547,3 +547,17 @@ objects:
       name: kapua-api
     port:
       targetPort: http
+
+- apiVersion: v1
+  kind: Service
+  metadata:
+    name: mqtt-ingress
+  spec:
+    ports:
+    - name: mqtt-tcp
+      port: 1883
+      nodePort: 31883
+    type: NodePort
+    selector:
+      app: kapua-broker
+      deploymentconfig: kapua-broker

docs/developer-guide/en/running.md

@@ -65,6 +65,26 @@ then you can also install Grafana for Hawkular to visualize your data:
 
     oc new-app -f https://raw.githubusercontent.com/hawkular/hawkular-grafana-datasource/master/docker/openshift/openshift-template-ephemeral.yaml
 
+### External access
+
+In order to enable devices to access Kapua we need to allow external access to the broker's MQTT connector. In the default deployment there are two ways to achieve this.
+
+First, the broker exposes MQTT over WebSocket transport. As WebSocket is based on HTTP we can define a router inside the Openshift to get those device connections to the broker.
+For example, if your Openshift deployment is running at the address `192.168.64.2`, you can connect the [Kura Simulator](../user-manual/simulator.md) like this
+
+```
+java -jar target/kapua-simulator-kura-*-SNAPSHOT-app.jar --broker ws://kapua-broker:[email protected]:80
+```
+
+Not all MQTT clients have WebSocket support, so we need to enable direct MQTT over TCP access to the broker as well. By default, Kapua comes with the NodePort service that routes all traffic from port `31883` to the broker.
+So you can connect your MQTT clients directly to this service. For the simulator example similar to the above, that would look something like
+
+```
+java -jar target/kapua-simulator-kura-0.2.0-SNAPSHOT-app.jar --broker tcp://kapua-broker:[email protected]:31883
+```
+
+This is suitable only for the local deployments. In the cloud or production environments, you should deploy a proper LoadBalancer Openshift service to enable external traffic flow to the broker.
+
 ### Ensuring enough entropy
 
  It may happen that firing up docker containers and starting up application which use

docs/user-manual/en/simulator.md

@@ -13,7 +13,7 @@ for this.
 The default main class is `org.eclipse.kapua.kura.simulator.main.SimulatorRunner`. It can be run after
 the module was built by be executing e.g. (which will print out some basic help):
 
-    java -jar target/kapua-simulator-kura-*-shaded.jar -?
+    java -jar target/kapua-simulator-kura-*-app.jar -?
 
 Once properly started the simulator will keep running (other forever or until the specified time elapsed)
 and then exit. While it is running it will try to stay connected to the broker. For more details about the
@@ -411,5 +411,5 @@ To start simulator with an example simulation configuration, run:
 
 ```
 export KSIM_SIMULATION_CONFIGURATION=$(curl -s https://raw.githubusercontent.com/eclipse/kapua/develop/simulator-kura/src/test/resources/example1.json)
-java -jar target/kapua-simulator-kura-*-shaded.jar
+java -jar target/kapua-simulator-kura-*-app.jar
 ```