Kura emulate (README.md)
Using with OpenShift
It is possible to run the Kura emulator instance in an OpenShift instance.
Assuming you already have set up OpenShift it is possible to deploy the Kura Emulator
inside of OpenShift using either method described in the following sections.
The template will create a new build and deployment configuration. This will trigger
OpenShift to download the base docker images, pull the source code of Kura from Git and
completely rebuild it. There is also a Kura instance configured to instantiate that image once
as soon as the build is complete. Every re-build will automatically trigger a re-deployment.
Installing
All following steps will assume that you already have create a new project in OpenShift named kura
for this. You will also need a working internet connection on the machine running OpenShift
and on the machine you will be using.
Note: If you are using the templates form a different branch than the master branch,
then you need to specify the branch name as the template parameter GIT_BRANCH.
Web console
- Click on “Add to project”
- Switch to “Import YAML / JSON”
- Either
- Copy and paste the content of either of the template files into the text area
- Use the “Browse…” button and load one of the template files
- Press “Create”
- In the following confirmation dialog:
- Keep the defaults
- Press “Continue”
Command line
Issue the following commands from your command line of choice. Please not that need to have the
OpenShift CLI installed installed.
You also need to be logged in to your OpenShift cluster with oc login.
oc new-app --file=kura-.yml
If you are using a template from a branch other than master, you must add the following
template parameter, e.g.:
oc new-app --file=kura-.yml -p GIT_BRANCH=develop
Persistence modes
There are three templates for deploying Kura. Emphermal, data persistence, instance persistence.
Ephermal
With ephermal you will loose all changes once the pod running Kura is destroyed. Each new pod will start
with a fresh installation of Kura. This may be useful for quickly testing Kura.
Data persistence
Data persistence will keep all configuration changes made inside of Kura, it will also keep additional
installed packages (DPs). But the Kura installation itself is considered “read-only” and cannot be
modified, e.g. by using a Kura updater. Data and installed packaged will be stored a persistent volume.
On the other hand allows to drop in a new container image, which will then bring a new Kura version, but
keep the configuration settings and DPs as they were.
Instance persistence
Using the instance persistent template, a new volume will be allocated and the Kura instance will be copied
over to this volume on the first start. Subsequent starts will keep the Kura instance and all its data directories.
The main difference between data and instance persistence is, that a new build with the persistent template will
restart the Kura pod, including a fresh container image (updated Java, OS, …) but it will keep the
same Kura version. In order to update Kura, you have to use the Kura update mechanisms. On the other hand,
updating Kura using its update mechanism will modify the Kura installation as expected.
Stateful sets
The Kura instance is run as a “stateful set”. This allows to keep a stable network name, and auto-allocate volumes as needed.
Note: Although image triggers have been added to the stateful set, sometimes those triggers don’t properly fire.
This results in a new builds not being activated.
Configuration through ConfigMaps
The Kura instance will use the config map kura-instance-config to store the following Kura specific files:
log4j.xml
kura_custom.properties
Loading bundles with ConfigMaps
The Kura docker container allows to map the directory /load and drop in OSGi bundles, which
will automatically be picked up by Apache FileInstall.
The OpenShift deployment will leverage that and map the configmap kura-instance-load-config
to /load (which is also monitored by the Kura instance). This allows one to update the configmap with
a new JAR and the Kura instance will pick up this OSGi bundle and correctly register it.
Note: For this to work ConfigMaps with binary support are required. This requires OpenShift 3.10, Kubernetes 1.10.
Eclipse Kura™ emulator Docker image
This is a docker image running Eclipse Kura™.
Use the following command to run it:
docker run -d -p 8080:8080 -t eclipse/kura
Once the image is started you can navigate your browser to http://localhost:8080 and log in using the credentials admin : admin.
Making use of Apache Felix File Install
This image includes Apache Felix FileInstall, which monitors a directory and loads all OSGi bundles it detects during runtime. Adding a new bundle is as easy as dropping an OSGi JAR file into a directory. Uninstalling is done by deleting the file and updates are simply done by overwriting the bundle with a newer version.
Note: The location of the directory changed from /opt/eclipse/kura/load to /load. The old path is
deprecated. It might still work for a while, but it might break at any time.
File Install loads bundles from /load which is also defined as a docker volume,
so that you can link this up with your container host:
docker run -ti -p 8080:8080 -v /home/user/path/to/bundles:/load:z eclipse/kura
Now you can access /home/user/path/to/bundles on your host machine and bundles will be loaded
by Kura inside the docker container.
Note: It may be that a bundle, which is first installed, needs to be manually started using the Kura Web UI.
Running with JMX enabled
Running with JMX or debugging enabled can sometimes be quite helpful. However it is disabled by default.
On Linux
If you want to run the image with JMX enabled use the following command on Linux:
docker run -ti -eJAVA_OPTS="-Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.port=9010 -Dcom.sun.management.jmxremote.local.only=false -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.ssl=false -Xdebug -Xrunjdwp:transport=dt_socket,address=9011,server=y,suspend=n" -p 8080:8080 --expose 9010 --expose 9011 -p 9010:9010 -p 9011:9011 eclipse/kura
On Windows
If you want to run the image with JMX enabled use the following command on Windows:
docker run -ti -eJAVA_OPTS="-Dcom.sun.management.jmxremote -Djava.rmi.server.hostname= -Dcom.sun.management.jmxremote.port=9010 -Dcom.sun.management.jmxremote.rmi.port=9010 -Dcom.sun.management.jmxremote.local.only=false -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.ssl=false -Xdebug -Xrunjdwp:transport=dt_socket,address=9011,server=y,suspend=n" -p 8080:8080 --expose 9010 --expose 9011 -p 9010:9010 -p 9011:9011 eclipse/kura
Where is the Docker address, you can find it by using ipconfig and search for DockerNAT address, for instance:
Ethernet adapter vEthernet (DockerNAT):
Connection-specific DNS Suffix . :
IPv4 Address. . . . . . . . . . . : 10.0.75.1
Subnet Mask . . . . . . . . . . . : 255.255.255.0
Default Gateway . . . . . . . . . :
The JMX port defined is 9010 and the Remote debug port is 9011. Both ports are not exposed by default and have to be exposed from the command line using --expose 9010 --expose 9011.
Re-Building
This docker container is being built by re-using the Intel UP² CentOS 7 image of Kura. It makes a few adjustments to the Kura sources and performs a full build from either a specified Git commit, or from the Git repository which has to be in the context root of the build.
If you want to re-build this image, check out this repository and simply run docker build -f kura/container/kura/Dockerfile . on the command line from the root of this repository.
You can re-build the image from a specific Git commit. For this you need to pass in the build argument KURA_COMMIT.
Running in OpenShift
There also is an OpenShift template, which can be used to deploy this image into OpenShift.
Building extended images
If you want to add additional content to the Kura installation inside the docker image,
it is possible to extend the installation.
Also see: extensions/artemis/README.md