All Kaa services, including EPMX, are distributed as Docker images. You can run these images using software containerization and orchestration tools, such as Docker, Docker Swarm, Docker Compose, Kubernetes, etc. Kubernetes is the recommended system for managing Kaa-based clusters.

Runtime dependencies

EPMX has the following runtime dependencies:

  • NATS for inter-service communication.

Regardless of the deployment method, always make sure that you have dependency services up and running prior to starting up EPMX.

The below instructions where EPMX sources its configuration data from a local file.

Environment variables

The table below summarizes the variables supported by the EPMX Docker image and provides default values along with descriptions.

Variable name Default value Description
INSTANCE_NAME epmx Service instance name.
APP_CONFIG_PATH /srv/epmx/service-config.yml Path to the service configuration YAML file inside container. In case of running in Kubernetes, consider using K8s Volumes for externalization.
JMX_ENABLE false Enables JMX monitoring.
JMX_PORT 10500 JMX service port.
JMX_MONITOR_USER_PASSWORD   JMX monitor user password. Required when JMX_ENABLE=true.
JAVA_OPTIONS -Xmx700m Additional parameters for Java process launch.
NATS_USERNAME   Username for connecting to NATS message broker.
NATS_PASSWORD   Password for connecting to NATS message broker.
KAA_LICENSE_CERT_PATH /run/license/license.p12 Path to the Kaa platform license certificate file in PKCS #12 format.
KAA_LICENSE_CERT_PASSWORD   License certificate password. Required.


To run EPMX on Kubernetes:

  1. Install Kubernetes.
  2. Set up NATS as a Kubernetes service or a standalone server.
  3. Prepare Kubernetes deployment descriptor.
  4. (Optional) Configure volumes and secrets.
  5. Prepare a config map, or a separate configuration file and save it into a file available to pods under APP_CONFIG_PATH.
  6. Start up the pod:
    kubectl create -f <deployment descriptor filename>
  7. Check that pods are running:
    kubectl get pods

Deployment descriptor

Provided below is a sample deployment descriptor file that pulls the EPMX version 1.0.0 Docker image from the official KaaIoT repository and runs one service replica (pod) with 1 GB RAM limit. With this deployment descriptor, the configuration file is expected to be located at ~/epmx-config/service-config.yml of the host machine. See spec.template.spec.volumes.hostPath below and the default APP_CONFIG_PATH above.

apiVersion: extensions/v1beta1
kind: Deployment
  name: epmx
  replicas: 1
        app: epmx
        tier: backend
      - name: epmx
        terminationMessagePolicy: FallbackToLogsOnError
        imagePullPolicy: Always
            path: /health
            port: management
          initialDelaySeconds: 150
          periodSeconds: 5
            path: /health
            port: management
          initialDelaySeconds: 1
          periodSeconds: 1
            memory: 350Mi
            memory: 1Gi
              name: license.cert.pass
              key: password
        - name: management
          containerPort: 8080
        - name: jmx
          containerPort: 10500
        - name: license-volume
          mountPath: /run/license
        - name: epmx-conf-volume
          mountPath: /srv/epmx
      - name: kaaid
        - name: epmx-conf-volume
          hostPath: ~/epmx-config
          defaultMode: 444
        - name: license-volume
            secretName: license.cert

Below are some notable parameters of the deployment descriptor:

  • spec.replicas defines the number of service instance replicas.
  • spec.template.spec.containers.image defines the Docker image to be used, while spec.template.spec.containers.imagePullPolicy defines the image update policy.
  • spec.template.spec.imagePullSecrets specifies the image pull secret for the official KaaIoT docker registry. To define this secret, use your KaaID credentials:
    $ export HISTCONTROL=ignorespace  # Prevent saving your credentials in the shell history
    $  KAAID_USER=<your KaaID username>; kubectl create secret docker-registry kaaid --docker-username=$KAAID_USER --docker-email=$KAAID_USER --docker-password=<your KaaID password>
  • specifies the volume to contain the license certificate file. We recommend that this volume is created from a Kubernetes secret.
  • defines the license certificate password environment variable, which is also recommended to be set from a Kubernetes secret.
  • defines the application label to map Kubernetes deployment to the service.
  • spec.template.spec.containers.resources defines resources available to each replica. See how Kubernetes manages compute resources for containers.
  • spec.template.spec.containers.env defines the environment variables that Kubernetes passes to the service replica.
  • spec.template.spec.containers.ports defines the exposed ports. See Connecting applications with services.

Volumes and secrets

The above deployment descriptor mounts a host machine directory for the service to load its configuration file from. However, such simple configuration may not be convenient in multi-node deployments and you might want to create other types of volumes. Besides, if you want to pass sensible pieces of information to the service using the environment variables, such as logins and passwords for dependency services, we recommend using Kubernetes Secrets. To learn more about these subjects, refer to Kubernetes documentation:


To run EPMX in Docker:

  1. Install Docker.
  2. Set up NATS as a Docker container or a standalone server.
  3. Prepare a configuration file and save it into a file available to the container under APP_CONFIG_PATH.
  4. Run Docker container. For example, use the following command to run the EPMX version 1.0.0 image:
    $ docker run \
        -v <host_path_to_config_directory>:/srv/epmx \