Installing IBM Edge Computing Manager for Devices infrastructure

IBM Edge Computing Manager for Devices installation process takes you through the following high-level installation and configuration steps:

Installation summary

Sizing

This sizing information is for IBM Edge Computing Manager for Devices services only, and is above and beyond the sizing recommendations for IBM Edge Computing Manager shared components which you can find documented here.

Database storage requirements

Compute requirements

The services leveraging Kubernetes compute resources will be scheduled across available worker nodes. At least three worker nodes is recommended.

Prerequisites

Note: By default, local development databases are provisioned as part of the chart installation. See the README.md for guidance about provisioning your own databases. You are responsible for backing up or restoring your databases.

Installation process

  1. Set the CLUSTER_URL environment variable, this value can be obtained from the output of the Management Hub install:

     export CLUSTER_URL=<CLUSTER_URL>

    Alternatively, after connecting to your cluster with oc login you can run:

     export CLUSTER_URL=https://$(oc get routes icp-console -o jsonpath='{.spec.host}' -n kube-system)

  2. Connect to your cluster with cluster administrator privileges, selecting kube-system as the namespace and fill in the password you defined in the config.yaml during the Management Hub install:

     cloudctl login -a $CLUSTER_URL -u admin -p <your-icp-admin-password> -n kube-system --skip-ssl-validation

  3. Define the image registry host, configure the Docker CLI to trust the self-signed certificate:

     export REGISTRY_HOST=$(oc get routes -n openshift-image-registry default-route -o jsonpath='{.spec.host}')

    For macOS:

    1. Trust the certificate

      mkdir -p ~/.docker/certs.d/$REGISTRY_HOST && \
echo | openssl s_client -showcerts -connect $REGISTRY_HOST:443 2>/dev/null | openssl x509 -outform PEM > ~/.docker/certs.d/$REGISTRY_HOST/ca.crt && \
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain ~/.docker/certs.d/$REGISTRY_HOST/ca.crt

    2. Restart the Docker service from the menu bar

    For Ubuntu:

    1. Trust the certificate

      mkdir /etc/docker/certs.d/$REGISTRY_HOST && \
echo | openssl s_client -showcerts -connect $REGISTRY_HOST:443 2>/dev/null | openssl x509 -outform PEM > /etc/docker/certs.d/$REGISTRY_HOST/ca.crt && \
service docker restart

  4. Login to the OpenShift Container Platform 4.2 image registry:

       docker login $REGISTRY_HOST -u $(oc whoami) -p $(oc whoami -t)

  5. Unpack the IBM Edge Computing Manager for Devices installation compressed file that was downloaded from IBM Passport Advantage:

     tar -zxvf ibm-ecm-4.0.0-x86_64.tar.gz && \
 cd ibm-ecm-4.0.0-x86_64

  6. Load the archive content into the catalog, and the images into the registry's ibmcom namespace:

     cloudctl catalog load-archive --archive ibm-ecm-prod-catalog-archive-4.0.0.tgz --registry $REGISTRY_HOST/ibmcom

    Note: IBM Edge Computing Manager for Devices supports only a CLI driven installation, installation from the catalog is not supported for this release.

  7. Extract the chart compressed file content to the current directory and move into to the directory created:

     tar -O -zxvf ibm-ecm-prod-catalog-archive-4.0.0.tgz charts/ibm-ecm-prod-4.0.0.tgz | tar -zxvf - && \
 cd ibm-ecm-prod

  8. Define a default storage class if one isn't set:

    # oc get storageclass
NAME                                 PROVISIONER                     AGE
rook-ceph-block-internal             rook-ceph.rbd.csi.ceph.com      8h
rook-ceph-cephfs-internal (default)  rook-ceph.cephfs.csi.ceph.com   8h
rook-ceph-delete-bucket-internal     ceph.rook.io/bucket             8h

    If you do not see a line with the (default) string above, tag your preferred default storage with:

    oc patch storageclass <PREFERRED_DEFAULT_STORAGE_CLASS_NAME> -p '{"metadata": {"annotations": {"storageclass.kubernetes.io/is-default-class": "true"}}}'

  9. Read and consider your configuration options, then follow the Installing the Chart section in the README.md.

    The script installs the infrastructure components mentioned in the Installation summary section above, runs installation verification, and then refers you back to the Post installation configuration section below.

Post installation configuration

Run the following commands from the same host where you ran the initial installation:

  1. Refer to steps 1 and 2 in the above Installation process section above to login to your cluster

  2. Install the hzn CLI with either the Ubuntu Linux or macOS package installers that are found under horizon-edge-packages in the appropriate OS/ARCH directory from the compressed content extracted in step 5 of the Installation process above:

    • Ubuntu Linux example:

      sudo dpkg -i horizon-edge-packages/linux/ubuntu/bionic/amd64/horizon-cli*.deb

    • macOS example:

      sudo installer -pkg horizon-edge-packages/macos/horizon-cli-*.pkg -target /

  3. Export the following variables that are needed for the next steps:

     export EXCHANGE_ROOT_PASS=$(oc -n kube-system get secret edge-computing -o jsonpath="{.data.exchange-config}" | base64 --decode | jq -r .api.root.password)
 export HZN_EXCHANGE_URL=https://$(oc get routes icp-console -o jsonpath='{.spec.host}' -n kube-system)/ec-exchange/v1
 export HZN_EXCHANGE_USER_AUTH="root/root:$EXCHANGE_ROOT_PASS"
 export HZN_ORG_ID=IBM

  4. Run the following command to trust the OpenShift Container Platform 4.2 Certificate Authority:

     oc --namespace kube-system get secret cluster-ca-cert -o jsonpath="{.data['tls\.crt']}" | base64 --decode > /tmp/icp-ca.crt

    • Ubuntu Linux example:

      sudo cp /tmp/icp-ca.crt /usr/local/share/ca-certificates && sudo update-ca-certificates

    • macOS example:

      sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain /tmp/icp-ca.crt

  5. Run the following command to create a signing key pair. For more information, see Step 5 in Preparing to create an edge service.

     hzn key create <company-name> <owner@email>

  6. Run the following command to confirm that the setup can communicate with the IBM Edge Computing Manager for Devices exchange API:

     hzn exchange status

  7. Populate sample edge services by running the following command:

     curl https://raw.githubusercontent.com/open-horizon/examples/v4.0/tools/exchangePublishScript.sh | bash

  8. Run the following commands to view some of the services and policies that were created in the IBM Edge Computing Manager for Devices exchange:

     hzn exchange service list IBM/
 hzn exchange pattern list IBM/
 hzn exchange service listpolicy IBM/ibm.helloworld_1.0.0_amd64
 hzn exchange service listpolicy IBM/ibm.cpu2evtstreams_1.4.2_amd64

  9. If not already setup, create an LDAP connection by using the OpenShift Container Platform 4.2 management console. After you establish an LDAP connection, create a team, grant that team access to any namespace, and add users to that team. This grants individual users the permission to create API keys.

    Note: API-keys are used for authentication with the IBM Edge Computing Manager for Devices CLI. For more information about LDAP, see Configuring LDAP connection Opens in a new tab.

Gather the necessary information and files for edge devices

Several files will be needed to install the IBM Edge Computing Manager for Devices agent on your edge devices and register them with IBM Edge Computing Manager for Devices. This section will guide you through gathering those files into a tar file, which can then be used on each of your edge devices.

It is assumed that you have already installed the cloudctl and kubectl commands, and extracted ibm-edge-computing-4.0.0-x86_64.tar.gz from the installation content, as described earlier in this page.

  1. Refer to steps 1 and 2 in the Installation process section above to set the following environment variables:

    export CLUSTER_URL=<cluster-url>
export USER=<your-icp-admin-user>
export PW=<your-icp-admin-password>

  2. Download the latest version of edgeDeviceFiles.sh:

    curl -O https://raw.githubusercontent.com/open-horizon/examples/v4.0/tools/edgeDeviceFiles.sh
chmod +x edgeDeviceFiles.sh

  3. Run the edgeDeviceFiles.sh script to gather the necessary files:

    ./edgeDeviceFiles.sh <edge-device-type> -t

    Command arguments:

    • Supported values: 32-bit-ARM , 64-bit-ARM, x86_64-Linux, or macOS
    • -t: create an agentInstallFiles-<edge-device-type>.tar.gz file containing all gathered files. If this flag is not set, the gathered files are placed in the current directory.
    • -k: create a new API key named $USER-Edge-Device-API-Key. If this flag is not set, the existing api keys are checked for one named $USER-Edge-Device-API-Key and creation is skipped if the key already exists.
    • -d : when installing on 64-bit-ARM or x86_64-Linux, you can specify -d xenial for the older version of Ubuntu, instead of the default bionic. When installing on 32-bit-ARM you can specify -d stretch instead of the default buster. The -d flag is ignored with macOS.
    • -f : specify a directory to move gathered files to. If the directory does not exist, it will be created. Default is current directory

  4. The command in the previous step will create a file called agentInstallFiles-<edge-device-type>.tar.gz. If you have additional types of edge devices (different architectures), repeat the previous step for each type.

  5. Take note of the API key that was created and displayed by the edgeDeviceFiles.sh command.

  6. Now that you are logged in via cloudctl, if you need to create additional API keys for users to use with the Horizon hzn command:

    cloudctl iam api-key-create "<choose-an-api-key-name>" -d "<choose-an-api-key-description>"

    In the output of the command look for the key value in the line that starts with API Key and save the key value for future use.

  7. When you are ready to set up edge devices, follow Getting started using IBM Edge Computing Manager for Devices.

Uninstalling

Note: By default, local databases are configured, in this case uninstallation will delete ALL persistent data. Ensure you have taken backups of all required persistent data (backup instructions are documented in the README) before running the uninstallation script. If you have configured remote databases, that data will not be deleted on an uninstall, and must be manually removed if desired.

Return to the location of the chart unpacked as part of installation and run the provided uninstall script. This script will uninstall the helm release and all associated resources. First, login to the cluster as a cluster administrator by using cloudctl, and then run:

ibm_cloud_pak/pak_extensions/uninstall/uninstall-edge-computing.sh <cluster-name>