OSIsoft Edge Data Store Azure IoT Deployment Sample

February 2, 2024 ยท View on GitHub

Version: 1.0.7

Build Status

This sample uses bash scripts to deploy Edge Data Store to a remote Linux edge device using Azure IoT Hub and Azure IoT Edge Modules.

Requirements

One-Time Local Setup

  1. If on Windows, install Windows Subsystem for Linux, see Microsoft Docs
    Powershell:

    Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux

    Then install a Linux distribution like Ubuntu, and use bash for all other commands in this ReadMe.

  2. Install Azure CLI, see Microsoft Docs
    Note: if preferred, download script and inspect it before running

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

  3. Install IoT extension for Azure CLI, see Microsoft Docs

    az extension add --name azure-iot

  4. Log in to Azure CLI, see Microsoft Docs

    az login

  5. Set the active subscription for Azure CLI, see Microsoft Docs

    az account set --subscription "{Subscription}"

  6. Install Docker, see Docker Docs
    Note: if preferred, download script and inspect it before running

    curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

  7. After downloading this repository, it may be necessary to change the mode for the bash scripts before running them. In order to do so, use the chmod command:

    # Required scripts
chmod +x remote.sh
chmod +x device.sh

# Optional (For reset scripts)
chmod +x reset.sh
chmod +x reset-device.sh

# Optional (For automated test script)
chmod +x test.sh

  8. Create an Azure IoT Hub with IoT Edge enabled, see Microsoft Docs

  9. Create an Azure Container Registry with Admin user enabled, see Microsoft Docs

  10. Build Edge Data Store container matching the edge device processor architecture (ARM32, ARM64, or AMD64), see OSIsoft Docs

  11. Push container image to Azure Container Registry, see Microsoft Docs

    docker push <acrLoginServer>/edgedatastore:v1

  12. Configure specified IotEdgeConfigPath file (iotedge-config.json by default) with required Azure IoT Edge Device Module information, specifically the required Azure Container Registry details.

    1. {azureContainerRegistryName} should be the name of the Azure Container Registry
    2. {azureContainerRegistryAddress} should be the 'Login server'
    3. {azureContainerRegistryPassword} should be the 'password' from 'Access Keys'
    4. {azureContainerRegistryUsername} should be the 'Username' from 'Access Keys'
    5. {azureContainerRegistryImageUri} should be the specific image URI, like myregistry.azurecr.io/edgedatastore:v1

Per-Device Setup

  1. (Optional) Set up SSH for passwordless login, see Linuxize Article

    ssh-keygen -t rsa -b 4096 -C "your_email@domain.com"
ssh-copy-id remote_username@device_ip_address
ssh remote_username@device_ip_address

  2. Configure config.ini with required information for the device

  3. If necessary, update the IotEdgeConfigPath file with the correct Edge Data Store container image for the destination device processor architecture (ARM32, ARM64, or AMD64)

  4. Configure specified EdsConfigPath file (eds-config.json by default) with required Edge Data Store system configuration, see OSIsoft Docs
    Note: The default EDS configuration file is the minimum configuration from the OSIsoft Docs, and includes no Periodic Egress Endpoints or Adapters

Sample Deployment Process

The sample will execute the following steps to deploy and configure Edge Data Store.

  1. Create an Azure IoT Edge Device in Azure IoT Hub
  2. Deploy the Edge Data Store Azure IoT Edge Module to the Azure IoT Edge Device
  3. Retrieve the connection string for the Azure IoT Edge Device
  4. Prepare a folder of files to send to the edge device
  5. Back up that folder by IP address to record a record of what was sent to the device
  6. Send the folder to the edge device
  7. Run the device.sh script on the device, which will run the following steps
    1. Prepare for and install the Azure IoT Edge runtime and Azure IoT Security Daemon
    2. Configure Azure IoT Edge by setting the device connection string
    3. Restart Azure IoT Edge and wait for Edge Data Store to be deployed
    4. Configure Edge Data Store using the specified configuration file

Running the Sample

Open a bash terminal, and run the remote.sh script.

./remote.sh

Running the Reset Script

A script is also included that can restore the Azure Iot Hub and destination edge device back to their original state. In order to do so, open a bash terminal and run the reset.sh script.

./reset.sh

Running the Automated Test

Note: Running the automated test requires extensive setup and a dedicated Azure VM, this section is largely intended to document internal build pipeline requirements.

Test Requirements

Configure the config.ini file including the Test section:

  1. Create (or find) an Azure Virtual Machine using the Ubuntu 18.04 LTS image, and enter the IpAddress, OS (ubuntu/18.04), UserName, and Password created for the device
  2. Ensure the Azure IoT Hub Name is entered for HubName, and enter the Virtual Machine name for DeviceId (DeviceId can be any string, but should be used to identify the device)
  3. Create (or find) an Azure Service Principal for use with the test script, see Microsoft Docs The service principal username and password should be entered for AzUsername and AzPassword
  4. Enter your Azure Tenant ID into AzTenant, see Microsoft Docs
  5. Enter your Azure Subscription Name into AzSubscription; your list of subscriptions should be listed when you login using the Azure CLI az login command
  6. Enter the Azure Container Registry fields described in the last step of One-Time Local Setup for the "Acr" fields

Using the Bash Terminal

Once the config.ini file is fully configured (including the Test section), open a bash terminal and run the test.sh script.

./test.sh

For the Edge landing page ReadMe
For the OSIsoft Samples landing page ReadMe