Quickstart: Start developing with the Azure IoT Operations SDKs (preview)

Get started developing with the Azure IoT Operations SDKs. Follow these steps to set up your development environment for building and running the samples, as well as creating and testing your own highly available edge applications.

GitHub repository | .NET SDK | Go SDK | Rust SDK

Prerequisites

Before you begin, prepare the following prerequisites:

An Azure subscription. If you don't have an Azure subscription, create one for free before you begin.
A GitHub account.
Azure access permissions. For more information, see Deployment details > Required permissions.

Setting up

Developing with the Azure IoT Operations SDKs requires a Kubernetes cluster with Azure IoT Operations deployed. Further configuration allows the MQTT broker to be accessed directly from the developer environment.

Important

The following development environment setup options, use K3s running in K3d for a lightweight Kubernetes cluster, and deploys Azure IoT Operations with test settings. For production deployments, choose secure settings.
If you want to use secure settings, we recommend you follow the instructions in Prepare your Azure Arc-enabled Kubernetes cluster to create a K3s cluster on Ubuntu and Deploy Azure IoT Operations to a production cluster to deploy with secure settings. Then proceed to configure Azure IoT Operations for deployment.

Codespaces
Ubuntu

GitHub Codespaces provides the most streamlined experience and can get the development environment up and running in a couple of minutes.

Create a codespace in GitHub Codespaces from the Azure IoT Operations SDKs repository:
Once the codespace is created, you have a container with the developer tools and a local K3s cluster running in K3d preinstalled.

Install Ubuntu

Clone the Azure IoT Operations SDKs repository:

git clone https://github.com/Azure/iot-operations-sdks

Navigate to the repository root directory:
```
cd <REPOSITORY ROOT>
```
Initialize the cluster and install required dependencies using the initialize-cluster.sh script:
```
sudo ./tools/deployment/initialize-cluster.sh
```
This script does the following:
1. Install prerequisites including:
  1. Docker if not already installed
  2. Mosquitto MQTT client for testing
  3. k3d to run lightweight Kubernetes clusters
  4. Helm for Kubernetes package management
  5. Step CLI for certificate management
  6. Azure CLI for managing Azure resources
  7. kubectl (Kubernetes CLI) for interacting with Kubernetes clusters
  8. k9s for managing Kubernetes clusters
2. DELETE any existing k3d cluster
3. Deploy a new k3d cluster
4. Set up port forwarding for ports 1883, 8883, and 8884 to enable TLS
5. Create a local container registry
For the next step you need nonroot access to the cluster, run the following command:
```
mkdir ~/.kube; sudo install -o $USER -g $USER -m 600 /root/.kube/config ~/.kube/config
```
This command gives your nonroot user access to the Kubernetes cluster by copying the cluster configuration file from the root account to your user account, ensuring you have the correct permissions to use Kubernetes tools like kubectl without needing root access.

Run the following command to increase the user watch/instance limits.

echo fs.inotify.max_user_instances=8192 | sudo tee -a /etc/sysctl.conf
echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf

sudo sysctl -p

For better performance, increase the file descriptor limit:

echo fs.file-max = 100000 | sudo tee -a /etc/sysctl.conf

sudo sysctl -p

Deploy Azure IoT Operations

You'll arc-enable the development cluster created in the previous step and deploy Azure IoT Operations with test settings.

Open a new bash terminal and do the following steps:

Navigate to the repository root directory:
```
cd <REPOSITORY ROOT>
```

Run the install-aio-arc.sh script to arc-enable your cluster and deploy Azure IoT Operations, replacing the placeholders with your values:

Parameter	Value
LOCATION	An Azure region close to you. For the list of currently supported regions, see Supported regions.
RESOURCE_GROUP	A name for a new Azure resource group where your cluster will be created.
CLUSTER_NAME	A name for your Kubernetes cluster.
STORAGE_ACCOUNT_NAME	A name for your storage account. Storage account names must be between 3 and 24 characters in length and only contain numbers and lowercase letters.
SCHEMA_REGISTRY_NAME	A name for your schema registry. Schema registry names can only contain numbers, lowercase letters, and hyphens.
SCHEMA_REGISTRY_NAMESPACE	A name for your schema registry namespace. The namespace uniquely identifies a schema registry within a tenant. Schema registry namespace names can only contain numbers, lowercase letters, and hyphens.

./tools/deployment/install-aio-arc.sh -l <LOCATION> -g <RESOURCE_GROUP> -c <CLUSTER_NAME> -s <STORAGE_ACCOUNT_NAME> -r <SCHEMA_REGISTRY_NAME> -n <SCHEMA_REGISTRY_NAMESPACE>

This script does the following:

Log in to Azure CLI
Create a resource group
Register Required Azure Providers
Connect Kubernetes Cluster to Azure Arc
Enable Azure Arc Features
Create Azure Storage Account
Create Azure IoT Operations Schema Registry
Initialize Azure IoT Operations
Create Azure IoT Operations Instance

After the deployment is complete, use az iot ops check to evaluate Azure IoT Operations service deployment for health, configuration, and usability. The check command can help you find problems in your deployment and configuration.
```
az iot ops check
```

Configure Azure IoT Operations for development

After Azure IoT Operations is deployed, you need to configure it for development. This includes setting up the MQTT broker and authentication methods, and ensuring that the necessary environment variables are set for your development environment:

Navigate to the repository root directory:
```
cd <REPOSITORY ROOT>
```
Run the configure-aio.sh script to configure Azure IoT Operations for development:
```
./tools/deployment/configure-aio.sh
```
This script does the following:
1. Setup certificate services, if missing
2. Create root and intermediate CAs for x509 authentication
3. Create the trust bundle ConfigMap for the Broker to authentication x509 clients
4. Configure a BrokerListener and BrokerAuthentication resources for SAT and x509 auth

Testing the installation

To test the setup is working correctly, use mosquitto_pub to connect to the MQTT broker to validate the x509 certs, SAT, and trust bundle.

Export the .session directory:

export SESSION=$(git rev-parse --show-toplevel)/.session

Test no TLS, no auth:

mosquitto_pub -L mqtt://localhost:1883/hello -m world --debug

Test TLS with x509 auth:

mosquitto_pub -L mqtts://localhost:8883/hello -m world --cafile $SESSION/broker-ca.crt --cert $SESSION/client.crt --key $SESSION/client.key --debug

Test TLS with SAT auth:

mosquitto_pub -L mqtts://localhost:8884/hello -m world --cafile $SESSION/broker-ca.crt -D CONNECT authentication-method K8S-SAT -D CONNECT authentication-data $(cat $SESSION/token.txt) --debug

Run a Sample

This sample demonstrates a simple communication between a client and a server using Telemetry and remote procedure call (RPC). The server tracks the value of a counter and accepts RPC requests from the client to either read or increment that counter.

Install the .NET 9.0 SDK
The samples within Azure IoT Operations SDKs GitHub repository read configuration from environment variables. We provide an .env file in the repository root that exports the variables used by the samples to connect to the MQTT Broker. Edit the .env file to set the values for your environment, or use the default values provided in the file.

Navigate to the CounterServer sample directory:

cd <REPOSITORY ROOT>/dotnet/samples/Protocol/Counter/CounterServer/

Build the sample:
```
dotnet build
```

Run the sample:

source `git rev-parse --show-toplevel`/.env; export AIO_MQTT_CLIENT_ID=counter-server; dotnet run

Open a new shell and navigate to the CounterClient sample directory:

cd <REPOSITORY ROOT>/dotnet/samples/Protocol/Counter/CounterClient/

Build the sample:
```
dotnet build
```

Run the sample:

source `git rev-parse --show-toplevel`/.env; export AIO_MQTT_CLIENT_ID=counter-client; export COUNTER_SERVER_ID=counter-server; dotnet run

You should see the client and server communicating, with the client sending requests to read and increment the counter value. This is an example of the output messages that you can see:

CounterClient output:

CounterClient Information: 0 : Invoked command 'readCounter' with correlation ID 12345 to topic 'rpc/command-samples/counter-server/readCounter'
CounterClient Information: 0 : Invoked command 'increment' with correlation ID 123456 to topic 'rpc/command-samples/counter-server/increment'
info: CounterClient.RpcCommandRunner[0] called counter.incr 1 with id 12346
info: CounterClient.CounterClient[0] Telemetry received from counter-server: CounterValue=1
info: CounterClient.RpcCommandRunner[0] counter 32 with id 12345
info: CounterClient.RpcCommandRunner[0] Current telemetry count: 32

CounterServer output:

CounterServer Information: 0 : Command executor for 'reset' started.
CounterServer Information: 0 : Command executor for 'increment' started.
CounterServer Information: 0 : Command executor for 'readCounter' started.
CounterServer.CounterService[0] --> Executing Counter.ReadCounter with id 12345 for counter-client
CounterServer.CounterService[0] --> Executed Counter.ReadCounter with id 12345 for counter-client
CounterServer.CounterService[0] --> Executing Counter.Increment with id 12346 for counter-client
CounterServer.CounterService[0] --> Executed Counter.Increment with id 12346 for counter-client
CounterServer Information: 0 : Telemetry sent successfully to the topic 'telemetry/telemetry-samples/counterValue'

The CounterClient sample automatically exits when it's completed. You can also stop the CounterServer sample by pressing Ctrl+C in its terminal.

Configuration summary

MQTT broker configuration

With the installation complete, the cluster contains the following MQTT broker definitions:

Component Type	Name	Description
`Broker`	default	The MQTT broker
`BrokerListener`	default	Provides cluster access to the MQTT Broker
`BrokerListener`	default-external	Provides off-cluster access to the MQTT Broker
`BrokerAuthentication`	default	SAT authentication definition
`BrokerAuthentication`	default-x509	An x509 authentication definition

MQTT broker access

The MQTT broker can be accessed both on-cluster and off-cluster using the connection information as described in the following table. Refer to Connection Settings for information on which environment variables to use when configuration your application.

Note

The hostname when accessing the MQTT broker off-cluster might differ from localhost depending on your setup.

Hostname	Authentication	TLS	On cluster port	Off cluster port
`aio-broker`	SAT	✅	`18883`	-
`localhost`	None	❌	`1883`	`1883`
`localhost`	x509	✅	`8883`	`8883`
`localhost`	SAT	✅	`8884`	`8884`

Development artifacts

As part of the deployment script, the following files are created in the local environment, to facilitate connection and authentication to the MQTT broker. These files are located in the .session directory, found at the repository root.

File	Description
`broker-ca.crt`	The MQTT broker trust bundle required to validate the MQTT broker on ports `8883` and `8884`
`token.txt`	A Service authentication token (SAT) for authenticating with the MQTT broker on `8884`
`client.crt`	A x509 client certificate for authenticating with the MQTT broker on port `8883`
`client.key`	A x509 client private key for authenticating with the MQTT broker on port `8883`

Troubleshooting

Check the troubleshooting guide for common issues in the Azure IoT Operations SDKs GitHub repository: Troubleshooting.

Next steps

In this Quickstart, you set up the Azure IoT Operations SDKs and ran a sample application. To learn more about developing with the SDKs, check out the following resources:

Azure IoT Operations SDKs documentation

Feedback

Was this page helpful?

Last updated on 2025-07-31