Development Guide

Warning

This documentation is work in progress, and subject to change!

In order to open a shell to a pod in the cluster, see make open-shell.

Running a service locally

During development, it is sometimes cumbersome to deploy a new build for every minor change, and running a service locally can speed up the development process. This can be achieved in three steps:

  1. Start the service locally on the host. You might need to expose the same environment variables as in k8s, and also copy files such as keys depending on the service you are working on.
  2. Make your service accessible to other services by running python3 util/proxy_service_to_localhost.py YOUR_SERVICE_NAME.
  3. Make other service accessible on the host by running kubefwd as described in Exposing OISP locally without ingresses.
  4. Start the desired service in your local environment.

Example: Running dashboard(frontend) service locally

  1. Prepare a fresh terminal for the local service and copy the keys:
nvm use 8
source <(./platform-launcher/util/get_oisp_container_config.sh oisp dashboard)
kubectl -n oisp cp dashboard-855957b8f8-8hr4h:/app/keys ./platform-launcher/oisp-frontend/public-interface

Warning

The used NodeJS version, paths, kubernetes namespace and the pod name are just an example and should be changed accordingly. For information on the helper script ‘get_oisp_container_config.sh’, use it with ‘-h’ argument.

  1. In a new terminal, make your service accessible to other services and make other services accessible to dashboard.
python3 ./platform-launcher/util/proxy_service_to_localhost.py dashboard
sudo kubefwd services --kubeconfig=/home/username/.kube/config -n oisp
  1. Start your service locally in the fresh prepared terminal.
node app.js

Warning

If you want to run multiple services locally, the steps are similar. Make sure but then that the environment variables are right. For example, if you are running frontend and websocket server together, then you should change the websocket server host in the frontend to localhost, as it will not be accessible via the host ‘websocket-server’ anymore.

Running tests

Final tests should be run in the cluster. See make import-images to use your new image without having to push it to a docker repository. Afterwards, you can run make test from the kubernetes directory. If you want to use the latest images for the other components, you will need to edit kubernetes/templates/[YOUR_SERVICE].yaml to use the image tag of your choice instead of the value provided by {{ .Values.tag }}.

Hint

Be careful about the Kubernetes pull policy. If you are working with the latest tag, Kubernetes will try to pull the image even if it is already imported into the cluster. See this for details.

Hint

Tests won’t run if the DOCKERUSER and DOCKERPASS variables are not exposed. If you do not need to pull any images, set an environment variable to bypass the check by running export NODOCKERLOGIN=true. This is also a good way to make sure you are not accidentally working with the images from the repository.

Testing the ingresses

If you want to test the ingresses itself, you should add the hostname of the ingress to your /etc/hosts file:

~>>> kubectl -n oisp get ingresses
NAME                 HOSTS                                                                     ADDRESS      PORTS     AGE
dashboard-web        latest.streammyiot.com,latest.streammyiot.com,ws.latest.streammyiot.com                80, 443   75m
dashboard-web-http   latest.streammyiot.com,latest.streammyiot.com,ws.latest.streammyiot.com   172.18.0.2   80        75m
mqtt                 mqtt.latest.streammyiot.com                                               172.18.0.2   80        75m

Then you will add an entry to your /etc/hosts file like this:

172.18.0.2          latest.streammyiot.com ws.latest.streammyiot.com

Warning

If you are running a service locally that uses ingress, then remember ingress will not route a request to your local working service.