This repository provides a complete reference implementation for deploying and managing Azure IoT Operations (AIO) on edge devices, with sample applications demonstrating industrial IoT scenarios.

This is a hands-on learning repository for Azure IoT Operations, covering:

• Edge Infrastructure Setup - Automated deployment of Azure IoT Operations on Ubuntu/K3s clusters
• MQTT-Based Asset Management - Creating and managing industrial assets with MQTT connectivity
• ARM Template Deployment - Infrastructure-as-code for deploying assets directly to Azure
• Sample IoT Applications - Production-ready edge applications including simulators and data processors
• Troubleshooting & Diagnostics - Scripts and guides for debugging common AIO issues
• Cloud Integration - Connecting edge devices to Azure Fabric, Real-Time Intelligence, and other services

The repository demonstrates real-world patterns for industrial IoT deployments, from initial cluster setup through application deployment and cloud integration.

The deployment process is split into two distinct phases for better security and flexibility.

Run on the edge device to prepare local infrastructure:

# On Ubuntu edge device (24.04+, 16GB RAM, 4 CPU cores minimum)
cd linux_build
bash linux_installer.sh

NOTE: The install will do several things that can create a restart. This will make it look like you lost connection. This is ok. It's meant to do this. Restart and rerun the script to continue if this happens.

Installs: K3s cluster, kubectl, Helm, optional tools (k9s, mqtt-viewer, mqttui), edge modules
Output: edge_configs/cluster_info.json for remote configuration
Configuration: Uses linux_aio_config.json for optional_tools and modules settings

Run from any Windows machine with Azure CLI to connect and deploy AIO:

# On DevOps machine, developer workstation, or CI/CD pipeline
cd linux_build
.\External-Configurator.ps1 -ConfigFile ".\edge_configs\cluster_info.json"

Configures: Azure Arc, resource groups, AIO deployment, asset sync
Benefits: No Azure credentials needed on edge device, supports multi-cluster management

# Check AIO pods are running
kubectl get pods -n azure-iot-operations

# Verify assets in Azure
az resource list --resource-group <YOUR_RG> --resource-type Microsoft.DeviceRegistry/assets -o table

# Monitor MQTT messages
kubectl exec -it -n azure-iot-operations deploy/aio-broker-frontend -- \
  mosquitto_sub -h localhost -p 18883 -t 'factory/#' -v

If you want to view Kubernetes resources directly in the Azure Portal (under Arc-enabled Kubernetes → Kubernetes resources), you'll need a service account bearer token:

# On the edge device
cd linux_build
bash get-k8s-bearer-token.sh

This script:

• Creates a service account with cluster-admin permissions
• Generates a bearer token
• Saves the token to USB/SD drive (or local directory)
• Provides instructions for using it in Azure Portal

Note: This is not required for Azure IoT Operations to function. AIO works independently of the Azure Portal Kubernetes viewer. However, the bearer token can be helpful for:

• Troubleshooting pods and deployments from the Azure Portal
• Viewing cluster resources without SSH access to the edge device
• Demonstrating full cluster visibility to stakeholders

• Linux Build Steps - Complete step-by-step guide for installing AIO on a fresh Linux system
• K3s Troubleshooting Guide - Comprehensive troubleshooting reference for K3s cluster issues
• Azure Portal Setup - Guide for discovering and managing devices in Azure Portal
• linux_installer.sh - Edge device installer (local infrastructure only)
• External-Configurator.ps1 - Remote Azure configurator (cloud resources only)
• Deploy-EdgeModules.ps1 - Automated deployment script for edge applications
• Deploy-Assets.ps1 - ARM template deployment script for Azure assets

• Edge MQTT Simulator - Comprehensive factory telemetry simulator
• Edge Historian - SQL-based historian with HTTP API for querying historical MQTT data
• Fabric Integration - Connecting AIO to Microsoft Fabric

Create the Python environment using uv:

uv sync

This repository demonstrates a modern edge-to-cloud architecture with separated edge infrastructure and cloud orchestration.

The deployment architecture divides the process into two distinct phases for better security and maintainability:

┌────────────────────────────────────────────────────────────────┐
│  Phase 1: Edge Device Setup (linux_installer.sh)              │
│  Runs ON the edge device                                       │
│                                                                 │
│  ┌──────────────────────────────────────────────────────────┐ │
│  │  Edge Device (Ubuntu + K3s)                              │ │
│  │  • System preparation & validation                       │ │
│  │  • K3s cluster installation                              │ │
│  │  • kubectl & Helm installation                           │ │
│  │  • Local system configuration                            │ │
│  │  Output: cluster_info.json                               │ │
│  └──────────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────┘
                              │
                              │ Transfer cluster_info.json
                              │ (Secure copy to management machine)
                              ▼
┌────────────────────────────────────────────────────────────────┐
│  Phase 2: Azure Configuration (External-Configurator.ps1)     │
│  Runs FROM any Windows machine with Azure CLI                 │
│                                                                 │
│  ┌──────────────────────────────────────────────────────────┐ │
│  │  Remote Configuration Machine                            │ │
│  │  • Azure Arc enablement                                  │ │
│  │  • Resource group & namespace creation                   │ │
│  │  • AIO instance deployment                               │ │
│  │  • Asset synchronization                                 │ │
│  │  • Multi-cluster management                              │ │
│  │  Output: deployment_summary.json                         │ │
│  └──────────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────┘
                              │
                              │ Azure Arc Connection
                              ▼
┌────────────────────────────────────────────────────────────────┐
│  Azure Cloud Resources                                         │
│  • Arc-enabled Kubernetes (connected edge cluster)            │
│  • Azure IoT Operations instance                              │
│  • Device Registry (Assets)                                   │
│  • Schema Registry & Storage                                  │
│  • Microsoft Fabric integration                               │
└────────────────────────────────────────────────────────────────┘

Benefits of Separated Architecture:

• 🔒 Security: No Azure credentials needed on edge devices
• 📡 Remote Management: Configure multiple edge devices from central location
• 🔄 CI/CD Friendly: Easy pipeline integration for GitOps workflows
• 🐛 Easier Debugging: Clear separation of local vs. cloud issues
• 🏢 Production Ready: Follows best practices for enterprise deployments
• 🎯 Modular Deployment: Configure edge modules (edgemqttsim, demohistorian, etc.) via config file

• Hardware: 16GB RAM minimum, 4 CPU cores, 50GB disk space
• OS: Ubuntu 24.04 LTS (or compatible Linux distribution)
• Azure: Active Azure subscription with appropriate permissions
• Tools: Azure CLI, kubectl, docker/containerd

This is a learning repository. Feel free to:

• Add new sample applications to iotopps/
• Improve diagnostic scripts in linux_build/
• Contribute troubleshooting tips and solutions
• Share integration examples with other Azure services

• Azure IoT Operations Documentation
• K3s Documentation
• MQTT Protocol Specification
• Azure Arc Documentation

This setup enables edge computing capabilities with local MQTT brokers, data processing pipelines, and integration with Azure cloud services.