Skip to main content
Hitachi Vantara Lumada and Pentaho Documentation

Install and configure IIoT Core Services

This chapter describes important preparatory steps before installing IIoT Core Services, the installation process itself, and the necessary post-installation tasks.

Preparing for IIoT Core Services installation

Before you begin installing IIoT Core Services, you should review all of the information in this chapter, gather the required information, and complete any necessary installations.

Installation node requirements

As a best practice, install IIoT Core Services from a small VM node outside the cluster but within the same network environment.

The following minimum requirements apply to the VM installation node.

Hardware Specifications
CPUIntel Atom or equivalent processor, 4 cores
Memory 8 GB
Disk space120 GB

IIoT Core Services supports the following operating systems on the installation node:

Software Version
Red Hat Enterprise Linux (RHEL) 8.4

IIoT Core Services system requirements

IIoT Core Services is designed to be installed in a cluster with a minimum of three nodes.

The following table lists the minimum requirements for each of the cluster nodes:

Hardware Specifications

CPU

2 Intel Xeon Scalable E5-2600 v5 or equivalent AMD processors, 64-bit, 8 cores
Memory 16 GB
Disk space512 GB

For worker nodes running Machine learning service, the following minimum requirements apply:

Hardware Specifications

CPU

GPU: 1 T4 GPU

Without GPU: 8 cores

Memory 16 GB
Disk space512 GB

IIoT Core Services supports the following operating system for cluster nodes:

Software Version
Red Hat Enterprise Linux (RHEL) 8.4

Installation prerequisites

Observe the following prerequisites before installing IIoT Core Services. These are global prerequisites that apply to all IIoT Core Services components, including the platform component.

IIoT Core Services prerequisites

To install IIoT Core Services, complete the following prerequisites.

High-level prerequisites
  • Install and configure Kubernetes in a three node cluster. See the Kubernetes Documentation for more information.
  • Use the command option -n hiota when installing the IIoT Core Services platform components. The platform components must be installed in the same hiota namespace where IIoT Core Services is installed.
  • You must have a FQDN for the cluster.
Component prerequisites

Observe the following specific prerequisites before installing the IIoT Core Services components.

ComponentRequirement
Kubernetes

A secured Kubernetes system (v1.21.6) with a kubeconfig file for API server access.

In addition to installing Kubernetes, optionally install and configure a Kubernetes dashboard.

Default storage class

To maximize solution portability, the Kubernetes system must declare a default storage class for dynamic provision of storage resources.

To verify that your Kubernetes cluster declares a default storage class (or you enable one), follow the instructions in the Kubernetes documentation on changing the default StorageClass.

Storage plugin

Install a storage plugin with the following specifications:

Googles Kubernetes Engine (GKE)

Storage class: GKE standard

Follow the instructions for creating a Kubernetes cluster using GKE in the Google documentation on the Kubernetes engine.

On-premises

Based on what best suits your hardware environment, choose one of the following options. Both options have been tested with IIoT Core Services 5.0.0:

Load balancer

Set up a load balancer to forward requests to the Kubernetes cluster node for the following ports:

  • 30084
  • 30086
  • 30090
  • 30091
  • 30092
  • 30223
  • 30224
  • 30228
  • 30303
  • 30443
  • 30671
  • 30884
  • 30998
  • 30999
  • 31000
  • 31671
  • 32500
Registry requirementsSee Registry requirements and Example of how to set up a Docker registry.
nfs-utils

Only applies to on-premises installations of IIoT Core Services when ML Services is selected as an optional installation:

Either install a nfs-utils package on all three nodes for NFS server installation or use an external NFS server. Different OS versions require a different version of nfs-utils.

DatabasesThe following database versions are supported with the current version of IIoT Core:
  • Couch: 2.3.1
  • InfluxDB: 2.1.1
  • Kafka: 2.12-2.3.0
  • Knative-eventing: v0.18.3
  • Knative-serving: v0.18.1
  • MinIO: RELEASE.2021-04-06T23-11-00Z.hotfix.e46577116

Registry requirements

IIoT Core Services requires a registry for container images that is OCI-compliant and has an SSL certificate.

Using FQDN from deployment

When deploying both cluster services and the control plane, specify the fully qualified domain name (FQDN) of this registry, either using the -r argument or the installer configuration file. The value you specify needs to include both the host and port for your registry. For example:

-r myregistry.example.com:6000

If your registry is available on port 443, you don't need to specify the port number.

Multitenancy

If you are using a registry that supports multitenancy, you also need to include the specific location within the registry that you want to use. For example, if you are using Harbor, include the name of the Harbor project you want to use:

-r myharbor.example.com:6000/my_project
Using an insecure registry

If the registry you are using is insecure (that is, it has a self-signed or otherwise not trusted SSL certificate), you must configure your Docker daemon on the installation node to allow the insecure registry.

This configuration is often done by adding the registry to the insecure-registries section of /etc/docker/daemon.json, and restarting the Docker service. Configure the container runtime on the cluster to allow the insecure registry. Specify the -I flag for install-control-plane.sh and for install-cluster-services.sh.

As a best practice, use a trusted, CA-signed certificate.

For information on setting up a non-production registry that meets requirements, see the following example.

Example of how to set up a Docker registry

This section walks you through the process of setting up a non-production, insecure registry that IIoT Core Services can use with Docker Registry.

A non-production (development-only) environment requires an OCI-compliant registry that uses HTTPS. To authenticate with the registry, use a username and password, not an auth plugin or credential helper.

ImportantThis registry configuration is not for production purposes. For production use, configure a registry with a trusted certificate and enforced authentication. As a best practice, configure the registry to be read-only for runtime use.

Before you begin

The following must be set up before running the procedure:

  • Docker
  • OpenSSL command line

Procedure

  1. Generate a self-signed OpenSSL certificate.

    mkdir -p certs
    openssl req \
      -newkey rsa:4096 -nodes -sha256 -keyout certs/domain.key \
      -x509 -days 365 -out certs/domain.crt -subj "/CN=$(hostname -f)"
  2. Start the Docker registry on port 5000 by passing a self-signed Open SSL certificate to the Docker registry.

    docker run -d -v "$(pwd)"/certs:/certs \
      -e REGISTRY_HTTP_ADDR=0.0.0.0:5000 \
      -e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt \
      -e REGISTRY_HTTP_TLS_KEY=/certs/domain.key \
      -p 5000:5000 \
      --name registry \
      --restart unless-stopped \
      registry:2
    NoteFor additional options, see https://docs.docker.com/registry/deploying/.
  3. Ensure that the registry is included in the list of insecure registries in your container runtime.

    Make sure to include <registry_hostname>:5000 in insecure-registries in /etc/docker/daemon.json.
    1. Create a /etc/docker/daemon.json file, if you don't already have one.

    2. In this file, add <registry_hostname>:5000 to a list of insecure registries:

      {  
          "insecure-registries" : [
              "<registry_hostname>:5000"
          ]  
      }
    3. Restart Docker for the configuration changes to take effect:

      systemctl restart docker
    4. Run docker info and verify that the list of Insecure Registries is correct.

      For example:
      Client:
       Debug Mode: false
      Server:
       Containers: 150
        Running: 67
        Paused: 0
        Stopped: 83
       Images: 217
       Server Version: 19.03.5-ce
       ...
       Insecure Registries:
        <registry_hostname>:5000
        127.0.0.0/8
       Live Restore Enabled: false
    For more information on daemon.json, see the official Docker documentation.
  4. Test the registry by pulling, tagging, and pushing an image:

    docker pull ubuntu
    docker image tag ubuntu $(hostname -f):5000/my-ubuntu
    docker push $(hostname -f):5000/my-ubuntu

    If you see output similar to the following, your registry is working correctly:

    Using default tag: latest
    latest: Pulling from library/ubuntu
    423ae2b273f4: Pull complete 
    de83a2304fa1: Pull complete 
    f9a83bce3af0: Pull complete 
    b6b53be908de: Pull complete 
    Digest: sha256:04d48df82c938587820d7b6006f5071dbbffceb7ca01d2814f81857c631d44df
    Status: Downloaded newer image for ubuntu:latest
    docker.io/library/ubuntu:latest
    The push refers to repository [<registry_hostname>:5000/my-ubuntu]
    1852b2300972: Pushed 
    03c9b9f537a4: Pushed 
    8c98131d2d1d: Pushed 
    cc4590d6a718: Pushed 
    latest: digest: sha256:0925d086715714114c1988f7c947db94064fd385e171a63c07730f1fa014e6f9 size: 1152

    You can also list the contents of the registry using the following commands:

    $ curl https://$(hostname -f):5000/v2/_catalog -k
    
    {"repositories":["my-ubuntu"]}

Results

The registry is now set up and ready for use.

Next steps

To remove this registry, run the following command:

docker stop registry; 
docker rm registry

Port configuration requirements (Core Services)

To use IIoT Core Services, you must provide access to the ports used by the system services and databases.

Message brokers, databases, and external-facing services

IIoT Core Services uses a combination of message brokers and RESTful services. Message brokers establish communication between applications and infrastructure for message queues and topics.

Check the following message brokers, databases, and other services to determine if the corresponding ports need to be open to run your IIoT Core Services. The needed ports must be open both on the load balancer and on each node.

Message brokers
ServiceDescriptionDefault portOptional installDefault loginLinks
AMQP - RabbitMQMessaging over AMQP30671Noadmin

Documentation: https://www.rabbitmq.com/documentation.html

Databases
ServiceDescriptionDefault portOptional installDefault loginLinks
CouchDBUnstructured data database access30084Noadmin

Documentation: http://docs.couchdb.org/en/stable/

UI: https://<IP-address>:30084

OR

https://<load-balancer-address>:30084

OR

https://<cluster_fqdn>:30084

InfluxDBTime-series data (historical data) database access30086Noadmin

Documentation: https://docs.influxdata.com/influxdb

MinIOObject storage database access31000Noadmin

Documentation: https://docs.min.io/docs/

UI: https://<IP-address>:31000/minio/login

OR

https://<load-balancer-address>:31000/minio/login

OR

https://<cluster_fqdn>:31000/minio/login

Services
ServiceDescriptionDefault portOptional installDefault loginLinks
Hiota Ingress RESTHTTPS data ingestion to IIoT Core30443NoN/A

N/A

Hiota Passport

CouchDB

Passport API access to Couch data

30224NoN/AN/A

InfluxDB

Time-series data (historical data) access

30223NoN/AN/A

PostgreSQL

Structured data access

30228NoN/AN/A
Hiota Product APIsAccess to management plane APIs30443NoN/ADocumentation: See Management plane REST API
OAuth-HelperSimple OAuth handling30303NoN/A

N/A

Other services
ServiceDescriptionDefault portOptional installDefault loginLinks
SparkKubernetes Operator for Apache Spark N/AYesN/A

Documentation: https://spark.apache.org/docs/latest/

Internal core services

Because the following ports are used by internal IIoT Core Services applications, verify that these ports are open to external access for the assigned IIoT Core Services to work properly.

Message brokers
ServiceDescriptionDefault portLinks
KafkaKafka messaging support30090, 30091, 30092

Documentation: https://kafka.apache.org/intro

RabbitMQ (https-UI)UI for troubleshooting31671

Documentation: https://www.rabbitmq.com/documentation.html

MQTT - RabbitMQMessaging over MQTT for gateway devices30884

Documentation: https://www.rabbitmq.com/documentation.html

Databases
ServiceDescriptionDefault portDefault loginLinks
ArangoDBArangoDB multi-model database system30529admin

Documentation: https://www.arangodb.com/documentation/

CouchDB (https-UI)UI for troubleshooting30984admin

Documentation: http://docs.couchdb.org/en/stable/

UI: https://<IP-address>:30984/_utils/#login

OR

https://<load-balancer-address>:30984/_utils/#login

OR

https://<cluster_fqdn>:30984/_utils/#login

Services
ServiceDescriptionDefault portLinks
Docker Trusted RegistryPrivate Docker trusted registry that stores and manages Docker images for gateway services or user applications that run on gateways32500

Documentation: https://docs.docker.com/ee/dtr/

Hiota Alert ManagerEnables alert management 30443N/A
Hiota AssetEnables asset and gateway management 30443N/A
Hiota Kube ResourceManagement wrapper API for Kubernetes resources for activities such as deploying software and configurations to gateways30443N/A
Hiota Manager (gRPC server)gRCP server for internal connections30999N/A
Hiota Manager (REST server)REST server for hiota-agent30998N/A
Hiota OI ManagerOpen Image Manager enables upload of software on the user interface and provides statuses.30800N/A
OAuth-HelperSimple OAuth handling30303N/A
Hiota RegistryAccess to core and gateway route endpoints and statuses as well as core service configurations30443N/A
Hiota User PreferencesUser preferences for notifications30231N/A

Machine learning service resource requirements

Machine learning service is a range of services that offer machine-learning tools as part of cloud computing services.

You can activate Machine learning service during the IIoT Core Services installation process to get started with machine learning.

For all cluster nodes, if you elect to enable Machine learning service during the IIoT Core Services installation process, note the following resource requirements:

RequirementsSpecifications
Minimum memory and processor requirements
  • 16 vCPU
  • 48 GB RAM
Disk space requirements
  • 10 GB storage for each user on Jupyter
  • 1 GB for JupyterHub
  • 2 GB for Seldon Core Analytics Prometheus Alert Manager
  • 15 GB for MLflow database

Access the IIoT Core Services software

To download the IIoT Core Services software, go to https://support.pentaho.com and log in. The software includes the following TAR files:

  • IIoT Core Services platform installation package.
  • IIoT Core Services main installer script.
  • (Optional) Modbus. Install the Modbus protocol after the core installation is complete.
  • IIoT Core Services Docker images.
  • (Optional) Machine learning service Docker images.
  • (Optional) Digital Twin Beta Docker images.
  • (Optional) Command Line Interface (CLI) application.

Setting up the Kubernetes cluster

IIoT Core Services can be deployed on different types of Kubernetes clusters:

IIoT Core comes with a Docker Trusted Registry (DTR) that is used to store Docker images of gateway services and user applications. See information about the Docker Trusted Registry service in Internal core services.

NoteThis DTR is different from the IIoT Core DTR or Google Container Registry (GCR) that is used to store the Docker images for IIoT Core Services.

For memory and disk space requirements for the installation node, see Installation node requirements.

Configure a GKE cluster with user hosted GCR

You can install a Google Kubernetes Engine (GKE) cluster by creating your own hosted Google Container Registry (GCR).

As a best practice, use an installer VM that is outside the cluster but can access the cluster nodes.

To log in to the GCR repository, use the JSON file reference to get the token:

cat <read-write-json-token> | docker login -u _json_key --password-stdin <gcr-url>
cat <read-write-json-token> | HELM_EXPERIMENTAL_OCI=1 helm registry login <gcr-url> -u _json_key --password-stdin

Procedure

  1. Download the following tarballs to a node that can connect to the hosted DTR and has Docker installed:

    • iiot-docker-images-release-5.0.0.tgz
    • iiot-installer-release-5.0.0.tgz
    • (Optional) mlservice-docker-images-1.0.0.tgz
    • (Optional) aaf-docker-images-5.0.0.tgz (Digital Twin Beta)
    On this node, the partition with /var/lib/docker (Docker default local repository) should have at least 120 GB free space. You can check how much space is available using the command df -h /var/lib/docker. The partition is needed later for loading and pushing Docker images to the registry.
  2. Open the core software package by executing the following command:

    tar xvf iiot-installer-release-5.0.0.tgz
    A new directory is created: iiot-installer-release-5.0.0
  3. Open the Docker images TAR file:

    tar xvf iiot-docker-images-5.0.0.tgz
  4. (Optional) Open the Machine learning service images TAR file and add og move the untarred folder to iiot-installer-release-5.0.0/mlaas/images:

    tar xvf mlservice-docker-images-5.0.0.tgz
    mv mlaas/images iiot-installer-release-5.0.0/mlaas/
  5. (Optional) Open the Digital Twin Beta docker image file and add og move the untarred folder to iiot-installer-release-5.0.0/aaf/images:

    tar xvf aaf-docker-images-5.0.0.tgz
    mv aaf/images iiot-installer-release-5.0.0/aaf/
  6. Push the hiota-solutions Helm chart and corresponding solution package to the IIoT Core Services DTR.

    This push only needs to be done once before starting the installation process so that the Solution Control Plane can manage hiota-solutions. Otherwise, hiota-solutions will not appear on the control plane user interface even though the IIoT Core Services is running.
    export HELM_EXPERIMENTAL_OCI=1
    helm chart save <path to IIoT Core Services 5.0.0 image>/iiot-installer-release-5.0.0/Module-4/hiota-solutions-5.0.0.tgz <core-dtr url>/hiota-solutions:5.0.0
    helm registry login <core-dtr url> -u <username> -p <password>
    helm chart push <core-dtr url>/hiota-solutions:5.0.0
    kubectl apply -f <path to IIoT Core Services 5.0.0 image>/iiot-installer-release-5.0.0/Module-4/roles/core-services/install/files/hiota_solution_package.yaml
  7. Obtain the hosted GCR login information (json_key file with read-write permission, for example).

  8. Tag the Docker images and push them to the hosted registry. This push needs to be done only once.

    The script can also be found in the IIoT Core Services installer script image folder: iiot-installer-release-5.0.0/tag-push-docker-images.sh.
  9. Create the GKE 3-node cluster.

  10. Create the installer VM on GCP with Python 3, Helm 3.4.x, and kubectl installed.

    Check if you can connect to the Kubernetes cluster with the kubectl command. The rest of the IIoT Core Services installation process is performed on the installer VM.

Results

Your cluster is now prepared to install IIoT Core Services using your own hosted GCR. To proceed with the installation of IIoT Core Services, go to Installing IIoT Core Services.

Configure a Kubernetes cluster on premises

You can run IIoT Core Services on your own Kubernetes cluster using your own Docker Trusted Registry (DTR).

As a best practice, use an installer VM that is outside the cluster but can still access the cluster nodes.

Procedure

  1. Download the following tarballs to a node that can connect to the hosted DTR and has Docker installed.

    • iiot-docker-images-release-5.0.0.tgz
    • iiot-installer-release-5.0.0.tgz
    • (Optional) mlservice-docker-images-1.0.0.tgz
    • (Optional) aaf-docker-images-5.0.0.tgz (Digital Twin Beta)
    On this node, the partition with /var/lib/docker (Docker default local repository) should have at least 120 GB free space. You can check how much space is available using the command df -h /var/lib/docker. The partition is needed later for loading and pushing Docker images to the registry.
  2. Open the core software package by executing the following command:

    tar xvf iiot-installer-release-5.0.0.tgz
    A new directory is created: iiot-installer-release-5.0.0
  3. Open the Docker images TAR file:

    tar xvf iiot-docker-images-5.0.0.tgz
  4. (Optional) Open the Machine learning service images TAR file and add og move the untarred folder to iiot-installer-release-5.0.0/mlaas/images:

    tar xvf mlservice-docker-images-5.0.0.tgz
    mv mlaas/images iiot-installer-release-5.0.0/mlaas/
  5. (Optional) Open the Digital Twin Beta Docker image file and add og move the untarred folder to iiot-installer-release-5.0.0/aaf/images:

    tar xvf aaf-docker-images-5.0.0.tgz
    mv aaf/images iiot-installer-release-5.0.0/aaf/
  6. Obtain the hosted core DTR login information, such as user name and password.

  7. Tag the Docker images and push them to the hosted registry. This push needs to be done only once.

    The script can also be found in the IIoT Core Services installer script image folder iiot-installer-release-5.0.0/tag-push-docker-images.sh.
  8. Create an on-prem 3-node Kubernetes cluster with a storage plugin.

  9. Verify that Python 3, Helm 3.4.x, and kubectl are installed on the installation node.

Results

Your cluster is now prepared to install IIoT Core Services. To proceed with the installation ofIIoT Core Services, go to Installing IIoT Core Services.

Installing IIoT Core Services

After the software prerequisites are met and your hosted environment is set up, you can install IIoT Core Services.

Install the platform components

This section describes how to install the IIoT Core Services platform components, also referred to as Foundry, for the purpose of installing IIoT Core Services.

Before you begin

If you are reinstalling the platform components, first uninstall any current instance of the software on your system to conserve system resources. See Uninstall the platform components.

NoteBefore uninstalling the platform components, make sure to first uninstall IIoT Core Services. See Uninstall IIoT Core Services.

Procedure

  1. Log in to the installation node.

  2. Download the platform installation package to the installation node:

    Foundry-Control-Plane-2.3.0.tgz
  3. Open the platform installation package by executing the following command:

    mkdir Foundry-Control-Plane-2.3.0
    tar xvf Foundry-Control-Plane-2.3.0.tgz -C ./Foundry-Control-Plane-2.3.0
    NoteYou must perform the installation from a directory that is at least two levels from the root level, as shown above.
  4. Navigate to the platform software directory:

    cd Foundry-Control-Plane-2.3.0
  5. Get an access token:

    gcloud auth print-access-token
  6. To install Keycloak, manually create a file called foundry-control-plane-values.yaml, which is used with the control plane installation command, with the following contents:

    keycloakoperator:
      publicPath: /auth
    configuration:
      keycloak:
        enableDockerAuthentication: true
        instances: 3
    logging:
      enabled: false
  7. If you have credentials for the IIoT Core Services Docker Trusted Registry (DTR), try logging into the DTR from the cluster nodes to verify access.

  8. Navigate to the bin directory:

    cd foundry-control-plane-2.3.0/bin
    NoteYou must perform the installation from a directory that is at least two levels from the root level, as in /root/foundry-control-plane-2.3.0/bin
  9. Install the platform cluster service using the following commands:

    For GKE:

    ./install-cluster-services.sh -r <core-dtr-url> -w service-type=NodePort -u oauth2accesstoken -p $(gcloud auth print-access-token)

    For on-premises:

    ./install-cluster-services.sh -r <core-dtr-url> -w service-type=NodePort -u <username> -p <password>
  10. Set the number of replicas of istiod, istio-ingressgateway, and istio-egressgateway you want to run by scaling as follows:

    Example using three replicas:
    kubectl scale deployment -n istio-system --replicas=3 istiod
    kubectl scale deployment -n istio-system --replicas=3 istio-ingressgateway
    kubectl scale deployment -n istio-system --replicas=3 istio-egressgateway
  11. Apply Kubernetes custom resource definitions.

    For GKE:

    cd Foundry-Control-Plane/bin/
    ./apply-crds.sh -r <gcr-url> -e -u oauth2accesstoken -p $(gcloud auth print-access-token)

    For on-premises:

    cd Foundry-Control-Plane/bin/
    ./apply-crds.sh -r <core-dtr-fqdn>:[<port>] -e -u <username> -p <password> 
    --insecure
  12. Install the control plane.

    For GKE:

    cd Foundry-Control-Plane/bin/
    ./install-control-plane.sh -r <gcr-url> -c https://<cluster-fqdn>:30443 -n hiota -u oauth2accesstoken -p $(gcloud auth print-access-token) -v
    <path-to>/foundry-control-plane-values.yaml --skip_cluster_url_check

    For on-premises:

    cd Foundry-Control-Plane/bin/
    ./install-control-plane.sh -I -r <core-dtr-url> -c https://<cluster-fqdn>:30443 -n hiota -u <username> -p <password> -v
    <path-to>/foundry-control-plane-values.yaml

Results

To verify that the platform components have been properly installed, go to Verify IIoT Core platform installation.

Verify IIoT Core platform installation

Log in to the Solution Management UI, an administrative console for the installation, and check the platform software version.

Procedure

  1. From the command line on the installation node, get the username and password for the Solution Management UI:

    • Username:
      echo $(kubectl get keycloakusers -n hiota keycloak-user -o jsonpath='{.spec.user.username}')
    • Password:
      echo $(kubectl get keycloakusers -n hiota keycloak-user -o jsonpath='{.spec.user.credentials[0].value}')
  2. Log into the Solution Management UI using the acquired credentials:

    https://<cluster-fqdn>:30443/hiota/hscp-hiota/solution-control-plane/
    where <cluster-fqdn> is the location where IIoT Core Services is installed.
  3. Navigate to Configuration Registry and replace the JSON password as follows:

    1. Get the JSON token and save it to the file gcr-token.json.
    2. Insert _json_key in the Username field on the Registry tab.
    3. Open the gcr-token.json file to obtain the token.
    4. Copy the token to the Password field on the Registry tab by pasting the password in a single line, and click to save.
    5. Click the Solutions tab, then the Installed sub-tab, to verify the platfom software version.

Results

If the Version field shows the correct platform version number, the control plane is correctly installed. You are now ready to install IIoT Core Services.

Installing IIoT Core Services in a cluster

You can install and configure IIoT Core Services in your cluster using the following instructions.

Start IIoT Core Services installation

This procedure walks you through the first part of the IIoT Core Services installation process.

Before you begin

  • Configure the load balancer to forward traffic to IIoT Core Services.
  • If you are reinstalling IIoT Core Services, first uninstall any current instance of the software on your system to conserve system resources.
  • Complete all prerequisites as described in IIoT Core Services prerequisites.
  • Configure a Kubernetes cluster using one of the options provided in Setting up the Kubernetes cluster. This includes downloading the installer and Docker images and extracting them on the installer node.

Procedure

  1. Log in to the installation node.

  2. Navigate to iiot-installer-release-5.0.0.

  3. Install the necessary libraries:

    export PATH=$PATH:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin
    ln -sf /usr/bin/python3 /usr/bin/python
    pip3 install -r requirements.txt
  4. Start the IIoT Core Services preinstallation and installation process by running the following script:

    ./lei_install.sh

    The software license terms appear.

  5. Read through the license, pressing Enter to scroll down. At the end of the license, enter y(es) at the prompt to agree to install.

    The main installer menu appears. Use this menu to Configure IIoT Core Services.

Configure IIoT Core Services

You can configure the cluster, add users, and configure storage and other settings using the IIoT Core Services installer.

Procedure

  1. From the main installer menu, enter 1 for Node Configuration.

  2. From the Nodes menu, enter 1 for Add Nodes to configure the cluster.

    Enter the requested information:
    FieldDescription
    HostnameEnter the hostname of the node being added.
    IP addressEnter the IP address for the node.
    Role
    • On-premises: Type "master" for all nodes.
    • Cloud: Type "master" for at least one node. Label the remaining nodes "worker."
    Select the option to Return to the Main Menu.
  3. Enter 2 for Load Balancer Configuration to configure the load balancer.

    Enter 1 to Add / Edit Load Balancer.
    FieldDescription
    FQDNEnter the fully qualified domain name (FQDN) of the load balancer.
    HostnameEnter the hostname of the load balancer.
    IP addressEnter the IP address of the load balancer.
    Select the option to Return to the Main Menu.
  4. Enter 3 for Profile Configuration to configure user, deployment, and storage profiles and other settings.

  5. In the Profile Configuration menu, enter 1 for User Profiles to create users.

    Enter 1 to Add User(s) and specify the following information for each new user:
    FieldDescription
    UsernameEnter a username for the new user.

    You can use, modify, or delete the following pre-configured users as needed:

    • Admin username: hiota

      Password: Change11me

    • Technician username: hiota_read

      Password: Change11me

    PasswordEnter a password for the new user.
    EmailEnter the email address for the new user.
    RoleEnter the user role: admin, technician, or operator.
    You must add at least one admin user and one user in another role to gain access to the IIoT Core Services user interface after installation.Select the option to Return to the Main Menu.
  6. Enter 2 for Service Passwords.

    For each service, either press Enter to accept the password that is generated, or type your own password and then press Enter. The passwords you create must have at least eight characters, one lowercase letter, one uppercase letter, and one number. When you create your passwords, copy and store them for easy access. If you forget the generated passwords, you can find them in the Kubernetes dashboard.Select the option to Return to the Main Menu.
  7. Enter 3 for Deployment Profiles and 1 for Edit Profile.

    In the Edit Profile menu, select a deployment profile.
    ProfileDescription
    development (default)Enter 1 to select the development environment and safely test your deployment without affecting the production environment.
    productionEnter 2 to select the production environment.

    Whether you select development or production in this menu, the minimum requirements in Preparing for IIoT Core Services installation apply. Your selection affects the number of replicas and requests and limits for CPU and memory.

    Select the option to Return to the Main Menu.
  8. Enter 4 for Storage Profiles.

    Enter 1 to Edit / Review PVC ReadWriteMode or keep the default setting:
    PVC ReadWriteModeDescription
    ReadWriteOnce (default)

    Mount the volume as read-write by a single node.

    Use this option for VMWare CNS or GCR.

    ReadWriteMany

    Mount the volume as read-only by many nodes.

    Use this option for HSPC.

    For option 2, Edit / Review Service Storage Partitions, enter the storage size for each service needed for your applications.Select the option to Return to the Main Menu.
  9. Enter 5 for Cloud / On Prem & DTR Configuration.

    FieldDescription
    Enable / Disable - Cloud / On Prem InstallEnter true to enable on-premises install or false to enable cloud install.
    View / Edit Core Services Image Registry ConfigurationEnter the FQDN URL, port number, current username and password for the core registry. This information is required even if you select Cloud.
    Select the option Return to Main Menu option.
  10. To enable RBAC, enter 6 for Optional Features, then Edit / Review RBAC.

    The setting to install RBAC is disabled by default. Toggle on or off by entering y(es) or n(o).Select the Return to Main Menu option to return to the Profile Configurations menu, then again Return to Main Menu to return to the start menu.
  11. Enter 4 for Optional Installations.

    The setting to install optional services is turned off by default. Toggle on or off by entering true or false for each service:
    ProfileDescription
    SparkAdd the Spark analytics engine capability for large-scale data processing.
    KnativeDeploy, run, and manage serverless, cloud-native applications with Kubernetes.
    ML ServiceDeploy cloud-based machine learning tools. See table below for Machine learning service configuration options. For more information about Machine learning service and resource requirements, see Machine learning service resource requirements.
    Digital Twin BetaActivate Digital Twin mode and the ability to add digital twin objects that are installed with IIoT Core.
    NoteTo activate this option, you must also select the ML Service option.
    NoteDigital Twin Beta is currently an experimental feature in IIoT Core Services.
    The Machine learning service options include the following:
    ML Service OptionDescription
    NFS_ServerSpecify storage size for file sharing using a Network File System (NFS) server. The default size is 9 GB.
    Model_LifecycleEnter true or false to enable or disable model lifecycle management.
    Model_ManagementEnter true or false to enable or disable model management.
    Model_ServerEnter true or false to enable or disable a model server.
    NotebookEnter true or false to enable or disable Jupyter Notebook.
    RayEnter true or false to enable or disable Ray for Machine learning service scaling.
    Select Return to Optional Installations Menu.
  12. Enter 10 to Validate Configuration Parameters.

  13. Return to the Main Menu and enter 10 to Exit Installer Menu.

    The installer checks if all the parameters are correctly set.

Results

The installation process begins. Let it complete before performing any other action. After successful installation, the information entered in the menu is saved as a Kubernetes secret named hiota-installation-configuration-values-secret in the hiota namespace.

Perform core post installation tasks

You can perform the following post installation tasks to verify that the IIoT Core Services installation is successful.

Sign into the IIoT Core Services UI and verify that IIoT Core Services services are running.

Obtain a CA certificate for IIoT Core Services

IIoT Core Services (also referred to as the appliance) uses a self-owned certificate that is trusted by the operating system, browsers, and other applications. As a result, client services that connect to IIoT Core Services do not automatically trust its certificates. They must be configured with the IIoT Core Services certificate.

Before you begin

The following is required to run the script:

ElementDescription
bashUnix shell (or similar)
curlHTTP(S) utility
jqJSON string processing utility
sedUtility to perform basic text transformations

Procedure

  1. Log in to the installation node.

  2. Navigate to the iiot-installer-release-5.0.0 directory.

  3. Run the script with the following arguments:

    appliance-ca.sh <appliance host address> <user name> [<certificate file path>]
    ArgumentDescription
    appliance host addressThe platform IP address.
    user nameThe name of the admin user authorized to access the certificate.
    certificate file path

    (Optional)

    The file path where the certificate should be saved.

Sign into the IIoT Core Services UI

You can access the IIoT Core Services UI (also called Edge Manager) by signing into its web-based user interface.

The first time you sign in you need the credentials provided by your administrator.

Procedure

  1. Navigate to https://lumada-edge.hiota.<cluster_fqdn>:30443

    where: cluster_fqdn is the fully qualified domain name (FQDN) for the cluster (usually that of the load balancer).
  2. Enter Username and Password.

    If you get an Access Denied message, you do not have the required permissions. Contact your administrator to set up access.The Lumada Edge Manager login screen.

Results

The IIoT Core Services UI opens.

Configuring Modbus

IIoT Core Services includes a Modbus adapter that can be configured for TCP communication between a IIoT Gateway and IIoT Core Services.

Install Modbus

You can perform the following steps to install the Modbus adapter with IIoT Core to connect to your devices.

Procedure

  1. Navigate to the directory where the Modbus installation file is located and extract the contents of the TAR file.

    tar xvf hiota-modbus-lib-5.0.0.tgz

    A new directory is created: Hiota-Modbus-Lib-Installer-5.0.0.

  2. Navigate to the new directory:

    cd Hiota-Modbus-Lib-Installer-5.0.0
  3. Use the following command to enable file executable permissions for the installer script:

    chmod +x Installer.sh
  4. Run the installer:

    ./installer.sh <cluster-fqdn>
  5. Restart the following containers on the IIoT Gateway:

    systemctl restart hiota ​
    
    docker restart mqtt hiota-phoenix hiota-gateway-store-forward modbus-lib modbus-adapter

Results

Modbus is installed and ready to configure.

Configure a Modbus adapter

You can perform the following steps to configure the installed Modbus adapter.

Procedure

  1. Enroll a IIoT Gateway on IIoT Core Services as described in Registering and provisioning an IIoT Gateway using CLI.

  2. Add a Modbus datamap to the enrolled device.

    The information is stored in the subordinate Modbus server in four different tables. Two tables store on/off discrete values (coils) and two store numerical values (registers). The coils and registers each have a read-only table and read-write table.
    Primary tablesData typeAddress rangeNumber of recordsTypeNotes
    Coil1 bit00000-0999910000 (0x270F)Read-WriteThis type of data can be changed by an application.
    Discrete input1 bit10000-1999910000 (0x270F)Read-OnlyThis type of data can be provided by an I/O system.
    Input registers16 bits30000-3999910000 (0x270F)Read-OnlyThis type of data can be provided by an I/O system.
    Holding registers16 bits40000-4999910000 (0x270F)Read-WriteThis type of data can be changed by an application.
  3. From the Data Route tab in the IIoT Core Services UI, create a Modbus route.

    When creating the data route, select HIOTA for the Data Type in the Data Profile section. HIOTA is the IIoT Core Services Common Data Model (CDM). For more information about CDM, see GUID-76D1641E-E676-47B4-A750-EDFFD13BF745.

Results

You can now receive Modbus data using IIoT Core Services.

Example: Configure multiple Modbus connections

With IIoT Core Services, you can configure multiple Modbus servers for each gateway. The following example shows how to configure two gateways with multiple Modbus servers.

GUID-635D365F-F3D5-40A7-B4D5-4BD5B2C3CCFE-low.png

Procedure

  1. Enroll two gateways on IIoT Core Services as described in Install and provision an IIoT Gateway.

  2. In the IIoT Core Services UI, select the Device tab.

  3. Deploy the Modbus adapter on each gateway device.

    Follow the instructions in Deploy protocol adapter configurations on a gateway.
    1. Select one of the gateways to be deployed.
      NoteYou can only select devices that are online and in Ready state.
    2. Select Deploy Deploy Protocol Adapter to view the Adapter Configuration page.
    3. In the Adapter Type list, select Modbus.
    4. Paste your Modbus adapter configuration YAML into the Insert Adapter Configuration File text box.

      Example:

      1   - name: "custom-application-1"
      2  tags:
      3    - name: "velocity"
      4      type: "int16"
      5      slaveAddr: 0x00; 
      6      tableName: HoldingRegister
      7      startAddr: 0x00
      8      isBigEndian: true
      9    - name: "temperature"
      10      type: "int16"
      11      slaveAddr: 0x00
      12      tableName: HoldingRegister
      13      startAddr: 0x01
      14      isBigEndian: true
      15    - name: "a_03_int8"
      16      type: "int8"
      17      slaveAddr: 0x00
      18      tableName: HoldingRegister
      19      startAddr: 0x02
      20      isBigEndian: true
      21    - name: "a_04_uint8"
      22      type: "uint8"
      23      slaveAddr: 0x00
      24      tableName: HoldingRegister
      25      startAddr: 0x03
      26      isBigEndian: true
      27    - name: "a_05_int32"
      28      type: "int32"
      29      slaveAddr: 0x00
      30      tableName: HoldingRegister
      31      startAddr: 0x04
      32      isBigEndian: true
      33    - name: "a_06_float"
      34      type: "float"
      35      slaveAddr: 0x00
      36      tableName: HoldingRegister
      37      startAddr: 0x06
      38      isBigEndian: true
      
      FieldDescription
      nameTag name.
      typeData type: bool, int8, uint8, int16, uint16, int32, uint32, int64, uint64, float, double, string.
      slaveAddrThe Modbus device addresses a specific subordinate device by placing the 8-bit subordinate address in the address field of the message (RTU mode). The address field of the message frame contains two characters (in ASCII mode), or 8 binary bits (in RTU mode). Valid addresses are from 1-247. Subordinate address 0 is used for broadcasts.
      tableNameName of primary table. The value is found in {‘Coils’, ‘DiscreteInput’, ‘HoldingRegisters’, ‘InputRegisters’}.
      startAddrStart address for tableName. The range is 0-9999.
      isBigEndianBoolean. Modbus is a “big-endian” protocol, that is, the more significant byte of a 16-bit value is sent before the less significant byte. In some cases, however, 32-bit and 64-bit values are treated as being composed of 16-bit words, and transfer the words in "little-endian" order. For example, the 32-bit value 0x12345678 would be transferred as 0x56 0x78 0x12 0x34. You can chose the little-endian mode when isBigEndian is set to false.
    5. Click Deploy.
  4. Select the Data Route tab to create a data route for each Modbus connection.

    NoteGeneral instructions for how to create a data route are found in Creating a data route.
    1. Click Create Data Route.

      The Create Data Route page opens.

    2. Enter a Name for the data route.
    3. Select the Asset that you are collecting data from.
    4. For Device Type, select Gateway.
    5. For Device, select the name of the gateway.
    6. Enter a Trace ID or keep the default Trace ID that is based on the asset name.
    7. For Data Type, select HIOTA.
    8. In the Data Source section, select Modbus from the Protocol field and the corresponding Hostname / IP Address and Port.
    9. In the Data Destinations section, add the data destination details for one or more data destinations.
    10. Click Save and Deploy.
    Repeat for the remaining data routes.

Results

When the five data routes have been successfully deployed, the Status column in the data route inventory shows Deployed (Connected) for each data route.

Shut down a Kubernetes node in a three-node cluster

You can perform a graceful shutdown of a cluster node for the purpose of node maintenance, troubleshooting, or other interventions.

Procedure

  1. Shut down and drain the cluster node by running the following command:

    kubectl drain <nodename> --ignore-daemonsets --delete-local-data
    NoteDraining safely evicts or deletes all pods except mirror pods to make them unschedulable in preparation for maintenance. The drain function waits for graceful termination. Do not operate on the node until the command completes.
  2. Wait for the drain to complete.

    If a pod is stuck in Init state, even after waiting eight minutes, delete the pod and wait a few minutes while the pod comes online. Run the following command to delete the pod:

    kubectl delete pod -n <namespace> <podname>

    If a pod is stuck in the Terminating state after a node is drained, run the following command to force delete the pod.

    Run the following command:

    kubectl delete pod -n <namespace> <podname> --grace-period=0 --force
  3. Confirm that all pods are running on the other two nodes by running the following command:

    kubectl get pods --all-namespaces -o wide

    Wait eight minutes for a pod to be up and running after it has been rescheduled to another node.

  4. Verify volume attachments and ensure that there are no volume attachments left on the drained node by running the following command:

    kubectl get volumeattachments -o custom-columns=VANAME:metadata.name,NODENAME:spec.nodeName

    Sample output:

    VANAME NODENAME
    csi-0232c4c79c3205b45c15eb2a60e61878df9ef6e546a8d98c7fc2c49619c2af7d NodeB
    csi-3fe0b6b87271201ad9b4f065a49894ac3ee5c8ed67f17ad2766177d58d5092d7NodeC
    csi-4bb22d7f2fcf9f59faba8560cbc37384127bcab09f381dda8ea65f31675a34b7 NodeB
    csi-6a02010d32147f167126f16b1baf8f56fff447df29b6446820cb443fb42199af NodeA
  5. If you still see volume attachments with NODENAME = NodeA (the drained node), delete the volumeattachment with the following command:

    kubectl delete volumeattachments csi-xxxx
  6. Repeat step 5 to delete all volume attachments left in the node you drained.

  7. Verify that there is nothing in the multipath directory by running the following command on NodeA (the drained node):

    multipath -ll
  8. Restart NodeA (the drained node) to put it back in service using the following command.

    kubectl uncordon <nodename>

Uninstall IIoT Core Services

You can uninstall IIoT Core Services from the master node.

Before you begin

If IIoT Core Services is installed on vCenter vSphere, do not delete the VM before uninstalling.

Procedure

  1. Log in as a root user on the installation node.

  2. Navigate to the product installation directory:

    cd iiot-installer-release-5.0.0
  3. Run the uninstall script:

    ./lei_uninstall.sh
  4. Select Y(es) to uninstall or N(o) to cancel.

    The uninstall script completes.
  5. Delete the folder iiot-installer-release-5.0.0.

Uninstall the platform components

After you have uninstalled IIoT Core Services, you can uninstall the IIoT Core platform components.

Procedure

  1. Log in as a root user on the installation node.

  2. Navigate to the product installation directory:

    cd <installation_dir>/Foundry-Control-Plane-2.3.0/bin
  3. Run the uninstall scripts:

    ./uninstall-control-plane.sh -n hiota
    ./uninstall-control-plane.sh -F
  4. Select Y(es) to uninstall or N(o) to cancel.

    The uninstall script completes.