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

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.

1. An Azure account
   • You can create an account free here
2. 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
3. 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

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

1. To download the script, use the command:

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

2. 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)

3. 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
   

View, copy, and paste commands

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

Screen capture provides an overall sense of the procedure; for detailed instructions see the following

1. 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"
   ## ⬆️⬆️⬆️
   

2. 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.

3. 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:

• Quickstart: Query examples for getting started with OSConfig and Azure IoT
• Working with network adapter status, IP addresses, etc., using OSConfig and Azure IoT
• Working with host names using Azure IoT and OSConfig
• Manage the OS package manager using Azure IoT and OSConfig
• and more

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.