Quickstart: Start developing with the Azure IoT Operations SDKs

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.
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 you to access the MQTT broker directly from the developer environment.

Important

The following development environment setup options use K3s running in K3d for a lightweight Kubernetes cluster. They deploy Azure IoT Operations with test settings. For production deployments, choose secure settings.
To use secure settings, 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 development.

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:
After 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

Go to the repository root directory:
```
cd <REPOSITORY ROOT>
```
Run the initialize-cluster.sh script to initialize the cluster and install required dependencies:
```
sudo ./tools/deployment/initialize-cluster.sh
```
This script runs the following commands:
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. This step ensures 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 complete the following steps:

Go 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. Replace 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 runs the following commands:

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 finishes, 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 you deploy Azure IoT Operations, configure it for development. Set up the MQTT broker and authentication methods. Make sure you set the necessary environment variables for your development environment:

Go 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 runs the following commands:
1. Sets up certificate services, if missing
2. Creates root and intermediate CAs for x509 authentication
3. Creates the trust bundle ConfigMap for the Broker to authentication x509 clients
4. Configures BrokerListener and BrokerAuthentication resources for SAT and x509 auth

Testing the installation

To test the setup, use mosquitto_pub to connect to the MQTT broker and 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.

The sample uses the v2 protocol compiler with WoT Thing model files, see the TestThing folder.

Install the .NET 9.0 SDK.
The samples within Azure IoT Operations SDKs GitHub repository read configuration from environment variables. The repository root provides an .env file 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/RPC/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/RPC/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 see the client and server communicating, with the client sending requests to read and increment the counter value. This example shows 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 completes. You can also stop the CounterServer sample by pressing Ctrl+C in its terminal.

Configuration summary

MQTT broker configuration

After you install the software, 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

You can access the MQTT broker both on-cluster and off-cluster by using the connection information described in the following table. For information on which environment variables to use when configuring your application, see Connection Settings.

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 local environment creates the following files to facilitate connection and authentication to the MQTT broker. You can find these files in the .session directory 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`	An x509 client certificate for authenticating with the MQTT broker on port `8883`
`client.key`	An 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.

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 2026-03-09