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
- Prerequisites
- Installation process
- Post installation configuration
- Gather the necessary information and files
- Uninstalling
Installation summary
- Deploy the following infrastructure components:
- IBM Edge Computing for Devices exchange API.
- IBM Edge Computing for Devices agbot.
- IBM Edge Computing for Devices Cloud Sync Service (CSS).
- IBM Edge Computing for Devices user interface.
- Verify that the installation was a success.
- Populate sample edge services.
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.
-
Minimum required resources:
- 8 GB RAM
- 8 CPU cores
-
Recommended resources:
- 16 GB RAM+
- 16 CPU cores+
Prerequisites
- IBM Cloud Private 3.2.1 and IBM Multicloud Manager 3.2.1 installation completed.
- For how to install IBM Cloud Private, see Installing .
-
An Ubuntu Linux or macOS host that can ssh as root into the IBM Cloud Private Kubernetes master node. Install the following packages on this host:
- Kubernetes CLI (kubectl) version 1.13.1 or higher
- Helm CLI (helm) version 2.9.1 or higher
- IBM Cloud Private CLI (cloudctl)
jq
git
docker
(version 18.06.01 or later)make
-
Provision three database instances to store the IBM Edge Computing for Devices component data:
-
PostgreSQL to store Exchange and AgBot data:
- Two separate instances, each with a minimum of 10 GB of storage.
- For production use, these instances should be highly available. The instance that stores the exchange data must support a minimum of 100 connections, and the instance that stores agbot data must support a minimum of 20 connections.
-
MongoDB to store Cloud Sync Service data:
- One instance with a minimum of 50 GB of storage. Note: The required size depends on the size and number of edge service models and files that you store and use.
- For production use, this instance should be highly available.
-
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:
-
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
-
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
-
Configure the Docker CLI to connect to the IBM Cloud Private private image registry. For more information, see Configuring authentication for the Docker CLI .
-
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.
-
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.
-
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
-
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:
-
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 /
-
-
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
-
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
-
-
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>
-
Run the following command to confirm that the setup can communicate with the IBM Edge Computing for Devices exchange API:
hzn exchange status
-
Populate sample edge services by running the following command:
curl https://raw.githubusercontent.com/open-horizon/examples/v3.2.1/tools/exchangePublishScript.sh | bash
-
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
-
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 .
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.
-
Install the IBM Cloud Private command line interface (
cloudctl
) and the Kubernetes command line interface (kubectl
) by following the steps in Installing cloudctl .Alternatively, you can install
kubectl
using your package manager. For more information about installingkubectl
with your package manager, see Install and set up kubectl . -
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 configureskubectl
.)export ICP_URL=<icp-url> cloudctl login -a $ICP_URL -u <your-icp-user> -p <your-icp-password> -n kube-public --skip-ssl-validation
-
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
-
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.
-
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
-
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
-
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.-
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
-
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 ifbionic
for the older version of Ubuntu. -
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 ifbionic
for the older version of Ubuntu. -
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
-
-
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).