industrial-edge / iectl-workflow

This application example shows how to use IECTL tool for automatic IEM/IED provisioning and application deployment.

Industrial Edge Control

Industrial Edge Control (IECTL) is a command line tool that enables you to interact with APIs of Industrial Edge components using just commands. This document describes how to use IECTL to automate workflow from provisioning IEM, onboarding Edge Devices to automatically deploying Edge applications. More information about the tool as well as the official documentation can be found here.

• Industrial Edge Control
  • Description
    • Overview
    • General task
  • Requirements
    • Prerequisites
    • Used Components
  • Installation
  • Implementation
  • Documentation
  • Contribution
  • License and Legal Information
  • Disclaimer

Description

Overview

This application example shows how to install and use IECTL in a complete workflow to automatically setup Edge components in 3 steps:

1. Activate IEM
2. Onboard Edge device
3. Deploy Edge applications

General task

The main goal of this example is to show how to setup the Industrial Edge platform in an automated workflow using IECTL. The idea is to provide with several shell scripts which can be adjusted and executed from a development environment to provision Industrial Edge components. This application example follows the network structure displayed in the picture below. The workflow starts with activating IEM in IE HUB, continues with automatic onboarding of one Edge Device and finally custom application is uploaded and deployed to the newly onboarded device. The provided shell scripts can be used and scaled for multiple IEMs, IEDs or applications. Please note that IP based IEM is used in this example and for DNS based setup the steps may differ.

Requirements

Prerequisites

• All Components are connected to a network with DHCP server available
• All components have an IP address
• IEM has connection to IE HUB
• IP based IEM is used in this example
• Linux Device with Docker and docker compose installed

Used Components

• Industrial Edge HUB
• Industrial Edge Management App v1.4.11
• Industrial Edge Management OS v1.4.0-42-amd64
• Industrial Edge Device v1.3.0-57
• Ubuntu 20.04 as development environment
• Industrial Edge Control (IECTL) for Linux v2.0.3

Installation

The installation steps can be found here. The installation consist of following steps:

• Activating IEM
• Onboarding IED
• Deploying self developed app

Implementation

The description of the implemented commands in the scripts can be found here.

Documentation

• You can find further documentation and help in the following links
  • Industrial Edge Hub
  • Industrial Edge Forum
  • Industrial Edge landing page
  • Industrial Edge GitHub page
  • Industrial Edge documentation page

Contribution

Thank you for your interest in contributing. Anybody is free to report bugs, unclear documentation, and other problems regarding this repository in the Issues section. Additionally everybody is free to propose any changes to this repository using Pull Requests.

If you haven't previously signed the Siemens Contributor License Agreement (CLA), the system will automatically prompt you to do so when you submit your Pull Request. This can be conveniently done through the CLA Assistant's online platform. Once the CLA is signed, your Pull Request will automatically be cleared and made ready for merging if all other test stages succeed.

License and Legal Information

Please read the Legal information.

Disclaimer

IMPORTANT - PLEASE READ CAREFULLY:

This documentation describes how you can download and set up containers which consist of or contain third-party software. By following this documentation you agree that using such third-party software is done at your own discretion and risk. No advice or information, whether oral or written, obtained by you from us or from this documentation shall create any warranty for the third-party software. Additionally, by following these descriptions or using the contents of this documentation, you agree that you are responsible for complying with all third party licenses applicable to such third-party software. All product names, logos, and brands are property of their respective owners. All third-party company, product and service names used in this documentation are for identification purposes only. Use of these names, logos, and brands does not imply endorsement.

iectl-workflow's Issues

issue template

did you use the Github template? Why is the issue template missing, which can be used for creating new issues?
==> https://github.com/industrial-edge/how-to-template/tree/main/.github/ISSUE_TEMPLATE

Spelling

All componets have a IP adress ==> please change to "an IP address"

Activate IEM

Note To finish this task, you need to have IE HUB API access granted. This means you need to have API key from IE HUB.

Maybe a short hint should be give how to enable it.

Additionally you should give a hint how to setup the IEM, you should add a link to the IEM Getting Started if someone is looking for information how to install the OS

Broker link

Please update link "here".

Go to your Linux environment and open the script for activating IEM. This script can be found here

That's the right link ==> https://github.com/industrial-edge/iectl-workflow/blob/main/src/activate-iem.sh

Deploying an unpublished application version to a device

I'm trying to build a pipeline that creates a new unpublished version of our application and deploys it onto a testing device.

Following the standalone app example, I tried this:

iectl publisher edgemanagement application uploadunpublishedversion \
    --appid "${APP_ID}" \
    --versionnumber "${version_new}"

iectl portal batches submit-batch \
    --appid "${APP_ID}" \
    --operation "installApplication" \
    --data "$(jq -c --null-input --arg deviceId "${DEVICE_ID}" '
      {
        "infoMap": {
          "devices":[
            $deviceId
          ]
        }
      }')" \
    --verbose

But this causes an error:

Error: request failed with status code 400 and response {"errors":[{"code":"notFound.appVersion","message":"App version not found.","errorCode":400,"field":"VersionVO","logref":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","parentLogref":""}]}

Investigating the network traffic from IEM web ui when I deploy from there, I can see it is making a request to:

https://${IEM_URL}/p.service/api/v4/applications/${APP_ID}/versions/${VERSION_ID}/batch?operation=installApplication&isRetainSecret=false&allow=true

and the infoMap only contains the target deviceIds.

So, how could I pass the versionId when using iectl? If this is currently not possible with iectl, would it be possible to obtain the needed headers from iectl and do the same request for example with curl?

Side note: I think running iectl portal batches submit-batch --help should show what information can/should be passed in infoMap. There is currently no mention of {"devices": [ $deviceIds ]}.

Using iectl version 1.3.1 on linux.

Absoluth Path

Please do not use absolut path or give a hint that this path needs to be modified:

iectl-workflow/src/create-ied.sh

Line 27 in 8c206b1

rm -rfv /home/siemens/iemctl-region-call/onboarding-file/*

Sentence too complex

The following sentence is hard to read, please make it a bit more easy to read.
Additionally you are talking about "executed from a device", I initially thought it is a Edge Device, but for it is not. Maybe better use another word instead of device (engineering station or something similiar).

Same in "installation.md": Note Linux device is used to run shell scripts with IECTL commands.
I would use a different term than "device"

The idea is to provide with several shell scripts which can be executed from a device which has connection to the Industrial Edge componments you want to interact

Link to iectl documentation

please also add a link to the IECTL documentation, that customers can check additional information:

https://industrial-edge.io/developer/platform/references/iectl/index.html

Clone repository and prepare the environment

Why workspace and onboarding-file folder are not available in the github repo?
If you do not want them to be available please explicitly mention that these two folders need to be created, I was a bit confused that I need to check which of the folders are available and which of the I need to create

Link broken

The link to the official docu is broken - see here:

https://github.com/industrial-edge/iectl-workflow/blob/main/README.md

"More information about the tool as well as the official documentation can be found [here]"

Broken link: https://industrial-edge.io/developer/platform/references/iectl/index.html
Correct link: https://docs.eu1.edge.siemens.cloud/apis_and_references/iectl/index.html

IP-Based setup

You should also mention somewhere that this example is setting up an IP-Based setup and for DNS-Based some additional steps are needed- Probably somewhere you need to specify the URLs as well as importing the certificates, right?