Deployment

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

SCR has the following runtime dependencies:

  • Git is used as a back-end that SCR loads service configuration files from.
  • 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 SCR.

Environment variables

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

Variable name Default value Description
INSTANCE_NAME scr Service instance name.
APP_CONFIG_PATH   Path to the service configuration YAML file inside container. In case of running in Kubernetes, consider using K8s Volumes for externalization. Optional.
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_URLS nats://nats:4222 Comma separated list of NATS URLs.
NATS_USERNAME   Username for connecting to NATS message broker.
NATS_PASSWORD   Password for connecting to NATS message broker.
GIT_URI   URI of the git repository that contains services’ configuration files. Required.
GIT_BRANCH master The git repository branch with configuration files.
GIT_USERNAME   Username to access git repository.
GIT_PASSWORD   Password to access git repository.
GIT_SEARCH_PATHS   Comma separated paths to search for configuration files.

Kubernetes

To run SCR on Kubernetes:

  1. Install Kubernetes.
  2. Set up NATS as a Kubernetes service or a standalone server.
  3. Prepare a git repository with service configuration files for SCR to serve.
  4. Prepare Kubernetes deployment descriptor.
  5. (Optional) Configure volumes and secrets.
  6. (Optional) Prepare a configuration file and save into a file available to pods under APP_CONFIG_PATH.
  7. Start up the pod:
    kubectl create -f <deployment descriptor filename>
    
  8. Check that pods are running:
    kubectl get pods
    
  9. Check that services are created:
    kubectl get service
    

Deployment descriptor

Provided below is a sample deployment descriptor file that pulls the SCR version 1.0.0 Docker image from the official KaaIoT repository and runs one service replica (pod) with 1 GB RAM limit. This deployment descriptor provides all the necessary SCR configuration options using the the environment variables.

apiVersion: extensions/v1beta1
kind: Deployment
metadata:
  name: scr
spec:
  replicas: 1
  template:
    metadata:
      labels:
        app: scr
        tier: backend
    spec:
      containers:
      - name: scr
        image: hub.kaaiot.io/kaaiot/scr/scr: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: 350Mi
          limits:
            memory: 1Gi
        env:
        - name: GIT_URI
          value: https://gitlab.kaaiot.io/samples/smartKettle/blueprint.git
        ports:
        - name: rest-api
          containerPort: 80
        - name: management
          containerPort: 8080
        - name: jmx
          containerPort: 10500
      imagePullSecrets:
      - name: kaaid

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-server=hub.kaaiot.io --docker-username=$KAAID_USER --docker-email=$KAAID_USER --docker-password=<your KaaID password>
    
  • 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.

    IMPORTANT Make sure that you substitute the GIT_URI value with a link to your repository.

  • 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 SCR’s REST API interface to the Kubernetes host network interface at port 30770.

apiVersion: v1
kind: Service
metadata:
  name: scr
  labels:
    app: scr
    tier: backend
spec:
  type: "LoadBalancer"
  ports:
  - name: rest-api
    port: 80
    targetPort: rest-api
    nodePort: 30770
  selector:
    app: scr
    tier: backend

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 uses environment variables to configure SCR. You might prefer to create a volume and load the SCR configuration file from it. 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 SCR in Docker:

  1. Install Docker.
  2. Set up NATS as a Docker container or a standalone server.
  3. Run Docker container. For example, use the following command to run the SCR version 1.0.0 image:
    $ docker run hub.kaaiot.io/kaaiot/scr/scr:1.0.0 \
        -p 80:80 \
        -v <host_path_to_config_directory>:/srv/scr \
        -e GIT_URI=https://gitlab.kaaiot.io/samples/smartKettle/blueprint.git
    

    IMPORTANT Make sure that you substitute the GIT_URI value with a link to your repository.