Create an OSConfig (with Azure IoT) lab environment in 5 minutes

Article
08/05/2022

This article and associated sample script are for anyone who wants to quickly try out OSConfig scenarios, including multi-device scenarios. The script results in:

An Azure resource group (for organizing lab resources and easy cleanup)
An IoT Hub
One or many Azure VMs (as stand-ins for real IoT/Edge devices), which
- Have OSConfig installed and running
- Are connected to IoT Hub

If you are looking for background information on how, where, and why to install OSConfig, see: How and where to install the OSConfig agent for Linux.

After following this procedure, you will have a lab environment for trying out specific scenarios, such as managing network adapters, host names, package managers, custom configuration, and more.

Note

Given the ephemeral lab nature of this environment, each virtual device connects to IoT Hub using a simple connection string passed via command line. For a production deployment use stronger authentication and device identity mechanisms supported by Azure IoT, such as TPM or X.509 based identities.

Prerequisites

For an overall sense of pre-requisites, see the following screen capture. For detailed instructions, continue reading.

Screen capture showing launch of cloud shell and ensuring Azure IoT extension is installed

An Azure account
- You can create an account free here
Azure Cloud Shell (recommended) or another bash environment with Azure CLI present and signed in to your Azure account
- Cloud Shell enables easy access and sign-in via web browser, and provides a bash environment with Azure CLI already installed and authenticated
  - If this is your first time using Cloud Shell, the experience will include creating a storage account for your shell resources
- If you prefer to use your own bash environment instead, ensure Azure CLI is installed and signed in to your account
- You can use az account show to check that Azure CLI is signed into the account you want to use
The Azure IoT extension for Azure CLI
- You can ensure this is installed by running: az extension add --name azure-iot

Create your lab environment

For detailed instructions, select your preferred approach:

Download, customize, and run script
View, copy, and paste commands

For an overall sense of the procedure, see the following screen capture. For detailed instructions, continue reading.

Screen capturing showing the download, modify, and run steps

To download the script, use the command:

curl -L https://aka.ms/OSConfigLabCreateExampleScript | tr -d '\r' > ./create-lab-fleet.sh

Inspect and customize the script using your preferred text editor

To use the nano text editor, for example, use the command:
```
nano ./create-lab-fleet.sh
```
Tip

The first three parameters in the script are the most often customized:
- Which Azure region to use (line 4 use_this_azure_location)
- How many virtual IoT devices to create (line 5 create_this_many_devices)
- Whether to use stable or preview builds of OSConfig (line 6 package_channels)
Execute

Once you are satisfied with your script (modified from the original sample), you can execute it by running the following:
```
chmod +x ./create-lab-fleet.sh
./create-lab-fleet.sh
```

For an overall sense of the procedure, see the following screen capture. For detailed instructions, continue reading.

Screen capture showing the above steps of copy/paste into shell Screen capture provides an overall sense of the procedure; for detailed instructions see the following

First, customize (if necessary) these first few lines to suit your environment

For example, you could copy these lines into a text editor, modify any parameters as needed, and then paste the modified lines into your shell environment.

Tip

The first three parameters are the most often customized:

Which Azure region to use
How many virtual IoT devices to create
Whether to use stable or preview builds of OSConfig

#!/bin/bash

## ⬇️⬇️⬇️ IMPORTANT: Modify these parameters to suit your environment
use_this_azure_location="southcentralus"
create_this_many_devices=4
package_channels=("prod") # Use ("prod") for stable release, use ("prod" "insiders-fast") for preview builds
start_device_labels_at_number=1 # Typically 1
existing_lab_environment_name="" # Typically blank, which results in a new environment being created
vm_size="Standard_B1s"
## ⬆️⬆️⬆️

Next, create a resource group and IoT Hub

You can copy from here and paste into your shell environment. Creating the IoT Hub may take a few minutes to complete.

## Create (if needed) resource group and IoT Hub
if [[ -n $existing_lab_environment_name ]]; then
  demoUniqueLabel="$existing_lab_environment_name"
else 
  uniquifier=$(od --address-radix=n -N2 -i /dev/random | tr -d "[:space:]")
  demoUniqueLabel="QuickStart-$uniquifier"
  echo "Creating resource group and IoT Hub"
  az group create --name "$demoUniqueLabel" --location "$use_this_azure_location" --query id
  az iot hub create --resource-group "$demoUniqueLabel" --name "$demoUniqueLabel" --query id --output tsv
fi
echo "
   IMPORTANT:
      Your IoT Hub and Resource Group are named: $demoUniqueLabel

"

Important

Make a note of the name returned (will be similar to "QuickStart-nnnn"). You will need this later for trying out scenarios in IoT Hub, or for deleting this lab environment when you no longer need it.

Next, create a series of IoT Hub device Ids and virtual devices

## Create IoT Hub device IDs and corresponding connected virtual devices (VMs)
vmInitScriptTemplate='#!/bin/bash
## add prod and sometimes insider channels from packages.microsoft.com
curl -sSL https://packages.microsoft.com/keys/microsoft.asc | sudo tee /etc/apt/trusted.gpg.d/pkgs-msft_key.asc > /dev/null
## channel add commands added dynamically below this line
sudo apt-get update

## Install and configure AIS, then osconfig
sudo apt install -y aziot-identity-service
sudo aziotctl config mp --connection-string DEMO_CONNECTION_STRING_PLACEHOLDER --force; sudo aziotctl config apply
sudo apt-get -y install osconfig
'

for i in $(seq $start_device_labels_at_number $create_this_many_devices)
do
    deviceName=$(printf "device%02d" "$i")
    echo "Creating device ID and connected virtual device $deviceName"
    pathToDeviceInitScript="/var/tmp/$deviceName.sh"
    az iot hub device-identity create --hub-name "$demoUniqueLabel" --device-id "$deviceName" --query status
    connectionString=$(az iot hub device-identity connection-string show --device-id "$deviceName" --hub-name "$demoUniqueLabel" --query connectionString)
    echo "$vmInitScriptTemplate" > "$pathToDeviceInitScript"
    sed -i "s|DEMO_CONNECTION_STRING_PLACEHOLDER|$connectionString|" "$pathToDeviceInitScript"
    for channelName in "${package_channels[@]}"
    do
      additionalChannelString="curl -sSL https://packages.microsoft.com/config/ubuntu/20.04/$channelName.list | sudo tee /etc/apt/sources.list.d/pkgs-msft_$channelName.list"
      sed -i "5 s[^[$additionalChannelString\n[" "$pathToDeviceInitScript"
    done
    az vm create --resource-group "$demoUniqueLabel" --name "$deviceName" --size "$vm_size" --image "canonical:0001-com-ubuntu-server-focal:20_04-lts-gen2:latest" --generate-ssh-keys --user-data "$pathToDeviceInitScript" --public-ip-sku Standard --admin-username "azureuser" --no-wait
    sleep 2
    rm "$pathToDeviceInitScript"
done
echo "Done"

Next Steps

Now that you have a lab environment you can try out different OSConfig scenarios, for example:

Important

When you are ready to dispose of this lab environment you can run the following (replacing <RG_NAME> with the name of your resource group): az group delete --name <RG_NAME>. While these resources (VMs, IoT Hub, etc.) continue to exist they will consume some amount of your Azure credits or budget.

Share via

Create an OSConfig (with Azure IoT) lab environment in 5 minutes

Prerequisites

Create your lab environment

Next Steps

Additional resources