Codebase for an automated IoT platform PoC using Azure, Terraform, and GitHub Actions.

• Prerequisites
• Setup Instructions
  • Install Required Tools
  • Azure Setup
  • GitHub Setup
  • Deploy Infrastructure
• Device Preparation
  • Install Docker
  • Install Azure IoT Edge Runtime
  • Configure IoT Edge Device
• Troubleshooting
• References

Before you begin, ensure you have the following installed on your local machine:

• Azure CLI (version 2.0 or later): Used to interact with Azure services.
• Terraform (version 0.13 or later): Infrastructure as Code tool for provisioning Azure resources.
• Docker: Required for running containerized applications.
• Azure IoT Edge Runtime: For deploying modules to IoT Edge devices.
• GitHub Account: For accessing and configuring the repository and Actions.

• Windows:

  Download and install from Azure CLI Installer.

• macOS:

  brew update && brew install azure-cli

• Linux:

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

Download the appropriate package for your OS from the Terraform Downloads Page, and follow the installation instructions.

Alternatively, using a package manager:

• macOS (Homebrew):

  brew tap hashicorp/tap
  brew install hashicorp/tap/terraform

• Windows (Chocolatey):

  choco install terraform

Refer to the official Docker installation guide: Get Docker

Installation steps are provided in the Device Preparation section.

1. Login to Azure CLI

   az login

   If you have multiple subscriptions, list them using:

   az account list --output table

2. Set the Desired Azure Subscription

   az account set --subscription "your-subscription-id-or-name"

3. Create a Resource Group

   The Terraform configuration expects a resource group named iotops-demo. Create it using:

   az group create --name iotops-demo --location "brazilsouth"

4. Create a Storage Account and Blob Container

   The Terraform backend requires a storage account named iotopstfstate and a blob container named tfstate. Create them using:

   # Create Storage Account
   az storage account create \
     --name iotopstfstate \
     --resource-group iotops-demo \
     --location "brazilsouth" \
     --sku Standard_LRS \
     --kind StorageV2
   
   # Retrieve Storage Account Key
   ACCOUNT_KEY=$(az storage account keys list \
     --resource-group iotops-demo \
     --account-name iotopstfstate \
     --query "[0].value" -o tsv)
   
   # Create Blob Container
   az storage container create \
     --name tfstate \
     --account-name iotopstfstate \
     --account-key $ACCOUNT_KEY

   Note: The storage account name must be globally unique. If iotopstfstate is already taken, choose another name and update provider.tf accordingly.

1. Fork the Repository

   • Fork this repository to your own GitHub account.

2. Create a GitHub Environment

   • In your GitHub repository, go to Settings > Environments.
   • Click New environment and name it iotops-demo (or your preferred environment name).

3. Set AZURE_CREDENTIALS Secret

   • Create a Service Principal with Contributor role:

     az ad sp create-for-rbac \
      --name "github-actions-sp" \
      --role contributor \
      --scopes /subscriptions/$(az account show --query id -o tsv) \
      --sdk-auth
     

     Replace {subscription-id} with your Azure subscription ID. The command will output a JSON object containing your credentials.

   • Add Secret to GitHub:

     • In your GitHub repository, go to Settings > Secrets and variables > Actions.
     • Click New repository secret.
     • Set the name as AZURE_CREDENTIALS and paste the JSON output from the previous step.

4. Update GitHub Actions Workflow

   Ensure that the environment name in your GitHub Actions workflow (deploy-infrastructure.yml) matches the one you created.

The deployment is automated using GitHub Actions.

1. Trigger the Workflow

   • Go to the Actions tab in your GitHub repository.
   • Select the Deploy Infrastructure workflow.
   • Click Run workflow.
   • Choose the environment (e.g., iotops-demo) and click Run workflow.

2. Monitor the Deployment

   • The workflow will execute and provision the Azure resources defined in the Terraform configuration.
   • You can monitor the progress and view logs directly in the Actions tab.

3. Verify Deployment

   • After the workflow completes, verify that the resources have been created in your Azure subscription.

   • You can check via the Azure Portal or using the Azure CLI:

     az iot hub list --resource-group iotops-demo --output table

Prepare your IoT Edge device by installing Docker and Azure IoT Edge runtime.

You can use the provided script or install manually.

Run the following script on your device:

chmod +x scripts/install-docker.sh
./scripts/install-docker.sh

Refer to the official Docker installation guide.

You can use the provided script or install manually.

Run the following script on your device:

chmod +x scripts/install-iot-edge.sh
./scripts/install-iot-edge.sh

1. Register Microsoft Package Repository

   curl https://packages.microsoft.com/config/ubuntu/$(lsb_release -rs)/prod.list > ./microsoft-prod.list
   sudo cp ./microsoft-prod.list /etc/apt/sources.list.d/
   curl https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor > microsoft.gpg
   sudo cp ./microsoft.gpg /etc/apt/trusted.gpg.d/

2. Install the IoT Edge Security Daemon

   sudo apt-get update
   sudo apt-get install moby-engine moby-cli iotedge

1. Retrieve Device Connection String

   • After deploying the infrastructure, retrieve the device connection string from your IoT Hub.

   • Use the Azure CLI:

     az iot hub device-identity connection-string show --hub-name {your-iot-hub-name} --device-id {your-device-id}

2. Update IoT Edge Configuration

   Edit the IoT Edge configuration file:

   sudo nano /etc/iotedge/config.yaml

   Replace the provisioning section with your device connection string:

   provisioning:
     source: "manual"
     device_connection_string: "{your-device-connection-string}"

3. Restart IoT Edge Service

   sudo systemctl restart iotedge

4. Verify Installation

   Check the status of the IoT Edge runtime:

   sudo iotedge check

   List running modules:

   sudo iotedge list

• Terraform Errors: If you encounter errors during Terraform initialization or deployment, ensure that your Azure credentials are correctly configured and that the resource names are unique.

• Docker Issues: Verify that Docker is running properly on your device by running sudo docker run hello-world.

• IoT Edge Runtime: If the IoT Edge runtime fails to start, check the logs:

  journalctl -u iotedge --no-pager --no-full

• GitHub Actions Failures: Review the logs in the GitHub Actions tab to identify any issues during the workflow execution.

• Azure IoT Edge Documentation
• Terraform Azure Provider
• Azure CLI Documentation
• Docker Documentation