Upgrading from 0.x to 1.0

This section descibes the upgrading of a Cybus Connectware installation from a previous 0.x version to 1.0.0. For an overview of concept changes, see General changes from 0.x to 1.0

Upgrading the Connectware installation

To upgrade the installed version from 0.x to 1.0, just download and run the connectware-online-installer.sh script as usual. If a 0.x installation is detected, the Connectware containers of the previous installation will be stopped and the container instances removed, but the container images will remain installed.

It is not possible to run both versions in parallel on the same computer, just as it is not possible to run more than one instance of the Connectware in parallel on one computer anyway. It is possible to have both versions installed and start either of both versions alternating, as long as one version is stopped completely (using docker-compose down) before starting the other version. Make sure to reload your browser window (e.g. by Ctrl+F5) when switching between both versions, as sometimes the browser keeps the wrong version of the admin UI in its cache.

Currently, no automatic migration of user data, device configuration, or service configuration is implemented. Please contact Cybus support if you need help in migrating your data.

Migrating commissioning files

In the following, the necessary migration work for service and device commissioning files will be described.

In 1.0, the resources of one commissioning file can reference other resources not only from the same commissioning file and service, but also across different services using the service id. Hence, the complete system context can be described by one or or by multiple commissioning files, whatever fits best for the application. In particular, it is up to you whether the old device and service commissioning files are migrated into one or into two files. Both is possible.

Service commissioning files

To migrate the old service commissioning files into new service commissioning files with resources, the following steps must be performed with the respective sections in the old file:

  • Old general properties must be rewritten in the new top-level properties or metadata properties, see Structure of Commissioning Files.

  • Old containers sections must be rewritten into Cybus::Container resources

  • Old frontends sections must be rewritten into Cybus::IngressRoute resources

  • For more information, feel free to contact Cybus Support.

Device commissioning files

To migrate the old device commissioning files into new service commissioning files with resources, the following steps must be performed with the respective sections in the old file:

  • Old source sections must be rewritten into Cybus::Connection resources

  • Old target sections are not needed as separate entries anymore. For the definition of the target topic prefix, either the default from the Cybus::MqttRoot global parameter is used, or the endpoint’s topic property needs to be defined.

  • Old mappings sections must be rewritten into Cybus::Mapping resources

  • Default settings that were used in multiple mappings (now: multiple endpoints) now need to be defined using definitions and used by !merge in the properties.

  • For more information, feel free to contact Cybus Support.

Specific Topics

Template Syntax

Old

In 0.x Connectware, the installation specific parameters were made configurable using the {{...}} template syntax. When installing commissioning files with these templates, the user was being asked to give values for these templates.

New

In 1.0 Connectware, the installation specific parameters are noted as parameters. They are defined in the parameters section of the commissioning file, then used by the !sub function for value substitution. Example: !sub 'My Workbench ${ID}'

MQTT Topic Space

Old

There were no special constraints on the MQTT topics to which device could write its messages, in particular no constraints on the topicPrefix of the target interface.

New

In 1.0 Connectware, every service hat its own namespace in MQTT as given by its ServiceID. Other services cannot read data from each other’s namespace directly. A service has its own scope. If this is intended to be changed, the global parameter CYBUS_MQTT_ROOT can be redefined to some global pattern. And also in a Cybus::Mapping resource, you are allowed to write to anything, but not in the endpoint.

Frontend Routes

Old

For making specific ports of service containers accessible to the outside, in 0.x Connectware one would specify these proxy rules in the frontends section of the service commissioning file. The URLs were created in a scheme that contains the string services, then the provider name and service-identifier, followed by the slug.

New

In 1.0 Connectware, making ports accessible to the outside is achieved by specifying a Cybus::IngressRoute resource. The URL still contains the string services, but then the serviceId followed by the specified slug. Watch out: No trailing slash is appended automatically now. This has to be specified explicitly if wanted.

Docker options

Old

If the docker containers in a service need to be started with special options, such as device capabilities or xxxx mode, one would use the section alice with some extra parameters.

New

In 1.0 Connectware, all extra docker options are available as parameters below the Cybus::Container resource, in particular the devices, ports, and capAdd parameters.

Environment Variables

Old

For passing environment variables to containers, a property section env was added to the containers section in the commissioning file. The actual env variables were written in a syntax with equal sign, like so: MQTT_HOST=foo.bar.

New

Defining environment variables for a container is done by adding the environment parameter below the Cybus::Container resource. The actual variables are now written in a syntax of yaml object assignment, as follows: MQTT_HOST: foo.bar.

It is also common to use a parameter in this place by reference !ref or substitution !sub, like so: MQTT_HOST: $ref Cybus::MqttHost or MQTT_HOST: '!sub ${myParameter}'

Examples

More examples are also shown here.

Grafana dashboard Example

This example shows the comparison between the old file to the new file. More examples are also shown here.

This service runs a Grafana visualization for data, an InfluxDB as data source of the container, and a connector container for data input. The comparison shows how the syntax for specifying containers needs to be changed when upgrading.

Old file in 0.x

#------------------------------------------------------------------------------#
# CYBUS SERVICE COMMISSIONING
#------------------------------------------------------------------------------#
general:
  title:            Generic Dashboard
  identifier:       generic-dashboard
  version:          1.2.1
  description:      >
    The generic Grafana dashboard visualizes all Connectware data with just a few
    clicks and offers a wide range of options for creation of graphs and analyzes.
  provider:         cybus
  homepage:         https://cybus.io
  terms:            Prototype
#------------------------------------------------------------------------------#
# GRANTEES
#------------------------------------------------------------------------------#
grantees:
- identifier:       influxdb-connector
  credentials:      token
  token:            $password
  purpose:          Forwards data to InfluxDB
  type:             container
#------------------------------------------------------------------------------#
# PERMISSIONS
#------------------------------------------------------------------------------#
policies:
- grantee:          influxdb-connector
  purpose:          Reads data from any MQTT topic
  policy:           ReadData
  constraints:
    topic:          '#'
#------------------------------------------------------------------------------#
# CONTAINERS
#------------------------------------------------------------------------------#
containers:
- image:            registry.cybus.io/cybus-services/generic-grafana:1.2.1
  name:             generic-grafana
  env:
  - GF_SERVER_ROOT_URL=/services/cybus/generic-dashboard/web
  - GF_AUTH_ANONYMOUS_ENABLED=true
  - INFLUX_HOST=generic-influxdb
  - INFLUX_PORT=8086
  - INFLUX_DB=generic
  alice:
    HostConfig:
      Binds:
        - "grafana:/var/lib/grafana"
- image:            registry.cybus.io/cybus-services/influxdb-push:0.0.3
  name:             influxdb-push
  env:
  - MQTT_HOST=connectware
  - MQTT_USER=influxdb-connector
  - MQTT_PORT=1883
  - MQTT_PASS=$password
  - MQTT_ROOT_TOPIC=#
  - INFLUX_HOST=generic-influxdb
  - INFLUX_PORT=8086
  - INFLUX_DB=generic
  - HTTP_ROOT=/services/cybus/generic-dashboard/red
- image:            registry.cybus.io/cybus-services/influxdb:1.7.8-alpine
  name:             generic-influxdb
  env:
    - INFLUXDB_DB=generic
  alice:
    HostConfig:
      Binds:
        - "genericdb:/var/lib/influxdb"
      PortBindings:
        "8086/tcp":
          - HostPort: '8086'
#------------------------------------------------------------------------------#
# FRONTENDS
#------------------------------------------------------------------------------#
frontends:
- type: http
  name: Grafana
  slug: web
  target:
    path: '/'
    container: generic-grafana
    port: 3000
  buttons:
  - name: Open Grafana
    href: "/services/cybus/generic-dashboard/web"

New file in 1.0

See also the full example here: “Machine Utilization Example” - Dashboards with role based access permission

Download: services/examples/modbus2/utilization-grafana.yml

Note

The example below uses an additional Docker image provided by Cybus that requires a suitable license. You can check the current capabilities and permissions of your Connectware license in the Cybus Portal (https://portal.cybus.io). If your license is not eligible to use the example Docker image, please contact Cybus Sales (sales@cybus.io).

 1description: >
 2  The generic Grafana Service
 3
 4metadata:
 5  name: Generic Grafana Dashboard
 6  icon: https://www.cybus.io/wp-content/uploads/2017/10/for-whom3.svg
 7  provider: cybus
 8  homepage: https://www.cybus.io
 9  version: 1.2.1
10
11definitions:
12  SID: !ref Cybus::ServiceId
13  CYBUS_MQTT_ROOT: 'services'
14
15resources:
16
17  #----------------------------------------------------------------------------
18  # VOLUMES
19  #----------------------------------------------------------------------------
20
21  grafanaVolume:
22    type: Cybus::Volume
23
24  influxdbVolume:
25    type: Cybus::Volume
26
27  #----------------------------------------------------------------------------
28  # FRONTENDS
29  #----------------------------------------------------------------------------
30
31  # Grafana
32  grafanaURL:
33    type: Cybus::IngressRoute
34    properties:
35      container: !ref genericGrafana
36      type: http
37      slug: grafana
38      target:
39        path: '/'
40        port: 3000
41
42  dashboard:
43    type: Cybus::Link
44    properties:
45      name: Dashboard
46      ingressRoute: !ref grafanaURL
47      href: ''
48
49  #----------------------------------------------------------------------------
50  # Cybus Timeseris & Dashboard service containers
51  #----------------------------------------------------------------------------
52
53  influxdbPush:
54      type: Cybus::Container
55      properties:
56        image: registry.cybus.io/cybus-services/influxdb-push:0.0.3
57        environment:
58          MQTT_HOST: !ref Cybus::MqttHost
59          MQTT_USER: !ref Cybus::MqttUser
60          MQTT_PORT: !ref Cybus::MqttPort
61          MQTT_PASS: !ref Cybus::MqttPassword
62          MQTT_ROOT_TOPIC: !sub "services/#"
63          INFLUX_HOST: !ref influxdb
64          INFLUX_PORT: 8086
65          INFLUX_DB: generic
66          HTTP_ROOT: /
67
68  influxdb:
69    type: Cybus::Container
70    properties:
71      image: registry.cybus.io/cybus-services/influxdb:1.7.7-alpine
72      ports:
73        - 8086:8086/tcp
74      volumes:
75        - !sub "${influxdbVolume}:/var/lib/influxdb"
76      environment:
77        INFLUXDB_DB: generic
78
79  genericGrafana:
80    type: Cybus::Container
81    properties:
82      image: registry.cybus.io/cybus-services/generic-grafana:1.2.1
83      volumes:
84        - !sub "${grafanaVolume}:/var/lib/grafana"
85      environment:
86        GF_SERVER_ROOT_URL: !sub "/services/${SID}/grafana"
87        GF_AUTH_ANONYMOUS_ENABLED: true
88        INFLUX_DB: generic
89        INFLUX_HOST: !ref influxdb
90        INFLUX_PORT: 8086