Deployment

• Runtime dependencies
• Environment variables
• Kubernetes
  • Deployment descriptor
  • Service descriptor
  • Volumes and secrets
• Docker

All Kaa services, including WD, 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

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

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

Environment variables

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

Kubernetes

To run WD on Kubernetes:

1. Install Kubernetes.
2. Prepare Kubernetes deployment descriptor.
3. (Optional) Configure volumes and secrets.
4. Prepare Kubernetes service descriptor to be able to expose the deployment outside of the Kubernetes network.
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
   

8. Check that services are created:

    kubectl get service
   

Deployment descriptor

Provided below is a sample deployment descriptor file that pulls the WD 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 ~/wd-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: wd
  namespace: default
spec:
  replicas: 1
  template:
    metadata:
      labels:
        app: wd
        tier: frontend
    spec:
      imagePullSecrets:
        - name: kaaid
      containers:
      - name: wd
        image: hub.kaaiot.net/kaaiot/wd/wd:1.0.0
        imagePullPolicy: Always
        livenessProbe:
          httpGet:
            path: /healz
            port: 30900
          initialDelaySeconds: 30
          periodSeconds: 5
        readinessProbe:
          httpGet:
            path: /healz
            port: 30900
          initialDelaySeconds: 30
          periodSeconds: 5
        resources:
          requests:
            memory: 350Mi
          limits:
            memory: 1Gi
        env:
        - name: KAA_LICENSE_CERT_PASSWORD
          valueFrom:
            secretKeyRef:
              name: license.cert.pass
              key: password
        ports:
        - name: wd-port
          containerPort: 30900
        volumeMounts:
        - name: license-volume
          mountPath: /run/license
      volumes:
      - 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.metadata.labels.app defines the application label to map Kubernetes deployment to the service.
• 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-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.wd.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.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 WD’s REST API interface to the Kubernetes host network interface at port 30900.

apiVersion: v1
kind: Service
metadata:
  name: wd
  labels:
    app: wd
    tier: frontend
spec:
  type: "LoadBalancer"
  ports:
  - port: 30900
    targetPort: 30900
    nodePort: 30900
    name: wd
  selector:
    app: wd
    tier: frontend

The following parameters are worth noting:

• spec.type defines the service type.
• spec.ports.port, spec.ports.targetPort, and spec.ports.nodePort parameters define the mapping between the Kubernetes service and deployment ports.
• spec.selector.app maps the service to the deployment. It matches spec.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:

• Volumes
• Secrets
• Config maps

Docker

To run WD in Docker:

1. Install Docker.
2. Prepare a configuration file and save it into a file available to the container under APP_CONFIG_PATH.
3. Run Docker container. For example, use the following command to run the WD version 1.0.0 image:

   $ docker run \
       -p 30900:30900 \
       -v <host_path_to_config_directory>:/srv/wd \
       hub.kaaiot.net/kaaiot/wd/wd:1.0.0