Services V1

While the connectware allows to individually perform all settings (like managing grantees, setting permissions, starting containerized applications, etc.) the idea of Services is to bundle all this activities into a single point of configuration and execution.

Hence, a Service - once enabled - may automatically add several grantees, set their permissions and start containerized applications performing some kind of data manipulation tasks for example. When disabled, all grantees, permissions, and containerized applications created before will be removed.

Like Devices (user/device-commissioning) or Containers, Services are installed using a commissioning file. Within this text-base file, all grantees, permissions and containerized applications a Service should use are listed. Additionally, it is possible to register notifications (via web-hooks) for any Service event (like on-started, on-stopped, etc.).

Service can start containers, which are downloaded either from the public docker registry (Docker Hub) or the private cybus registry (registry.cybus.io). Cybus exposes some, but not all, docker options to be used by service containers. All containers belonging to one service are connected to a dedicated service network. Containers cannot publish ports to the host but can communicate with each other by using their name as a hostname reference. In order to provide network ports to the outside (e.g. Web Dashboards), services must implement the frontend directive. Frontends will be subject to proxying and are available to the HTTPS interface of the Cybus Connectware.

Commissioning file structure

The commissioning file uses the .yaml format.

Below a fully valid, but simple commissioning file is shown as an example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
#------------------------------------------------------------------------------#
# CYBUS SERVICE COMMISSIONING                                                  #
#------------------------------------------------------------------------------#
general:
  title:            Sample Service
  identifier:       sample-service
  version:          1.0.0
  description:      >
    Sample gateway
  icon:             https://de.wikipedia.org/wiki/Emoticon#/media/File:Binette-typo.png
  provider:         cybus
  homepage:         https://cybus.io
  terms:            Prototype
#------------------------------------------------------------------------------#
# LIST OF WEBHOOKS THE SERVICE WILL CALL UPON LIFECYCLE EVENTS                 #
#------------------------------------------------------------------------------#
events:
- on: installed
  post: http://...
- on: enabled
  post: http://...
- on: error
  post: http://...
- on: disabled
  post: http://...
- on: deleted
  post: http://...
#------------------------------------------------------------------------------#
# LIST OF GRANTEES THE SERVICE WILL ADD                                        #
#------------------------------------------------------------------------------#
grantees:
- identifier:       cybus.sample-service
  credentials:      token
  token:            $password
  purpose:          sample gateway
#------------------------------------------------------------------------------#
# THE SERVICE CAN DEFINE GENERAL POLICIES APART FROM DEVICES                   #
#------------------------------------------------------------------------------#
policies:
- grantee:          cybus.sample-service
  purpose:          forwards data
  policy:           ReadData
  constraints:
    topic:          io/cybus/device/goodread
#------------------------------------------------------------------------------#
# CONTAINERS THE SERVICE WILL OPERATE                                          #
#------------------------------------------------------------------------------#
containers:
- image:            registry.cybus.io/sample-provider/sample-service
  name:             sample-service
  env:
  - MQTT_HOST=cybus.factory.io
  - MQTT_PORT=8883
  - MQTT_USER=sample-service
  - MQTT_PASS=<tobedefined>
  restartPolicy:
    condition: on-failure
    maxAttempts: 10
#------------------------------------------------------------------------------#
# FOR PROVIDING WEB DASHBOARDS, THE SERVICE DEFINES FRONTENDS                  #
# WHICH ARE PROXIED TO THE SPECIFIED CONTAINERS                                #
# THE FOLLOWING DIRECTIVE CREATES A PROXY ON URL:                              #
# https://<platform>/services/cybus/sample-service/dashboard                   #
#                             ^provider  ^identifer     ^slug                  #
#------------------------------------------------------------------------------#
frontends:
- type: http
  slug: frontend
  name: Dashboard
  description: A cool dashboard
  target:
    path: ''
    container: sample-service
    port: 80
  buttons:
  - name: Dashboard
    href: /services/cybus/sample-service/frontend/deep-link

From the file you quickly see some important syntax rules:

  • Comments always start with #

  • Keys are separated from values using a :

  • Indentation is used to express nesting

  • A - sign indicates a list of instructions

Parameters

general

Section containing general information about the service in the following parameters.

title

Required. Title of the service

identifier

Required. Unique name of the service in the Connectware

version

Required. Version number

description

Required. Short description of the service

icon

Picture displayed in the Services section of the Connectware. Can be jpeg, png, apng, gif(animated), svg or bmp.

provider

Provider of the service

homepage

Homepage of the provider

terms

Terms describing the service

events

Section allowing to specify notification events by registering web-hooks. Must be a list of items containing:

on

Required. The name of the event. Can be either installed, enabled, disabled or deleted.

post

URL of the target web-hook address.

grantees

This section contains a list of grantees which should be created on activation of the service. Every grantee requires the following parameters.

identifier

Required. Name of the grantee

credentials

Required. Authentication method. Currently only authentication via token is implemented.

token

Required. Password of this grantee. For service internal users, use $password here. This keyword will be replaced by a randomly generated secret on every container start.

purpose

Required. Describing what this grantee is used for

policies

This section contains a list of policies which should be defined on activation of the service. Every policy is added with the following parameters.

grantee

Required. Grantee the policy should be valid for

purpose

Required. Describing what this policy is used for

policy

Required. Access type this policy grants. For MQTT access this can be ReadData or WriteData. For API access this can be ManageFlows, ReadAcl, WriteAcl, ReadDeviceMapping, WriteDeviceMapping, ReadLogs, ListServices, InstallServices, DeleteServices, ToggleServices, ListContainers, ManageContainers.

constraints

Only required if policy is ReadData or WriteData. Contains topic which is the path of an MQTT topic the policy should be valid for.

containers

This section contains a list of containers the Service should acquire and operate on.

image

Required. Location of the required container image. Can either be a public docker hub repository or an image located at the Cybus registry.

name

Required. Name the container should carry inside the Connectware. This name can be used as a hostname when multiple service containers need to reference each other. Important: this name must be less than 63 characters long, be lower case, contain only alphanumeric characters and dashes.

env

List of environment variables defining undetermined values of the executed application.

restartPolicy

The behavior to apply when the container exits. The default is to restart ‘unless-stopped’.

condition

“no” to never restart “always” to always restart. “unless-stopped” to restart always except when user has manually stopped the container “on-failure” to restart only when the container exit code is non-zero.

maxAttempts

Controls the number of times to retry before giving up. Only needed with ‘on-failure’ and it’s ignored on every other condition.

frontends

This section defines frontends for which proxy rules will be created that point to specific ports in Service Containers. This allows Service Containers to provide web dashboards which are served through the HTTPS interface of the Cybus Connectware.

The proxy server will automatically create a rule based on the following scheme:

https://<platform>/services/<provider>/<service-identifier>/<frontend-slug>

For each installed service, a private, closed virtual network is created which all Service Containers are assigned to.

type

Currently, only http is supported

slug

Required. The last component in the path of the proxy rule.

name

Descriptive name for the frontend, will be used in the Admin Web-App for displaying.

description

An explanatory text about the frontend.

target > container

The name of the container the proxy should point to. This must be the same as the name in the containers section.

target > port

The port of the container the proxy should point to. This must be a Docker exposed port.

target > path

Optional. If specified, the proxy will rewrite the path. Use this if the base path of the target http server cannot be modified.

buttons

A list of buttons that will be displayed in the service manager, e.g. to link to a specific website

buttons > name

Name of the button

buttons > href

Href of the button link

Installing a commissioning file

Commissioning files are installed using the web-based interface of the Connectware. Once you have opened the entry screen of the Connectware interface:

  1. If the navigation panel is not displayed on the left side click the menu icon in the upper left corner.

  2. On the navigation panel click on Services.

    ../_images/services_menu.png
  3. Press the + Button in the bottom right corner to add a service.

    ../_images/create.png
  4. In the popped up dialog click Choose File and select the commissioning file in the file browser, then click Install.

    ../_images/file.png
  5. Now, you should see an installed but still disabled Service, to enable click the button on the Service card.

    ../_images/enable.png
  6. Depending on the content of your service you will be asked to authorize the changes the Service will apply to your Connectware. If you are fine with the settings press Allow.

    ../_images/authorization.png
  7. If everything went well you should see an enabled Service.

    ../_images/enabled.png

Single Sign on Experience

HTTP Routes provided by services are proxied through the Cybus Ingress Router, which takes care of TLS Termination, Load Balancing and also Authentication/ Authorization. This provides a single-sign on user experience.

HTTP calls that should be forwarded must be equipped with one of the following credentials:

  • valid client certificate

  • HTTP Header X-Cybus-Authorization: Bearer <token> or X-Cybus-Authorization: Basic <token>

  • Cookie named X-Auth-Token containing a JSON Web Token

Important: if one of the provided credentials is invalid, the request is rejected. The credentials are extracted from the request and not forwarded to the service. A service may incorporate own user management by using other HTTP headers, e.g. with regular Authorization: Bearer or cookies that are named differently.

API Definition

POST /api/services

Uploads a Service Commissioning File

Uploads a Service Commissioning JSON. The default State is ‘disabled’.

Status Codes
GET /api/services

List all Services with detailed View

List all Services with their current configuration, status, grantees and policies.

Status Codes
POST /api/services/validate

Validate a Service Commissioning File

Status Codes
GET /api/services/status

List all Services and their current Status

Status Codes
GET /api/services/{id}

Find Service by ID

Returns a Service with its current configuration, status, grantees and policies.

Parameters
  • id (string) – Service ID

Status Codes
PUT /api/services/{id}

Updates Service by ID

Updates a Service with a new configuration

Parameters
  • id (string) – Service ID

Status Codes
DELETE /api/services/{id}

Delete Service by ID

Deletes a Service

Parameters
  • id (string) – Service ID

Status Codes
GET /api/services/{id}/status

Current Service Status

Overall Operational Status of a Service.

Parameters
  • id (string) – Service ID

Status Codes
POST /api/services/{id}/operation

Perform an Operation on a Service

Allows you to enable or disable a Service. This is an async operation! You should check the status of the Service or use web-hooks to verify completion. If the Service is already enabled/disabled nothing happens.

Parameters
  • id (string) – Service ID

Status Codes