Deployment
All Kaa services, including EPTS, 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
EPTS has the following runtime dependencies:
Regardless of the deployment method, always make sure that you have dependency services up and running prior to starting up EPTS.
The below instructions where EPTS sources its configuration data from a local file.
Environment variables
The table below summarizes the variables supported by the EPTS Docker image and provides default values along with descriptions.
Variable name | Default value | Description |
---|---|---|
APP_CONFIG_PATH |
/srv/epts/service-config.yml | Path to the service configuration YAML file inside container. In case of running in Kubernetes, consider using K8s Volumes for externalization. |
NATS_URLS |
“nats://nats:4222” | NATS connection URLs. May include connection credentials, e.g. “nats://derek:pass@localhost:4222”. |
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. | |
KAA_INFLUX_URL |
InfluxDB URL. | |
KAA_INFLUX_USER |
InfluxDB username. | |
KAA_INFLUX_PASSWORD |
InfluxDB password. | |
KAA_SECURITY_ISSUER |
URL of the AAA service. | |
KAA_SECURITY_CLIENTID |
Client ID for making requests to the AAA service. | |
KAA_SECURITY_CLIENTSECRET |
Client secret for making requests to the AAA service. |
Kubernetes
To run EPTS on Kubernetes:
- Install Kubernetes.
- Set up NATS as a Kubernetes service or a standalone server.
- Set up InfluxDB in Kubernetes or as a standalone server.
- Prepare Kubernetes deployment descriptor.
- (Optional) Configure volumes and secrets.
- Prepare Kubernetes service descriptor to be able to expose the deployment outside of the Kubernetes network.
- Prepare a [config map][service configuration], or a separate configuration file and save it into a file available to pods under
APP_CONFIG_PATH
. - Start up the pod:
kubectl create -f <deployment descriptor filename>
- Check that pods are running:
kubectl get pods
- Check that services are created:
kubectl get service
Deployment descriptor
Provided below is a sample deployment descriptor file that pulls the EPTS version 1.0.0 Docker image from the official KaaIoT repository and runs one service replica (pod) with 150 MB RAM limit.
With this deployment descriptor, the configuration file is expected to be located at ~/epts-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
metadata:
name: epts
spec:
replicas: 1
template:
metadata:
labels:
app: epts
tier: backend
spec:
containers:
- name: epts
image: hub.kaaiot.net/kaaiot/epts/epts:1.0.0
terminationMessagePolicy: FallbackToLogsOnError
imagePullPolicy: Always
livenessProbe:
httpGet:
path: /health
port: management
initialDelaySeconds: 150
periodSeconds: 5
readinessProbe:
httpGet:
path: /health
port: management
initialDelaySeconds: 1
periodSeconds: 1
resources:
requests:
memory: 20Mi
limits:
memory: 150Mi
env:
- name: KAA_LICENSE_CERT_PASSWORD
valueFrom:
secretKeyRef:
name: license.cert.pass
key: password
ports:
- name: rest-api
containerPort: 80
- name: management
containerPort: 8080
volumeMounts:
- name: license-volume
mountPath: /run/license
- name: epts-conf-volume
mountPath: /srv/epts
imagePullSecrets:
- name: kaaid
volumes:
- name: epts-conf-volume
hostPath: ~/epts-config
defaultMode: 444
- name: license-volume
secret:
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, whilespec.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-server=hub.kaaiot.net --docker-username=$KAAID_USER --docker-email=$KAAID_USER --docker-password=<your KaaID password>
spec.template.spec.volumes.name.license-volume
specifies the volume to contain the license certificate file. We recommend that this volume is created from a Kubernetes secret.spec.template.spec.containers.name.epts.env.name.KAA_LICENSE_CERT_PASSWORD
defines the license certificate password environment variable, which is also recommended to be set from a Kubernetes secret.spec.template.metadata.labels.app
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.
Service descriptor
To expose the deployment outside the Kubernetes network, create a service descriptor. Below is a sample service descriptor that exposes EPTS’s REST API interface to the Kubernetes host network interface at port 30740.
apiVersion: v1
kind: Service
metadata:
name: epts
labels:
app: epts
tier: backend
spec:
type: "LoadBalancer"
ports:
- name: rest-api
port: 80
targetPort: rest-api
nodePort: 30740
selector:
app: epts
tier: backend
The following parameters are worth noting:
spec.type
defines the service type.spec.ports.port
,spec.ports.targetPort
, andspec.ports.nodePort
parameters define the mapping between the Kubernetes service and deployment ports.spec.selector.app
maps the service to the deployment. It matchesspec.metadata.labels.app
in the deployment descriptor above.
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:
Docker
To run EPTS in Docker:
- Install Docker.
- Set up NATS as a Docker container or a standalone server.
- Set up InfluxDB as a Docker container or as a standalone server.
- Prepare a configuration file and save it into a file available to the container under
APP_CONFIG_PATH
. - Run Docker container.
For example, use the following command to run the EPTS version 1.0.0 image:
$ docker run \ -p 80:80 \ -v <host_path_to_config_directory>:/srv/epts \ hub.kaaiot.net/kaaiot/epts/epts:1.0.0