Installing IBM Edge Computing for Devices infrastructure

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

Installation summary

Sizing

Recommendations vary depending on hardware and use case. The suggested values are for total resources available across worker nodes. The resources can be spread across multiple worker nodes. At least two worker nodes are required. These resources are in addition to IBM Cloud Private sizing requirements.

Prerequisites

Note: You are responsible for backing up or restoring your databases.

Installation process

Perform these steps on the host that was set up in the previous section:

  1. Set the ICP_HOSTNAME environment variable and add it to /etc/hosts with the IP address of the IBM Cloud Private cluster:

     export ICP_HOSTNAME=<cluster name>.icp
 sudo echo "<cluster-ip> $ICP_HOSTNAME" >> /etc/hosts

  2. Ensure that you are connected to your IBM Cloud Private Kubernetes cluster with cluster administrator privileges. Select the kube-system as the namespace when you are logging in:

     export ICP_URL="https://$ICP_HOSTNAME:<icp-port-number>"
 cloudctl login -a $ICP_URL -u <your-icp-admin-user> -p <your-icp-admin-password> -n kube-system --skip-ssl-validation

  3. Configure the Docker CLI to connect to the IBM Cloud Private private image registry. For more information, see Configuring authentication for the Docker CLI Opens in a new tab.

  4. Locate the IBM Edge Computing for Devices installation content compressed file that was downloaded from IBM Passport Advantage. Unpack that compressed file and find the file: ibm-edge-computing-x86_64-3.2.1.1/ibm-edge-computing-prod-catalog-archive-3.2.1.1.tgz. Note: Keep the compressed file from IBM Passport Advantage because you will need it again when you install edge devices.

  5. Load the archive content into IBM Edge Computing for Devices:

     cloudctl catalog load-archive --archive ibm-edge-computing-prod-catalog-archive-3.2.1.1.tgz --registry $ICP_HOSTNAME:8500/kube-system --username <your-icp-admin-user> --password <your-icp-admin-password>

    Note: IBM Edge Computing for Devices supports only a CLI driven installation for this release. This offering is not in the IBM Edge Computing for IBM Cloud Private management console catalog.

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

     tar -O -zxvf ibm-edge-computing-prod-catalog-archive-3.2.1.1.tgz charts/ibm-edge-computing-prod-3.2.2.tgz | tar -zxvf -
 cd ibm-edge-computing-prod

  7. Follow the steps in the README.md file.

    This script installs the mentioned infrastructure components and runs a final verification.

Post installation configuration

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

  1. 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 locally:

    • 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 /

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

     export EXCHANGE_ROOT_PASS=$(kubectl -n kube-system get secret edge-computing -o jsonpath="{.data.exchange-config}" | base64 --decode | jq -r .api.root.password)
 export HZN_EXCHANGE_URL=$ICP_URL/ec-exchange/v1
 export HZN_EXCHANGE_USER_AUTH="root/root:$EXCHANGE_ROOT_PASS"
 export HZN_ORG_ID=IBM

  3. Run the following command to trust the IBM Cloud Private root CA:

     kubectl --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

  4. 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>

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

     hzn exchange status

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

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

  7. Run the following commands to view some of the services and policies that were created in the IBM Edge Computing 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

  8. If not already setup, create an LDAP connection by using the IBM Cloud Private 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 for Devices CLI. For more information about LDAP, see Configuring LDAP connection Opens in a new tab.

Set up an edge device to verify that it can communicate to IBM Edge Computing for Devices infrastructure. Follow the steps in Preparing an edge device, including the step in Install the Horizon agent on your edge device and register it with the hello world example.

Gather the necessary information and files

The steps in this section only need to be performed once, but must be performed on an x86 host (Linux, macOS, or Windows). If your edge device is a different architecture (for example arm or arm64), then run the steps in this section on an x86 host and copy the resulting files to your edge device.

  1. Install the IBM Cloud Private command line interface (cloudctl) and the Kubernetes command line interface (kubectl) by following the steps in Installing cloudctl Opens in a new tab.

    Alternatively, you can install kubectl using your package manager. For more information about installing kubectl with your package manager, see Install and set up kubectl Opens in a new tab.

  2. After cloudctl is installed, ask your IBM Cloud Private cluster administrator for the IBM Cloud Private URL, username, and password. Use these to login. (This login also configures kubectl.)

    export ICP_URL=<icp-url>
cloudctl login -a $ICP_URL -u <your-icp-user> -p <your-icp-password> -n kube-public --skip-ssl-validation

  3. Query the IBM Cloud Private cluster name and note it for future steps:

    kubectl get configmap -n kube-public ibmcloud-cluster-info -o jsonpath="{.data.cluster_name}" && echo

  4. Create a IBM Cloud Private platform API key to use as your credentials when running Horizon hzn commands:

    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.

  5. With the information from the previous steps, create agent-install.cfg:

    cat << EndOfContent > agent-install.cfg
HZN_EXCHANGE_URL=$ICP_URL/ec-exchange/v1/
HZN_FSS_CSSURL=$ICP_URL/ec-css/
HZN_ORG_ID=<icp-cluster-name>
HZN_EXCHANGE_USER_AUTH=iamapikey:<api-key>
HZN_EXCHANGE_PATTERN=IBM/pattern-ibm.helloworld
EndOfContent

  6. Get the IBM Cloud Private self-signed certificate:

    kubectl -n kube-public get secret ibmcloud-cluster-ca-cert -o jsonpath="{.data['ca\.crt']}" | base64 --decode > agent-install.crt

  7. Locate the IBM Edge Computing for Devices installation content compressed file ibm-edge-computing-x86_64-3.2.1.1.tar.gz that was downloaded from IBM Passport Advantage. Extract from it the agent packages for your edge device type. Choose the one bullet below that applies to your edge device architecture and run the corresponding command.

    1. If your edge device is 32-bit ARM (for example, Raspberry Pi):

      tar --strip-components 6 -zxvf ibm-edge-computing-x86_64-3.2.1.1.tar.gz ibm-edge-computing-x86_64-3.2.1.1/horizon-edge-packages/linux/raspbian/stretch/armhf

    2. If your edge device is 64-bit ARM (for example, NVIDIA Jetson Nano, TX1, or TX2):

      tar --strip-components 6 -zxvf ibm-edge-computing-x86_64-3.2.1.1.tar.gz ibm-edge-computing-x86_64-3.2.1.1/horizon-edge-packages/linux/ubuntu/bionic/arm64

      Note: you can use xenial instead if bionic for the older version of Ubuntu.

    3. If your edge device is x86_64 Linux:

      tar --strip-components 6 -zxvf ibm-edge-computing-x86_64-3.2.1.1.tar.gz ibm-edge-computing-x86_64-3.2.1.1/horizon-edge-packages/linux/ubuntu/bionic/amd64

      Note: you can use xenial instead if bionic for the older version of Ubuntu.

    4. If your edge device is macOS:

      tar --strip-components 3 -zxvf ibm-edge-computing-x86_64-3.2.1.1.tar.gz ibm-edge-computing-x86_64-3.2.1.1/horizon-edge-packages/macos

  8. If this is not your edge device, this commmand lists the gathered files that you must copy to your edge device once it has an operating system:

    ls agent-install.cfg agent-install.crt *horizon*

Uninstalling

Return to the location of the README.md file that is used during installation and run the uninstall script that is provided to automate the uninstall tasks. The major steps that are covered by the script are uninstalling helm charts and the removal of secrets. First, login to the cluster as a cluster administrator by using cloudctl. Then, run this command:

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

Note: By default, local databases are used. If you have configured remote databases, when prompted with the database backup option, leave the response blank to skip the backup attempt (remote database content will not be deleted on an uninstall).