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
- Prerequisites
- Installation process
- Post installation configuration
- Gather the necessary information and files
- Uninstalling
Installation summary
- Deploy the following infrastructure components:
- IBM Edge Computing Manager for Devices exchange API.
- IBM Edge Computing Manager for Devices agbot.
- IBM Edge Computing Manager for Devices Cloud Sync Service (CSS).
- IBM Edge Computing Manager for Devices user interface.
- Verify that the installation was a success.
- Populate sample edge services.
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
- PostgreSQL Exchange
- 10GB default
- PostgreSQL AgBot
- 10GB default
- MongoDB Cloud Sync Service
- 50GB default
Compute requirements
The services leveraging Kubernetes compute resources will be scheduled across available worker nodes. At least three worker nodes is recommended.
-
These configuration changes will support up to 10,000 edge devices:
exchange: replicaCount: 5 dbPool: 18 cache: idsMaxSize: 11000 resources: limits: cpu: 5
Note: Directions for making these changes are described in the Advanced Configuration section in the README.md.
-
The default configuration will support up to 4,000 edge devices, the chart totals for default compute resources are:
- Requests
- Less than 5GB of RAM
- Less than 1 CPU
- Limits
- 18GB of RAM
- 18 CPU's
- Requests
Prerequisites
- Install IBM Edge Computing Manager shared components
- A macOS or Ubuntu Linux host
- OpenShift client CLI (oc) 4.2
- jq Download
- git
- docker 1.13+
- make
-
The following CLI's, which can be obtained from your Management Hub cluster installation at
https://<CLUSTER_URL_HOST>/common-nav/cli
Note: You may have to navigate to the above URL twice as unauthenticated access re-directs navigation to a welcome page
- Kubernetes CLI (kubectl)
- Helm CLI (helm)
- IBM Cloud Pak CLI (cloudctl)
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
-
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)
-
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
-
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:
-
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
-
Restart the Docker service from the menu bar
For Ubuntu:
-
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
-
-
Login to the OpenShift Container Platform 4.2 image registry:
docker login $REGISTRY_HOST -u $(oc whoami) -p $(oc whoami -t)
-
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
-
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.
-
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
-
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"}}}'
-
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:
- Refer to steps 1 and 2 in the above Installation process section above to login to your cluster
-
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 /
-
-
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
-
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
-
-
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 Manager for Devices exchange API:
hzn exchange status
-
Populate sample edge services by running the following command:
curl https://raw.githubusercontent.com/open-horizon/examples/v4.0/tools/exchangePublishScript.sh | bash
-
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
-
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 .
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.
-
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>
-
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
-
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
- Supported
-
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.
-
Take note of the API key that was created and displayed by the edgeDeviceFiles.sh command.
-
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.
-
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>