Install and run the Spatial Analysis container (preview)

Azure Stack Edge is a hardware-as-a-service solution and an AI-enabled edge computing device with network data transfer capabilities. For detailed preparation and setup instructions, see the Azure Stack Edge documentation.

Minimum hardware requirements

• 4 GB of system RAM
• 4 GB of GPU RAM
• 8 core CPU
• One NVIDIA CUDA Compute Capable GPU 6.0 or higher (for example, NVIDIA Tesla T4, A2, 1080Ti, or 2080Ti)
• 20 GB of HDD space

Recommended hardware

• 32 GB of system RAM
• 16 GB of GPU RAM
• 8 core CPU
• Two NVIDIA CUDA Compute Capable GPUs 6.0 or higher (for example, NVIDIA Tesla T4, A2, 1080Ti, or 2080Ti)
• 50 GB of SSD space

In this article, you'll download and install the following software packages. The host computer must be able to run the following (see below for instructions):

• NVIDIA graphics drivers and NVIDIA CUDA Toolkit. The minimum GPU driver version is 460 with CUDA 11.1.
• Configurations for NVIDIA MPS (Multi-Process Service).
• Docker CE and NVIDIA-Docker2
• Azure IoT Edge runtime.

In our example, we utilize an NCv3 series VM that has one v100 GPU.

Configure compute on the Azure Stack Edge portal

Spatial Analysis uses the compute features of the Azure Stack Edge to run an AI solution. To enable the compute features, make sure that:

• You've connected and activated your Azure Stack Edge device.
• You have a Windows client system running PowerShell 5.0 or later, to access the device.
• To deploy a Kubernetes cluster, you need to configure your Azure Stack Edge device via the Local UI on the Azure portal:
  1. Enable the compute feature on your Azure Stack Edge device. To enable compute, go to the Compute page in the web interface for your device.
  2. Select a network interface that you want to enable for compute, then select Enable. This creates a virtual switch on your device, on that network interface.
  3. Leave the Kubernetes test node IP addresses and the Kubernetes external services IP addresses blank.
  4. Select Apply. This operation may take about two minutes.

Set up Azure Stack Edge role and create an IoT Hub resource

In the Azure portal, navigate to your Azure Stack Edge resource. On the Overview page or navigation list, select the Edge compute Get started button. In the Configure Edge compute tile, select Configure.

In the Configure Edge compute page, choose an existing IoT Hub, or choose to create a new one. By default, a Standard (S1) pricing tier is used to create an IoT Hub resource. To use a free tier IoT Hub resource, create one and then select it. The IoT Hub resource uses the same subscription and resource group that is used by the Azure Stack Edge resource

Select Create. The IoT Hub resource creation may take a couple of minutes. After the IoT Hub resource is created, the Configure Edge compute tile will update to show the new configuration. To confirm that the Edge compute role has been configured, select View config on the Configure compute tile.

When the Edge compute role is set up on the Edge device, it creates two devices: an IoT device and an IoT Edge device. Both devices can be viewed in the IoT Hub resource. The Azure IoT Edge Runtime will already be running on the IoT Edge device.

Enable MPS on Azure Stack Edge

Follow these steps to remotely connect from a Windows client.

1. Run a Windows PowerShell session as an administrator.

2. Make sure that the Windows Remote Management service is running on your client. At the command prompt, type:

   winrm quickconfig
   

   For more information, see Installation and configuration for Windows Remote Management.

3. Assign a variable to the connection string used in the hosts file.

   $Name = "<Node serial number>.<DNS domain of the device>"
   

   Replace <Node serial number> and <DNS domain of the device> with the node serial number and DNS domain of your device. You can get the values for node serial number from the Certificates page and DNS domain from the Device page in the local web UI of your device.

4. To add this connection string for your device to the client’s trusted hosts list, type the following command:

   Set-Item WSMan:\localhost\Client\TrustedHosts $Name -Concatenate -Force
   

5. Start a Windows PowerShell session on the device:

   Enter-PSSession -ComputerName $Name -Credential ~\EdgeUser -ConfigurationName Minishell -UseSSL
   

   If you see an error related to trust relationship, then check if the signing chain of the node certificate uploaded to your device is also installed on the client accessing your device.

6. Provide the password when prompted. Use the same password that is used to sign into the local web UI. The default local web UI password is Password1. When you successfully connect to the device using remote PowerShell, you see the following sample output:

   Windows PowerShell
   Copyright (C) Microsoft Corporation. All rights reserved.
   
   PS C:\WINDOWS\system32> winrm quickconfig
   WinRM service is already running on this machine.
   PS C:\WINDOWS\system32> $Name = "1HXQG13.wdshcsso.com"
   PS C:\WINDOWS\system32> Set-Item WSMan:\localhost\Client\TrustedHosts $Name -Concatenate -Force
   PS C:\WINDOWS\system32> Enter-PSSession -ComputerName $Name -Credential ~\EdgeUser -ConfigurationName Minishell -UseSSL
   
   WARNING: The Windows PowerShell interface of your device is intended to be used only for the initial network configuration. Please engage Microsoft Support if you need to access this interface to troubleshoot any potential issues you may be experiencing. Changes made through this interface without involving Microsoft Support could result in an unsupported configuration.
   [1HXQG13.wdshcsso.com]: PS>
   

Follow these instructions if your host computer isn't an Azure Stack Edge device.

Install NVIDIA CUDA Toolkit and Nvidia graphics drivers on the host computer

Use the following bash script to install the required Nvidia graphics drivers, and CUDA Toolkit.

wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu1804/x86_64/cuda-ubuntu1804.pin
sudo mv cuda-ubuntu1804.pin /etc/apt/preferences.d/cuda-repository-pin-600
sudo apt-key adv --fetch-keys https://developer.download.nvidia.com/compute/cuda/repos/ubuntu1804/x86_64/3bf863cc.pub
sudo add-apt-repository "deb http://developer.download.nvidia.com/compute/cuda/repos/ubuntu1804/x86_64/ /"
sudo apt-get update
sudo apt-get -y install cuda

Reboot the machine, and run the following command.

nvidia-smi

You should see the following output.

Install Docker CE and nvidia-docker2 on the host computer

Install Docker CE on the host computer.

sudo apt-get update
sudo apt-get install -y apt-transport-https ca-certificates curl gnupg-agent software-properties-common
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io

Install the nvidia-docker-2 software package.

distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list
sudo apt-get update
sudo apt-get install -y docker-ce nvidia-docker2
sudo systemctl restart docker

Enable NVIDIA MPS on the host computer

For best performance and utilization, configure the host computer's GPU(s) for NVIDIA Multiprocess Service (MPS). Run the MPS instructions from a terminal window on the host computer.

# Set GPU(s) compute mode to EXCLUSIVE_PROCESS
sudo nvidia-smi --compute-mode=EXCLUSIVE_PROCESS

# Cronjob for setting GPU(s) compute mode to EXCLUSIVE_PROCESS on boot
echo "SHELL=/bin/bash" > /tmp/nvidia-mps-cronjob
echo "PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin" >> /tmp/nvidia-mps-cronjob
echo "@reboot   root    nvidia-smi --compute-mode=EXCLUSIVE_PROCESS" >> /tmp/nvidia-mps-cronjob

sudo chown root:root /tmp/nvidia-mps-cronjob
sudo mv /tmp/nvidia-mps-cronjob /etc/cron.d/

# Service entry for automatically starting MPS control daemon
echo "[Unit]" > /tmp/nvidia-mps.service
echo "Description=NVIDIA MPS control service" >> /tmp/nvidia-mps.service
echo "After=cron.service" >> /tmp/nvidia-mps.service
echo "" >> /tmp/nvidia-mps.service
echo "[Service]" >> /tmp/nvidia-mps.service
echo "Restart=on-failure" >> /tmp/nvidia-mps.service
echo "ExecStart=/usr/bin/nvidia-cuda-mps-control -f" >> /tmp/nvidia-mps.service
echo "" >> /tmp/nvidia-mps.service
echo "[Install]" >> /tmp/nvidia-mps.service
echo "WantedBy=multi-user.target" >> /tmp/nvidia-mps.service

sudo chown root:root /tmp/nvidia-mps.service
sudo mv /tmp/nvidia-mps.service /etc/systemd/system/

sudo systemctl --now enable nvidia-mps.service

Configure Azure IoT Edge on the host computer

To deploy the Spatial Analysis container on the host computer, create an instance of an Azure IoT Hub service using the Standard (S1) or Free (F0) pricing tier.

Use the Azure CLI to create an instance of Azure IoT Hub. Replace the parameters where appropriate. Alternatively, you can create the Azure IoT Hub on the Azure portal.

curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash

sudo az login

sudo az account set --subscription "<name or ID of Azure Subscription>"

sudo az group create --name "<resource-group-name>" --location "<your-region>"

See Region Support for available regions.

sudo az iot hub create --name "<iothub-group-name>" --sku S1 --resource-group "<resource-group-name>"

sudo az iot hub device-identity create --hub-name "<iothub-name>" --device-id "<device-name>" --edge-enabled

You need to install Azure IoT Edge version 1.0.9. Follow these steps to download the correct version:

Ubuntu Server 18.04:

curl https://packages.microsoft.com/config/ubuntu/18.04/multiarch/prod.list > ./microsoft-prod.list

Copy the generated list.

sudo cp ./microsoft-prod.list /etc/apt/sources.list.d/

Install the Microsoft GPG public key.

curl https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor > microsoft.gpg

sudo cp ./microsoft.gpg /etc/apt/trusted.gpg.d/

Update the package lists on your device.

sudo apt-get update

Install the 1.0.9 release:

sudo apt-get install iotedge=1.1* libiothsm-std=1.1*

Next, register the host computer as an IoT Edge device in your IoT Hub instance, using a connection string.

You need to connect the IoT Edge device to your Azure IoT Hub. You need to copy the connection string from the IoT Edge device you created earlier. Alternatively, you can run the below command in the Azure CLI.

sudo az iot hub device-identity connection-string show --device-id my-edge-device --hub-name test-iot-hub-123

On the host computer open /etc/iotedge/config.yaml for editing. Replace ADD DEVICE CONNECTION STRING HERE with the connection string. Save and close the file. Run this command to restart the IoT Edge service on the host computer.

sudo systemctl restart iotedge

Deploy the Spatial Analysis container as an IoT Module on the host computer, either from the Azure portal or Azure CLI. If you're using the portal, set the image URI to the location of your Azure Container Registry.

Use the below steps to deploy the container using the Azure CLI.

An Azure Virtual Machine with a GPU can also be used to run Spatial Analysis. The example below will use a NCv3 series VM that has one v100 GPU.

Create the VM

Open the Create a Virtual Machine wizard in the Azure portal.

Give your VM a name and select the region to be (US) West US 2.

To locate the VM size, select "See all sizes" and then view the list for "N-Series" and select NC6s_v3, shown below.

Next, Create the VM. Once created, navigate to the VM resource in the Azure portal and select Extensions from the left pane. Select on "Add" to bring up the extensions window with all available extensions. Search for and select NVIDIA GPU Driver Extension, select create, and complete the wizard.

Once the extension is successfully applied, navigate to the VM main page in the Azure portal and select Connect. The VM can be accessed either through SSH or RDP. RDP is helpful as it enables viewing of the visualizer window (explained later). Configure the RDP access by following these steps and opening a remote desktop connection to the VM.

Verify Graphics Drivers are Installed

Run the following command to verify that the graphics drivers have been successfully installed.

nvidia-smi

You should see the following output.

Install Docker CE and nvidia-docker2 on the VM

Run the following commands one at a time in order to install Docker CE and nvidia-docker2 on the VM.

Install Docker CE on the host computer.

sudo apt-get update

sudo apt-get install -y apt-transport-https ca-certificates curl gnupg-agent software-properties-common

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -

sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"

sudo apt-get update

sudo apt-get install -y docker-ce docker-ce-cli containerd.io

Install the nvidia-docker-2 software package.

DISTRIBUTION=$(. /etc/os-release;echo $ID$VERSION_ID)

curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -

curl -s -L https://nvidia.github.io/nvidia-docker/$DISTRIBUTION/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list

sudo apt-get update

sudo apt-get install -y docker-ce nvidia-docker2

sudo systemctl restart docker

Now that you have set up and configured your VM, follow the steps below to configure Azure IoT Edge.

Configure Azure IoT Edge on the VM

To deploy the Spatial Analysis container on the VM, create an instance of an Azure IoT Hub service using the Standard (S1) or Free (F0) pricing tier.

Use the Azure CLI to create an instance of Azure IoT Hub. Replace the parameters where appropriate. Alternatively, you can create the Azure IoT Hub on the Azure portal.

curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash

sudo az login

sudo az account set --subscription "<name or ID of Azure Subscription>"

sudo az group create --name "<resource-group-name>" --location "<your-region>"

See Region Support for available regions.

sudo az iot hub create --name "<iothub-name>" --sku S1 --resource-group "<resource-group-name>"

sudo az iot hub device-identity create --hub-name "<iothub-name>" --device-id "<device-name>" --edge-enabled

You need to install Azure IoT Edge version 1.0.9. Follow these steps to download the correct version:

Ubuntu Server 18.04:

curl https://packages.microsoft.com/config/ubuntu/18.04/multiarch/prod.list > ./microsoft-prod.list

Copy the generated list.

sudo cp ./microsoft-prod.list /etc/apt/sources.list.d/

Install the Microsoft GPG public key.

curl https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor > microsoft.gpg

sudo cp ./microsoft.gpg /etc/apt/trusted.gpg.d/

Update the package lists on your device.

sudo apt-get update

Install the 1.0.9 release:

sudo apt-get install iotedge=1.1* libiothsm-std=1.1*

Next, register the VM as an IoT Edge device in your IoT Hub instance, using a connection string.

You need to connect the IoT Edge device to your Azure IoT Hub. You need to copy the connection string from the IoT Edge device you created earlier. Alternatively, you can run the below command in the Azure CLI.

sudo az iot hub device-identity connection-string show --device-id my-edge-device --hub-name test-iot-hub-123

On the VM open /etc/iotedge/config.yaml for editing. Replace ADD DEVICE CONNECTION STRING HERE with the connection string. Save and close the file. Run this command to restart the IoT Edge service on the VM.

sudo systemctl restart iotedge

Deploy the Spatial Analysis container as an IoT Module on the VM, either from the Azure portal or Azure CLI. If you're using the portal, set the image URI to the location of your Azure Container Registry.

Use the below steps to deploy the container using the Azure CLI.