Setting up IEM¶

Run the manifest file using IECTL to set up the IEM.

Also, make sure you have a CLI user available in your iehub environment. See the steps below to create one if you don't already have one.

Open the Industrial Edge Hub in your browser.
From top right menu click the API access management icon.
Click the + Grant API Access button
Enter your details, a password will be generated, copy this password and keep it handy for future use.

Before you run the manifest file, run the following command.

export EDGE_SKIP_TLS=1

Save the manifest template as dev-setup-iem.yaml:¶

Please read the commented fields in the yaml file and update the values accordingly. Replace other variable values also with your actual credentials, IP addresses, or namespace and download locations. Make sure all values are correct and meet your requirements.

Required parameters¶

config_url : iehub url on which iem instance will be created
config_user : iehub cli username
config_password : iehub cli password
onboard_file : local path where onboarding file needs to be downloaded
iem_namespace : use same namespace of iem which was used during kind cluster and kong cert creation
iemuser : provide a username which will be used to login on IEM.
iemurl : use IP address of your host machine with https protocol and port 443
iemip : use ip address of your host machine
iempassword : create a pssword for the IEM, please refer the rules in manifest for creating it.
global.certchain : copy the output of bash cat /path/to/certChain.crt | base64 -w 0 and update this parameter. Also please update the path to the certChain.crt file before executing the command

Optional parameters¶

config_name : iectl iehub config name
iem_instance_name: iem instance name that will be created on iehub

variables:
  config_name: "test_iehub"   #update iectl iehub config name
  config_url: "https://iehub.eu1.edge.siemens.cloud"    #update iehub url on which iem needs to be onboarded
  config_user: "user@siemens.com"   #update iehub cli user
  config_password: "cliuserpassword"   #update iehub cli user password
  onboard_file: "/Downloads/helm.json"   #update local path where onboarding file needs to be downloaded
  iem_instance_name: "devieminstance"    #update iem instance name that will be created on iehub
  iem_namespace: "deviem"    #update same namespace of iem which was used during kind cluster and kong cert creation
  iemuser: "iemuser@siemens.com"   #update iem user email
  iemurl: "https://iem-url"   #update iem url
  iemip: "iem-url"   #update iem url
  iempassword: "S@MpleP@ssw0rd"     #update iem admin password, must contain at least 12 characters, one lower case, one upper chase, one special character (!@$#*&%) and one digit
commands:
 - command:
   target: config
   resource: add.iehub
   parameters:
     user: "${{config_user}}"
     password: "${{config_password}}"
     url: "${{config_url}}"
     name: "${{config_name}}"
 - command:
   target: iehub
   resource: instance-management.create
   parameters:
     name: "${{iem_instance_name}}"
     allowfailure: "true"
 - command:
   target: iehub
   resource: instance-management.get-details
   parameters:
     name: "${{iem_instance_name}}"
     filepath: "${{onboard_file}}"
 - command:
   target: provision
   resource: install
   arguments:
      - ${{onboard_file}}
   parameters:
      namespace: "${{iem_namespace}}"
      set: 
       - global.hostname=${{iemip}}  
       - global.iemAdminPassword=${{iempassword}}    
       - global.iamAdminPassword=${{iempassword}}   
       - central-auth.keycloak.initialUser.username=iemuser
       - central-auth.keycloak.initialUser.email=${{iemuser}}  
       - global.certChain=LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUdIVENDQkFXZ0F3SUJBZ0lVRHdGL3VPaTdZQ #update output of : cat /path/to/certChain.crt | base64 -w 0
       - kong.deployment.hostNetwork=true
       - kong.dnsPolicy=ClusterFirstWithHostNet
       - kong.proxy.tls.hostPort=443
       - kong.proxy.http.hostPort=80
       - kong.containerSecurityContext.capabilities.add={NET_BIND_SERVICE}
       - kong.containerSecurityContext.runAsGroup=0
       - kong.containerSecurityContext.runAsNonRoot=false
       - kong.containerSecurityContext.runAsUser=0
       - kong.proxy.http.containerPort=80
       - kong.proxy.tls.containerPort=443
       - kong.deployment.daemonset=true
       - kong.env.SSL_CERT=/etc/secrets/kongcert/tls.crt
       - kong.env.SSL_CERT_KEY=/etc/secrets/kongcert/tls.key
       - kong.secretVolumes.kong-proxy-tls=kongcert
       - device-catalog.workflowexecutor.enabled=true
       - device-catalog.firmwaremanagement.enabled=true
 - command:
   target: iem
   resource: system.onboard-status
   parameters:
     url: "${{iemurl}}"
     username: "${{iemuser}}"
     password: "${{iempassword}}"

How to run the manifest¶

./iectl apply -f path/to/dev-setup-iem.yaml

For running the manifest in verbose mode:

./iectl apply -f path/to/dev-setup-iem.yaml --verbose

When the IEM deployment was successful, you can open the IEM Launchpad at the URL: https://<hostip>/.

IEM Login

Rollback IEM on Failure¶

If at any point the IEM fails to onboard, please run the following commands before re-running the IEM setup manifest. Create a shell script with the name rollback-manifest.yaml and copy the content below.

variables:
  config_name: "test_iehub"   #update iectl iehub config name
  config_url: "https://iehub.eu1.edge.siemens.cloud"    #update iehub url on which iem needs to be onboarded
  config_user: "user@siemens.com"   #update iehub cli user
  config_password: "cliuserpassword"   #update iehub cli user password
  iem_instance_name: "devieminstance"    #same name which is used while setting up IEM
commands:
 - command:
   target: config
   resource: add.iehub
   parameters:
     user: "${{config_user}}"
     password: "${{config_password}}"
     url: "${{config_url}}"
     name: "${{config_name}}"
 - command:
   target: iehub
   resource: instance-management.delete
   parameters:
     name: "${{iem_instance_name}}"

Create a shell script with the name rollback.sh and copy the content below.

#!/bin/bash

certkey=""
cert=""
namespace="deviem"
while getopts k:c:h:r:t:n: flag; do
 case "$flag" in
  k)
   kindversion=${OPTARG};;
  c)
   kubectlversion=${OPTARG};;
  h)
   helmversion=${OPTARG};;
  r)
   certkey=${OPTARG};;
  t)
   cert=${OPTARG};;
  n)
   namespace=${OPTARG};;
 esac
done
iectl apply -f rollback-manifest.yaml --verbose
kubectl delete namespace $namespace
kubectl create namespace $namespace
kubectl -n $namespace create secret tls kongcert --key $certkey --cert $cert

After the above step is completed, run the script with the following command

NOTICE

Please update the value of the iem namespace variable -n before running. Use the same iem namespace that was created during cluster setup.

  bash +x rollback.sh -r "out/myCert.key" -t "out/myCert.crt" -n "deviem"

Setup IED¶

Run the manifest file using IECTL to set up the IED.

Before executing the manifest file, please run the command below. Also make sure to have a CLI user ready on your iehub environment.

export EDGE_SKIP_TLS=1

Save the manifest template as dev-setup-ied.yaml:¶

Please read the commented fields in the yaml file and update the values accordingly. Replace other variable values also with your actual credentials, IP addresses, or namespace and download locations. Make sure all values are correct and meet your requirements.

Required parameters¶

config_url : iehub url from which ied kit will be donwloaded
config_user : iehub cli username
config_password : iehub cli password
iemuser : iem username which was created in iem manifest
iemurl : iem url https://<hostip>:443
iempassword : iem password which was created in iem manifest
ieduser : provide a username to login on IED
iedurl : https://<hostip>:9445
iedpassword : create a pssword for the IED, please refer the rules in manifest for creating it.
macAddress : mac address of VM on which ied is setup by using command : ip addr show
devicetypeID : please update the variable devicetypeID in the below yaml based on device types available on IEM. To check available device types use command iectl iem device-types.
download_path : update download path where ied kit artifact will be downloaded from IEHUB

Optional parameters¶

config_name : iectl iehub config name

variables:
  config_name: "test_iehub"   #update iectl iehub config name
  config_url: "https://iehub.eu1.edge.siemens.cloud"    #update iehub url from which ied kit will be downloaded
  config_user: "user@siemens.com"   #update iehub cli user
  config_password: "cliuserpassword"   #update iehub cli user password
  iemuser: "iemuser@siemens.com"   #update iem user email
  iemurl: "https://iem-url"   #update iem url
  iempassword: "S@MpleP@ssw0rd"     #update iem admin password, must contain at least 12 characters, one lower case, one upper chase, one special character (!@$#*&%) and one digit
  ieduser: "ieduser@siemens.com"   #update ied user email
  iedurl: "https://ied-url:9445"   #update ied url with port 9445
  iedpassword: "S@MpleP@ssw0rd"    #update iem admin password, must contain at least 12 characters, one lower case, one upper chase, one special character (!@$#*&%) and one digit
  macAddress: "00:00:11:ab:00:11" # update the host machine mac address
  devicetypeID: "core.ieipc" #check if device type exists on IEM
  download_path: "/Downloads/"   #update download path where ied artifact will be downloaded from IEHUB
commands:
 - command:
   target: config
   resource: add.iehub
   parameters:
     user: "${{config_user}}"
     password: "${{config_password}}"
     url: "${{config_url}}"
     name: "${{config_name}}"
 - command:
   target: config
   resource: add.iem
   parameters:
     name: "iem_config"
     url: "${{iemurl}}"
     user: "${{iemuser}}"
     password: "${{iempassword}}"
 - command:
   target: iem
   resource: system.onboard-status
   parameters:
     url: "${{iemurl}}"
     username: "${{iemuser}}"
     password: "${{iempassword}}"
 - command:
   target: iehub
   resource: run-ied-dev
   parameters:
     name: "Industrial Edge Device Kit - x86-64"
     path: "${{download_path}}"
 - command:
   target: iem
   resource: device.onboard
   parameters:
     id: "${{devicetypeID}}"
     url: "${{iedurl}}"
     name: "ied_dev"
     username: "${{ieduser}}"
     password: "${{iedpassword}}"
     allowfailure: "true"
     nics: '{"MacAddress":"${{macAddress}}","GatewayInterface":true,"DHCP":"enabled","Static":{"IPv4":"","NetMask":"","Gateway":""}}'   #mac address of VM on which ied is setup by using : ip addr show

Running the manifest¶

./iectl apply -f path/to/dev-setup-ied.yaml

for running the manifest in verbose mode

./iectl apply -f path/to/dev-setup-ied.yaml --verbose

When the IED deployment was successful, the IED can be opened at the URL: https://<hostip>:9445/.

Ied-Login

Important checkpoints¶

Please change the iem instance name before running the manifest again.
Only one IEM instance can be mapped to a namespace. If the namespace is created and manifest fails in between, please delete the cluster and follow the process to create a new cluster and namespace and update the manifest with new values.
The IEDK will be created on port "9445". Update the IED url with port as well.
To find the VM's Mac address, run the ifconfig command in a terminal.

Deleting Cluster¶

To delete the clusteruse the command:

kind delete cluster

To delete the IED use the command:

docker ps #to check ied container id
docker rm -f < Container_ID>
docker rmi -f <ied image name>