Edge App Manager User Guide

(1)

Edge App Manager

User Guide

(2)

Edition notice

Technical specifications and availability subject to change without notice.

This document may not be reproduced, disseminated to third parties or processed and its contents may not be used or disclosed without express permission. Non-compliance shall result in compensation for damages. All rights, including those resulting from a successful patent application and registration of a utility model or design patent, are reserved.

Edition: 2020-11-20

Document ID: A6V12059211

(3)

Cybersecurity disclaimer

Siemens provides a portfolio of products, solutions, systems and services that includes security functions that support the secure operation of plants, systems, machines and networks. In the field of Building Technologies, this includes building automation and control, fire safety, security management as well as physical security systems.

In order to protect plants, systems, machines and networks against cyber threats, it is necessary to implement – and continuously maintain – a holistic, state-of-the-art security concept. Siemens’ portfolio only forms one element of such a concept. You are responsible for preventing unauthorized access to your plants, systems, machines and networks which should only be connected to an enterprise network or the internet if and to the extent such a connection is necessary and only when appropriate security measures (e.g. firewalls and/or network segmentation) are in place. Additionally, Siemens’ guidance on appropriate security measures should be taken into account. For additional information, please contact your Siemens sales representative or visit https://www.siemens.com/global/en/home/company/topic-areas/future-of-manufacturing/industrial-security.html.

Siemens’ portfolio undergoes continuous development to make it more secure. Siemens strongly recommends that updates are applied as soon as they are available and that the latest versions are used. Use of versions that are no longer supported, and failure to apply the latest updates may increase your exposure to cyber threats. Siemens strongly recommends to comply with security advisories on the latest security threats, patches and other related measures, published, among others, under https://www.siemens.com/cert/en/cert-security-advisories.htm.

(4)

1 1 Edge App Manager User Guide

1.1 Overview

Edge App Manager is a service that allows you to develop, publish, and manage Edge apps. The Edge App Manager creates a configuration of an existing

container. Within Asset Manager, installing an app will assign this configuration to a device.

In particular this service offers:

● Creating an Edge app: Create a new Edge app, add an application version, and configure an Edge app.

● Creating a distribution: Create a new distribution, add a version and configure a distribution.

● Manage Edge app life-cycle: Manage Edge apps and distributions by going through all life-cycle states including development, test, release and discontinued.

The service is applicable for all cloud offerings.

After log-in you may be able to directly access and impact connected sites and assets as specified in the related documentation. You and your company are solely responsible for any impact on the connected sites and assets which result from your use of this Service.

1.2 Creating Edge app

An Edge app is a single Edge device service or a collection of multiple Edge device services which together perform a business use-case when installed and running on an Edge device. An app consists of a list of defined Edge services.

(6)

Edge App Manager User Guide Creating Edge app

1 1.2.1 Adding app

 You have already set up an account for Edge App Manager.

1. Go to https://edge.bpcloudapps.siemens.com/ to open Edge App Manager. 2. Log in and verify the correct company is selected in your profile.

3. Click Create app and enter a Name for the app.

It is recommended to enter a Description.

 A new Edge app is created.

1.2.2 Adding application version

An application version is an entity of an Edge application which serves the business use-case of the app under a specific set of conditions.

(7)

1

1. Open the recently created app and click Add version.

2. Fill in the fields on the ensuing form appropriately.

It is important to select the correct compatible gateway operating system version, for example, 4.10.0.

3. Click Create.

You can either create a new version or a clone from an existing app version.

 The app version is created and the app state will switch to Development. The app is ready to integrate a new service.

1.2.3 Configuring app

 An Edge app is created.

 An application version is added.

1. Open the app and the app version you intend to configure. 2. Go to Configuration tab.

(8)

1

Entries in Settings section are optional. The red asterisk next to Services indicates that entries in Services section are mandatory.

3. In Settings section, you can define Allowed ports and Properties. You can also add one or multiple Tunnel for remote access to the app that is installed on the gateway. This enables remote engineering of the app:

– Enter Display name and Description.

– Enter URL, for example: http(s)://127.0.0.1:8085. 4. In Services section, select Add service.

5. Fill in the fields below appropriately:

– Enter Display name (will be visible in local gateway UI and in Asset Manager in Services tab).

– Enter Image link for the app icon.

Currently, version 1.0.0 of the Image registry.horizonint.cloud/gw-bif/gw-reference-app is available.

– The Network mode depends on the number of services you intend to add: If you want to add only 1 service select Network mode host. The port of the container is directly mapped to the host. If you want to add 2 more

services, select Network mode default. This mode requires defining the port mapping for the gw-reference-app. Source is always 9000. Target must be unique for each service you want to create, e.g., 9001, 9002, 9003… 6. Volumes for services:

– While configuring services under an Edge app, the developer can enable either / both of Settings & Data volume for the service.

– Enabling a volume for a service requires the target as input. This is the path within the container where the volume will be mounted at.

(9)

1

– These volumes are created at the application level and mounted to a service. If the same volume is enabled for multiple services within an app, they all share the same volume. This was done by design, due to a working assumption that developer would have control over all services being included in an Edge app and that there would be no concern if services of an app would share the same volume.

– On enabled volume, valid target MUST be provided.

7. Custom volumes for services:

– A developer can choose to define custom volume for a service, whereby the name of the volume, its target mount path has to be specified.

– Developer can define multiple such custom volumes for a service, each of which would be identified by the name given to them.

– If multiple services have a custom volume with the same name, then the custom volume is shared across the said services.

– To conform to the original concept, the actual volume on the Edge device is created with the name of the app prefixed to it.

– The original Settings & Data volumes are still available for the services along with any custom volumes that may have been defined.

8. Go to Open Source software license and fill in the according field. 9. Go to Release notes and fill in the according fields.

Release notes and Open Source software license mandatory for release. Uploading OSS license files [➙ 10]

10. Confirm with Update.

(10)

1 1.2.4 Uploading OSS license files

OSS license files ensure that Edge applications are aligned with clearance policy. One or multiple files can be uploaded and assigned to application versions.

OSS license files must have file extension .md or .txt. Minimum file size is 1 Byte, maximum is 10 MB.

Add OSS license file

1. Select an app.

2. Click on Manage OSS licenses.

3. Go to Add new file and select the OSS license file. Drag and drop is also possible.

4. Confirm with Upload.

 OSS license file is uploaded.

Assign OSS license file

1. Select an application version.

2. Go to Open Source software licenses tab. 3. Select one or multiple applicable OSS files. 4. Click on Update.

 Selected OSS licenses are assigned to the application version. OSS license files that are already assigned to application versions cannot be deleted. Assignment must be detached first.

1.2.5 Developing app

Once an Edge app is configured, Edge App Manager provides a feature for debugging & verifying the app on a physical Edge gateway.

(11)

1

 Reference Edge app project is cloned on the local PC. A clone can be created from

https://code.siemens.com/horizon/HEdge/reference-edge-app.  Windows terminal app is installed.

The following installation is recommended: https://conemu.github.io/

 SSH in maintenance page of Edge gateway is enabled.

 Edge gateway is connected to local PC via ethernet connection 169.254.169.254.

1. Open an app.

2. Select the application version which is required to be installed and tested on the device on Edge App Manager UI.

3. In Info tab, click Try app.

 Installation script is copied to clipboard. The script contains the access token and information on the app configuration to install the selected version on the Edge device.

4. Use Terminal supporting shell script to navigate to the Edge app cloned on local PC.

5. Paste the access token from clipboard.

The installation script copied to clipboard has a very short expiration time. It might be necessary to click Try app again to copy the installation script to clipboard. 6. Execute the command to start the installation.

7. Confirm prompts.

1.2.6 Updating app

1. Open the app you intend to update (see Managing life-cycle [➙ 14] for an overview of life-cycle states).

2. Go to Info tab.

 You can now see the current state of your app. 3. Click Update.

(12)

Edge App Manager User Guide Creating distribution

1

 The state of your app will change to Test. 4. Click Update again.

 The state of your app will change to Released.

5. Click twice on the back button to get back to the initial screen. 6. Check the overview page for the current state of your app.

 The state Released is displayed.

1.3 Creating distribution

A distribution defines a product domain and the required subscription to access it, e.g., Sinteso, Cerberus, SSP. For companies to see a distribution and it's versions, a corresponding subscription capability is required.

1.3.1 Adding distribution

This version of Edge App Manager supports only one distribution set per

company. An update to allow multiple distribution sets will be incorporated in later versions.

(13)

Edge App Manager User Guide Creating distribution

1

1. Click Create distribution below the Edge apps section if there is no distribution yet. Otherwise open an existing distribution.

2. Fill in the fields on the ensuing form appropriately. 3. Confirm with Create.

 The distribution is created.

1.3.2 Configuring distribution

 A distribution is created.

1. Open the distribution and click Add version.  A default app will automatically be installed. You can not uninstall a default app.

2. Select all applications you want to include in the distribution.

3. Click Next.

4. Select all application versions with compatible parameters. 5. Click Next.

(14)

Edge App Manager User Guide Managing life-cycle

1

6. Enter Version. 7. Click Save.

 The distribution is configured.

8. Check the overview page for the current state of your distribution.  The state Released is displayed.

1.4 Managing life-cycle

Edge apps and distributions go through several states until they are released/shared. These states define the Edge app/distribution life-cycle:

Edge app life-cycle

● Development ● Test ● Released ● Discontinued

Distribution life-cycle

● Test ● Preview

(15)

Edge App Manager User Guide Sharing Edge apps

1

● Released ● Discontinued

Configurations are possible in Development state only. The developer has to ensure a correct configuration prior to release.

Roles and responsibilities within the Edge app/distribution life-cycle

In Edge App Manager there are three roles. Each role is bound to a certain profile of rights:

State Developer Release-Manager Tester

Development x x

Test x x

Preview x

Released x

Discontinued x

1.5 Sharing Edge apps

EDS organizations develop and own Edge apps. Edge apps can be made publicly visible and specific app solutions can be shared across EDS organizations. Shared Edge apps will be visible in the app catalogue all EDS organizations have access to. The app catalogue is managed by Governance Organization

(16)

1 1.5.1 Publishing app

DEV ORG1 publishes an app to the app catalogue.  App is in state Released.

1. Select an app and open the context menu. 2. Click on Publish.

3. Confirm with Publish.

App will be visible in app catalogue once approved by the Governance Organization Administrator.

1.5.2 Approving app

The ADMIN (Governance Organization Administrator) checks the quality of the app. Once approved, the app is visible to all other EDS organizations.

 As a Governance Organization Administrator: 1. Go to App catalogue tab.

2. In Review apps, select an app and open the context menu. 3. Click on Approve.

(17)

1 1.5.3 Requesting app

DEV ORG2 requests an app from the app catalogue. Once approved, DEV ORG2 can include the app from DEV ORG1 in their distributions. DEV ORG2 cannot modify the requested app from DEV ORG1.

The App catalogue only displays approved apps. Access is granted to released app versions only.

1. Go to App catalogue tab.

2. In Published apps, select an app and open the context menu. 3. Click on Request.

(18)

Issued by Siemens Switzerland Ltd Smart Infrastructure Global Headquarters Theilerstrasse 1a CH-6300 Zug +41 58 724 2424 www.siemens.com/buildingtechnologies © Siemens Switzerland Ltd, 2020